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

API reference

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.

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, sign_video_url or 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
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).