<!-- Markdown twin of https://pixelvault.dev/docs/api/image-delivery/ -->

[API reference](/docs/api/)

# Image Delivery

The CDN on img.pixelvault.dev serves every image and applies on-the-fly transforms from query parameters. No API call or auth for public images; private images need a signed URL.

-   GET [Serve or transform an image](#serve_image)

## Serve or transform an image

GET `/{project_id}/{filename}`

Host: `https://img.pixelvault.dev`

Fetch an image from the CDN, optionally transformed on the fly via query params, from img.pixelvault.dev (not the API host). No API call or auth for public images; private media needs a signed URL (`token` + `expires`) and an unsigned or expired private request returns 403. Transforms are edge-cached; invalid params are ignored (the original is returned, never an error); SVG sources are served as-is (not transformed). `filename` is `{image_id}.{ext}` and may be preceded by a folder path (e.g. `blog/img_abc123.png`). The effect params (segment, gravity, zoom, blur, sharpen, rotate, flip, brightness, contrast, saturation) apply to your project images, not the anonymous playground. Response headers: `X-PV-Transform` echoes the applied operations; `X-PV-Cache` is HIT|MISS.

The same URL shape serves PDFs (always `Content-Disposition: attachment`), MP4 videos and audio originals. Video and audio support `HEAD` and one `Range: bytes=…` per request (206; unsatisfiable ranges 416); image transform parameters are refused on them.

### Authentication

None. This endpoint is public.

### Path parameters

Path parameters

Name

Type

Required

Description

`project_id`

string

Required

Project ID (omit on custom domains, where it is implied by the host).

`filename`

string

Required

`{image_id}.{ext}`, optionally folder-prefixed (e.g. `blog/img_abc123.png`).

### Query parameters

Query parameters

Name

Type

Required

Description

`size`

string

Optional

Named preset (wins over w/h). s=256w, m=640w, l=1280w, social=1200×630 OG card.

One of: `s`, `m`, `l`, `social`

`w`

integer

Optional

Target width in px, snapped up to a discrete set (16–4000).

`h`

integer

Optional

Target height in px, snapped up to a discrete set (16–4000).

`fit`

string

Optional

Resize mode. `scale-down` (default) never enlarges a smaller source; the others fit the exact box and may upscale.

One of: `scale-down`, `contain`, `cover`, `crop`, `pad`

`fmt`

string

Optional

Output format. `auto` negotiates WebP/AVIF via the Accept header. Omit to keep the source format. `format` is accepted as an alias.

One of: `auto`, `webp`, `avif`, `jpg`, `png`

`q`

string

Optional

Output quality (discrete steps).

One of: `auto`, `60`, `75`, `85`

`segment`

string

Optional

AI background removal → transparent cut-out. Forces PNG unless a solid `background` or `fmt=webp`/`avif` is set. Project images only.

One of: `foreground`

`background`

string

Optional

Fill behind a removed background (or the `fit=pad` area): hex (`%23ffaa00`), rgb()/rgba(), or a common CSS color name.

`gravity`

string

Optional

Crop gravity, with `fit=cover`/`crop`. `face` is face-aware. `XxY` = 0.0–1.0 coordinates.

`zoom`

number

Optional

Face-crop tightness, with `gravity=face`.

min 0 · max 1

`blur`

integer

Optional

Gaussian blur (0–250, snapped to a discrete set). 0 = off.

min 0 · max 250

`sharpen`

number

Optional

Sharpen strength (0–10, snapped). 1 is a good default for downscaled images. 0 = off.

min 0 · max 10

`rotate`

integer

Optional

Rotate in 90° steps.

One of: `90`, `180`, `270`

`flip`

string

Optional

Mirror horizontally, vertically, or both.

One of: `h`, `v`, `hv`

`brightness`

number

Optional

Brightness multiplier, snapped to 0.5/0.75/1.25/1.5/2. 1 = no change.

`contrast`

number

Optional

Contrast multiplier, snapped to 0.5/0.75/1.25/1.5/2. 1 = no change.

`saturation`

number

Optional

Saturation multiplier, snapped to 0/0.5/1.5/2. 0 = grayscale; 1 = no change.

`tile`

string

Optional

Watermark: the CDN path of another RASTER image (png/jpg/webp/avif) in the SAME project: its image\_id.ext (e.g. img\_logo.png), prefixed with its folder if it has one — not the original upload filename. Tiled edge-to-edge at its native size over the base. Bake opacity into the source PNG. Must be your own uploaded raster image — not an external URL and not SVG. A missing or unknown path is ignored (the base is served).

`token`

string

Optional

HMAC signature for a signed (private) URL, from [`sign_image_url`](/docs/api/images/#sign_image_url), [`sign_video_url`](/docs/api/videos/#sign_video_url) or [`sign_audio_url`](/docs/api/audio/#sign_audio_url). When transform params are present they are bound into the signature.

`expires`

integer

Optional

Unix timestamp (seconds) after which a signed URL is rejected.

### Responses

-   200
    
    The image, transformed if params were supplied (or the PDF, video or audio bytes).
    
-   206
    
    Partial content: one byte range of a video or audio original.
    
-   400
    
    `document_transforms_unsupported`, `video_transforms_unsupported`, `audio_transforms_unsupported`: image transform parameters were sent for a PDF, video or audio asset.
    
-   403
    
    Signed URL missing, invalid or expired for private media, or a signed transform could not be served.
    
-   404
    
    Image or project not found.
    
-   410
    
    Image expired or deleted (a placeholder image is returned).
    
-   416
    
    The requested byte range cannot be satisfied (video and audio).
    
-   429
    
    Bandwidth limit exceeded on the free tier (a placeholder image is returned).
    

Request

curlNode.jsPython

```
curl "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=800&fit=cover&fmt=auto" \
  -o image.jpg
```

Response 200

Body: `image/*`. The image, transformed if params were supplied (or the PDF, video or audio bytes).
