URL API v3
URL reference
Every Pixlane request is a plain GET. Transforms go in the first path segment, the path of your original comes after it. There is no SDK to install and nothing to upload.
URL anatomy
https://img.example.com/w_640,h_400,fit_cover,f_auto/catalog/2026/lamp-oak.jpg└── your Pixlane host └── transforms └── path at your origin
Transforms are key_value pairs separated by commas. Order does not matter: Pixlane sorts them before building the cache key, so w_640,q_70 and q_70,w_640 are one cached object, not two.
To fetch the untouched original, use the literal segment raw in place of the transforms.
Your Pixlane host is shown in the dashboard e-mail you received at onboarding. You can also put your own domain in front of it with a CNAME; certificates are issued automatically.
Size and fit
| Key | Values | Default | What it does |
|---|---|---|---|
w_ | 1–8192 | — | Output width in CSS pixels. |
h_ | 1–8192 | — | Output height. With only one of w_/h_ the aspect ratio is kept. |
dpr_ | 1, 1.5, 2, 3 | 1 | Multiplies w_ and h_ for high-density screens. |
fit_ | cover contain inside fill | inside | How the image fills the box when both dimensions are given. |
bg_ | hex colour, e.g. bg_f4f4f0 | transparent or white | Padding colour for fit_contain. |
Pixlane never enlarges an image beyond its original pixel size. Ask for w_4000 on a 1280-pixel original and you get 1280 pixels back, with the real dimensions reported in x-px-size.

640 × 360 · 110 kB

400 × 400 · 55 kB
Gravity
When fit_cover has to cut something off, g_ decides what stays.
| Value | Keeps |
|---|---|
g_center | The middle of the frame. Default. |
g_top g_bottom g_left g_right | The named edge. |
g_auto | The region with the most visual detail, found with a saliency map. Adds about 6 ms on a cache miss. |
g_xy_0.32_0.5 | A focal point you supply, as fractions of width and height. |

the uncropped frame

360 × 480 · 49 kB
Format and quality
| Key | Values | Default | What it does |
|---|---|---|---|
f_ | auto avif webp jpeg png | format of the original | f_auto picks the best format the requesting browser lists in Accept and sets Vary: Accept. |
q_ | 1–100, or auto | auto | Encoder quality. q_auto aims for a fixed perceptual score instead of a fixed number. |
strip_ | all keep-icc none | keep-icc | Metadata handling. GPS data is removed unless you ask for none. |
The effect of q_ is easiest to see when it goes wrong. Both files below are 640 pixels wide.

103 kB

26 kB — look at the sky
Effects
Deliberately few. Pixlane is a delivery service, not an editor.
| Key | Values | What it does |
|---|---|---|
blur_ | 1–100 | Gaussian blur, sigma in pixels of the output. |
mono | flag | Converts to greyscale. |
sharp_ | 1–10 | Unsharp mask after resizing. sharp_2 suits most downscaled photographs. |
lqip | flag | Returns a 32-pixel placeholder of a few hundred bytes for blur-up loading. |

61 kB

11 kB

607 bytes, stretched
Response headers
HTTP/2 200 content-type: image/avif content-length: 39515 cache-control: public, max-age=31536000, immutable vary: Accept etag: "9f2c41d7a0b3" x-px-cache: hit x-px-lane: eu-2 x-px-size: 640x360 x-px-origin-bytes: 2055861 timing-allow-origin: * access-control-allow-origin: *
x-px-cache is one of hit, miss or stale. A miss means the variant was rendered for this request; expect 30–60 ms on top of the origin fetch.
Errors
Errors are JSON with a stable code, served with cache-control: no-store unless noted.
{
"status": 422,
"code": "transform_invalid",
"message": "w_ must be an integer between 1 and 8192",
"param": "w_"
}
| Status | Code | Meaning |
|---|---|---|
| 403 | signature_mismatch | Signing is required for this host and sig_ is missing or wrong. |
| 404 | origin_not_found | Your origin answered 404. Cached for 60 seconds. |
| 415 | source_unsupported | The original is not an image we can decode. |
| 422 | transform_invalid | Unknown key or a value out of range. param names it. |
| 429 | variant_budget | More than 400 new variants of one original in an hour. Usually a missing signature. |
| 504 | origin_timeout | Your origin took longer than 10 seconds. |
Signed URLs
Turn signing on per host. The signature is the first 16 hex characters of an HMAC-SHA256 over the sorted transform string and the path, appended as a transform.
# sign.sh — needs openssltransforms="f_auto,q_auto,w_640"# already sortedpath="catalog/2026/lamp-oak.jpg" sig=$(printf '%s/%s' "$transforms" "$path" \ | openssl dgst -sha256 -hmac "$PIXLANE_KEY" -hex | cut -c18-33) echo "https://img.example.com/$transforms,sig_$sig/$path"
Keys can be rotated without downtime: two keys are valid at once, and the response header x-px-key tells you which one matched.
Limits
- Originals up to 50 MB and 100 megapixels. Animated GIF and WebP up to 500 frames.
- Output is capped at 8192 pixels on the long edge.
- Source formats: JPEG, PNG, WebP, AVIF, HEIC, GIF, TIFF. SVG is passed through untouched.
- Originals are re-validated against your origin every 24 hours using
ETagorLast-Modified; purge sooner by addingv_with any value.