Skip to content
Read the docs

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

KeyValuesDefaultWhat 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, 31Multiplies w_ and h_ for high-density screens.
fit_cover contain inside fillinsideHow the image fills the box when both dimensions are given.
bg_hex colour, e.g. bg_f4f4f0transparent or whitePadding 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.

Crates of oranges, lemons and pomegranates on a market stall
w_640
640 × 360 · 110 kB
The same stall cropped to a square
w_400,h_400,fit_cover
400 × 400 · 55 kB

Gravity

When fit_cover has to cut something off, g_ decides what stays.

ValueKeeps
g_centerThe middle of the frame. Default.
g_top g_bottom g_left g_rightThe named edge.
g_autoThe region with the most visual detail, found with a saliency map. Adds about 6 ms on a cache miss.
g_xy_0.32_0.5A focal point you supply, as fractions of width and height.
Striped lighthouse on a rocky headland
w_640
the uncropped frame
Portrait crop that keeps the lighthouse in frame
w_360,h_480,fit_cover,g_left
360 × 480 · 49 kB

Format and quality

KeyValuesDefaultWhat it does
f_auto avif webp jpeg pngformat of the originalf_auto picks the best format the requesting browser lists in Accept and sets Vary: Accept.
q_1–100, or autoautoEncoder quality. q_auto aims for a fixed perceptual score instead of a fixed number.
strip_all keep-icc nonekeep-iccMetadata 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.

Harbour at normal quality
w_640,q_auto,f_jpeg
103 kB
Harbour at quality 25, with visible blocking in the sky
w_640,q_25,f_jpeg
26 kB — look at the sky

Effects

Deliberately few. Pixlane is a delivery service, not an editor.

KeyValuesWhat it does
blur_1–100Gaussian blur, sigma in pixels of the output.
monoflagConverts to greyscale.
sharp_1–10Unsharp mask after resizing. sharp_2 suits most downscaled photographs.
lqipflagReturns a 32-pixel placeholder of a few hundred bytes for blur-up loading.
Mountain road in greyscale
w_640,mono
61 kB
Mountain road, heavily blurred
w_640,blur_12
11 kB
Tiny blurred placeholder of the harbour photograph
lqip
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_"
}
StatusCodeMeaning
403signature_mismatchSigning is required for this host and sig_ is missing or wrong.
404origin_not_foundYour origin answered 404. Cached for 60 seconds.
415source_unsupportedThe original is not an image we can decode.
422transform_invalidUnknown key or a value out of range. param names it.
429variant_budgetMore than 400 new variants of one original in an hour. Usually a missing signature.
504origin_timeoutYour 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 openssl
transforms="f_auto,q_auto,w_640"            # already sorted
path="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 ETag or Last-Modified; purge sooner by adding v_ with any value.