<!-- Markdown twin of https://pixelvault.dev/docs/transforms/ -->

# 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](/images/).

```
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](/docs/private-media/) signed URLs can't be transformed: the signature binds the exact URL.

The delivery endpoint is documented in the reference as [Image delivery](/docs/api/image-delivery/#serve_image). Agents can build transform URLs with the MCP `transform_image` tool.

## Next steps

-   [Images in email](/docs/guides/email-images/): serve 2× images for retina.
-   [Image transforms for AI agents](/blog/image-transforms-for-ai-agents/).
