Base path: /image
Generates placeholder images on the fly. The base graphic is built as SVG and then, for raster formats, converted with sharp.
GET /image/{name}_{width}x{height}.ext
Returns a generated placeholder image containing the requested dimensions and, optionally, a label.
Path parameters
| Parameter | Required | Description |
|---|---|---|
name |
yes | Label drawn under the dimensions. Use _ for an empty label (e.g. /_200x100.png). Max 100 characters. |
width |
yes | Image width in pixels, 1–4000. |
height |
yes | Image height in pixels, 1–4000. |
ext |
yes | Output format: jpg, jpeg, png, webp, gif or svg. |
The path shape is {name}_{width}x{height}.{ext}. The underscore before the width is a separator: logo_200x100.png produces a 200×100 image with the label logo.
Responses
| Status | Body |
|---|---|
200 |
The generated image (Content-Type depends on ext) |
400 |
Invalid dimensions. when width/height are out of range |
400 |
Invalid extension. when extension is not known |
Successful responses include Cache-Control: public, max-age=86400 and X-Content-Type-Options: nosniff.
Content types
ext |
Content-Type |
|---|---|
svg |
image/svg+xml |
png |
image/png |
webp |
image/webp |
gif |
image/gif |
jpg, jpeg |
image/jpeg |
Logging
Requests are logged through the winston logger under the Image module:
trace: incoming request (name, width, height, ext) and successful generation (ext, byte size).warn: invalid extension or out-of-range dimensions.error: raster generation failures (with the underlying error).
Examples
SVG placeholder:
curl "$BASE_URL/image/logo_200x100.svg"
PNG placeholder:
curl -o logo.png "$BASE_URL/image/logo_200x100.png"
JPEG placeholder:
curl -o placeholder.jpg "$BASE_URL/image/placeholder_600x400.jpg"
Empty label:
curl -o blank.webp "$BASE_URL/image/_300x300.webp"
Invalid dimensions (out of range):
curl -i "$BASE_URL/image/logo_5000x100.png"
HTTP/1.1 400 Bad Request
Invalid dimensions.