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}
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
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Required | Project ID (omit on custom domains, where it is implied by the host). |
filename | string | Required |
|
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. |
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. |
fmt | string | Optional | Output format. |
q | string | Optional | Output quality (discrete steps). |
segment | string | Optional | AI background removal → transparent cut-out. Forces PNG unless a solid |
background | string | Optional | Fill behind a removed background (or the |
gravity | string | Optional | Crop gravity, with |
zoom | number | Optional | Face-crop tightness, with |
blur | integer | Optional | Gaussian blur (0–250, snapped to a discrete set). 0 = off. |
sharpen | number | Optional | Sharpen strength (0–10, snapped). 1 is a good default for downscaled images. 0 = off. |
rotate | integer | Optional | Rotate in 90° steps. |
flip | string | Optional | Mirror horizontally, vertically, or both. |
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 |
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).
curl "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=800&fit=cover&fmt=auto" \
-o image.jpg