Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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

ParamValuesNotes
sizes · m · l · social · square · portraitNamed 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, hpixelsWidth/height. Snapped up to a discrete set (16–4000) for cache efficiency.
fitscale-down · contain · cover · crop · padDefault scale-down never enlarges a smaller source; cover/crop/contain/pad fit the exact box and may upscale.
fmtwebp · avif · jpg · png · autoauto 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.
qauto · 60 · 75 · 85Output quality. Default auto.
segmentforegroundRemoves 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).
backgroundhex · rgb()/rgba() · named colorFills behind a removed background (or the fit=pad area). Hex (%23ffaa00), rgb()/rgba(), or a common CSS color name (white, black, …).
gravityauto · face · left · right · top · bottom · XxYWhere to crop toward, with fit=cover/crop. face is face-aware.
zoom0.0–1.0Face-crop tightness — with gravity=face (which needs fit=cover/crop).
blur0–250Gaussian blur. Snapped to a discrete set. 0 = off.
sharpen0–10Sharpen strength. Snapped to a discrete set. 1 is a good default for downscaled images; 0 = off.
rotate90 · 180 · 270Rotate in 90° steps.
fliph · v · hvMirror horizontally, vertically, or both.
brightnessmultiplierSnapped to 0.5 · 0.75 · 1.25 · 1.5 · 2. 1 = no change.
contrastmultiplierSnapped to 0.5 · 0.75 · 1.25 · 1.5 · 2. 1 = no change.
saturationmultiplierSnapped to 0 · 0.5 · 1.5 · 2. 0 = grayscale; 1 = no change.
tileimage pathWatermark. 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