Image transforms
Every CDN URL supports on-the-fly transforms via query params — no extra API call. The edge resizes, crops, and converts the image, then caches the result globally. Available on all plans. See every param on live images on the Images page.
https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=400&fit=cover&fmt=webp Parameters
| Param | Values | Notes |
|---|---|---|
| size | s · m · l · social · square · portrait | Named preset. s=256w, m=640w, l=1280w, social=1200×630 (OG card), square=1080×1080, portrait=1080×1350. square, portrait and social all fall inside Instagram and TikTok carousel limits (ratio 4:5 to 1.91:1, width ≤1440) — prefer them over w/h, which snap to a discrete set and can land outside the ratio you asked for. |
| w, h | pixels | Width/height. Snapped up to a discrete set (16–4000) for cache efficiency. |
| fit | scale-down · contain · cover · crop · pad | Default scale-down never enlarges a smaller source; cover/crop/contain/pad fit the exact box and may upscale. |
| fmt | webp · avif · jpg · png · auto | auto negotiates WebP/AVIF from the Accept header. With no fmt, or when the client advertises neither, Cloudflare picks the output type — an opaque PNG comes back as JPEG, alpha keeps PNG — so it is not guaranteed to match the source. Pass an explicit fmt when the consumer requires one. |
| q | auto · 60 · 75 · 85 | Output quality. Default auto. |
| segment | foreground | Removes the background (AI cut-out) → transparent output. Output is PNG unless you request fmt=webp/avif. A solid background fills the removed area, but fmt=jpg isn't available with segment (you get PNG). |
| background | hex · rgb()/rgba() · named color | Fills behind a removed background (or the fit=pad area). Hex (%23ffaa00), rgb()/rgba(), or a common CSS color name (white, black, …). |
| gravity | auto · face · left · right · top · bottom · XxY | Where to crop toward, with fit=cover/crop. face is face-aware. |
| zoom | 0.0–1.0 | Face-crop tightness — with gravity=face (which needs fit=cover/crop). |
| blur | 0–250 | Gaussian blur. Snapped to a discrete set. 0 = off. |
| sharpen | 0–10 | Sharpen strength. Snapped to a discrete set. 1 is a good default for downscaled images; 0 = off. |
| rotate | 90 · 180 · 270 | Rotate in 90° steps. |
| flip | h · v · hv | Mirror horizontally, vertically, or both. |
| brightness | multiplier | Snapped to 0.5 · 0.75 · 1.25 · 1.5 · 2. 1 = no change. |
| contrast | multiplier | Snapped to 0.5 · 0.75 · 1.25 · 1.5 · 2. 1 = no change. |
| saturation | multiplier | Snapped to 0 · 0.5 · 1.5 · 2. 0 = grayscale; 1 = no change. |
| tile | image path | Watermark. The CDN path of another raster image in the same project (png/jpg/webp/avif): its image_id.ext, e.g. img_logo.png, prefixed with its folder if it has one. That's the last part of the image's URL; the original upload filename does not work. Tiled edge-to-edge at native size. Bake opacity into the source PNG. Must be your own image — not an external URL, not SVG. A missing or unknown path is ignored. |
Responsive images
Because a transform is just a URL, a srcset needs no build step:
<img
src="https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=800&fmt=auto"
srcset="https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=400&fmt=auto 400w,
https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=800&fmt=auto 800w,
https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=1600&fmt=auto 1600w"
sizes="(max-width: 800px) 100vw, 800px"
alt="Product screenshot" /> Keyed public raster uploads also return optimized_url (url plus ?fmt=auto&q=85), a ready-made WebP/AVIF variant.
Background removal
Background removal isolates the subject and makes the background transparent:
# transparent PNG cut-out
.../img_abc123.jpg?segment=foreground
# subject on a white fill
.../img_abc123.jpg?segment=foreground&background=white
# portrait cut-out
.../img_abc123.jpg?w=400&h=400&fit=cover&gravity=face&segment=foreground Effects
Effects (blur, sharpen, rotate, flip, brightness, contrast, saturation) stack and combine with resize/crop:
.../img_abc123.jpg?blur=30 # blurred
.../img_abc123.jpg?saturation=0 # grayscale
.../img_abc123.jpg?rotate=90&flip=h # rotated + mirrored
.../img_abc123.jpg?w=800&blur=30&saturation=0 # grayscale, blurred 800px thumbnail Watermark
Watermark tiles one of your own images over the base — upload the watermark once, then reference it by its image id and extension:
.../img_abc123.jpg?tile=img_logo.png # your logo, tiled at native size
.../img_abc123.jpg?w=1200&tile=img_wm123.png # resized + watermarked Rules and limits
- Background removal, face-crop, effects, and watermark (
segment,gravity,zoom,blur,sharpen,rotate,flip,brightness,contrast,saturation,tile) apply to your project images, not the anonymous playground. - Invalid params are ignored — you get the original image back, never an error.
- SVG sources are served as-is (not transformed). PDFs reject image transform parameters.
- Private signed URLs can't be transformed: the signature binds the exact URL.
The delivery endpoint is documented in the reference as Image delivery. Agents can build transform URLs with the MCP transform_image tool.
Next steps
- Images in email: serve 2× images for retina.
- Image transforms for AI agents.