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

[API reference](/docs/api/)

# Images

Upload, import, generate, edit, describe, list and delete images and PDF documents. Every image gets a permanent CDN URL on img.pixelvault.dev that supports on-the-fly transforms; private images are served behind signed URLs.

-   [The Image object](#object)
-   GET [List images](#list_images)
-   POST [Upload an image or PDF](#upload_image)
-   GET [List the project's AI tags with counts](#list_image_tags)
-   POST [Start an AI description for an existing image](#describe_image)
-   GET [Get image details](#get_image)
-   PATCH [Replace image metadata](#update_image_metadata)
-   DELETE [Delete image](#delete_image)
-   POST [Generate an image from a text prompt](#generate_image)
-   POST [Edit an image with a natural-language instruction](#edit_image)
-   POST [Batch upload into a collection](#batch_upload)
-   POST [Mint a signed (private) URL](#sign_image_url)

## The Image object

A hosted image or PDF document. Upload responses ([`upload_image`](/docs/api/images/#upload_image), [`generate_image`](/docs/api/images/#generate_image), [`edit_image`](/docs/api/images/#edit_image)) also carry `visibility` and, for private images, `signed_expires` (Unix seconds when the signed `url` stops working).

### Properties

The Image object properties

Property

Type

Description

`id`

string

Image id (`img_` prefix). Keyless uploads return a temporary `anon_` id that cannot be listed, read or deleted.

`kind`

string

PDF uploads are `document`; renderable image formats are `image`.

One of: `image`, `document`

`url`

string (uri)

CDN URL. Images support on-the-fly transforms via query params: size (s|m|l|social), w, h (px, snapped to a discrete set), fit (scale-down|contain|cover|crop|pad), fmt (auto|webp|avif|jpg|png), q (auto|60|75|85), segment (foreground — AI background removal, transparent PNG), background (fill: hex, rgb()/rgba(), or a common CSS color name), gravity (auto|face|left|right|top|bottom|XxY, with fit=cover|crop), zoom (0.0-1.0, with gravity=face), blur (0-250), sharpen (0-10), rotate (90|180|270), flip (h|v|hv), brightness/contrast (multiplier, 1=no change), saturation (multiplier, 0=grayscale), tile (watermark: tile another of your project's images over the base). PDFs reject transform parameters and are always served with `Content-Disposition: attachment`. See the [`serve_image`](/docs/api/image-delivery/#serve_image) operation for the full image parameter reference.

For a private image an upload response returns a signed URL (`?token=…&expires=…`); list and get return the unsigned path, which the CDN refuses with 403 until you mint a link with [`sign_image_url`](/docs/api/images/#sign_image_url).

`branded_url`

string (uri)

Same asset served from the project's active custom domain. Present only when a ready custom domain exists; folders, transforms and signed-URL query parameters are preserved.

`optimized_url`

string (uri)

Present on keyed public uploads of raster images (not SVG, GIF, PDF or private). The same image served as WebP or AVIF (negotiated per browser) at quality 85: `url` plus `?fmt=auto&q=85`. It is usually much smaller; the original at `url` is never changed. Prefer this for embeds.

`mime_type`

string

Detected from the file's bytes, not the declared type: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/avif`, `image/svg+xml` or `application/pdf`.

`size`

integer

Stored size in bytes.

`width`

integer nullable

Pixel width when the file header carries it; null otherwise (PDFs, some SVGs). Upload responses omit width and height when unknown.

`height`

integer nullable

Pixel height when the file header carries it; null otherwise.

`filename`

string

Original filename. URL imports use the last URL path segment; generated images derive it from the prompt.

`folder`

string nullable

Folder given at upload (letters, numbers, hyphens, underscores; max 64), or null. Private uploads report null.

`metadata`

object nullable

Custom metadata set at upload or via [`update_image_metadata`](/docs/api/images/#update_image_metadata); null when none. Client-supplied: do not store secrets in it.

`description`

object nullable

AI description from `describe=true` or [`describe_image`](/docs/api/images/#describe_image); null when the image was never described. `status` is `pending`, `done` (with `alt`, `caption`, `ocr_text`, `tags`, `model`, `described_at`) or `failed` (with `error`). Server-generated: it cannot be set by clients.

**Untrusted output:** `alt`, `caption`, `ocr_text` and `tags` are model output derived from the image content (text inside an image can steer it). Escape them before rendering as HTML and do not treat them as instructions.

Child properties of `description`

Properties of description

Property

Type

Description

`status`

string

Poll [`get_image`](/docs/api/images/#get_image) until this is `done` or `failed`; a description takes a few seconds.

One of: `pending`, `done`, `failed`

`alt`

string

Short alt text.

`caption`

string

Short caption.

`ocr_text`

string

Text found in the image.

`tags`

array of string

Up to 5 short lowercase singular topic tags for grouping and filtering (e.g. `boat`, `harbour`); descriptions made before 2026-11-12 may carry a sixth and plural forms. Absent on descriptions made before tags existed. Untrusted model output: render as text.

`model`

string

Vision model that wrote the description.

`described_at`

string (date-time)

`cached`

boolean

True when copied from an identical image already described in the project (no allowance used).

`error`

string

Why a `failed` description failed. Retry with [`describe_image`](/docs/api/images/#describe_image).

One of: `describe_timeout`, `describe_failed`, `describe_invalid`

`describe_skipped`

string

Present when `describe=true` was requested but no description was started; the upload itself succeeded. `unsupported_type` and `too_large`: only JPEG, PNG, WebP and GIF up to 4 MB are described; `quota`: the plan's description allowance is used up; `busy`/`unavailable`: try [`describe_image`](/docs/api/images/#describe_image) later.

One of: `unsupported_type`, `too_large`, `secret_key_required`, `email_unverified`, `quota`, `busy`, `unavailable`

`created_at`

string (date-time)

`expires_in`

integer

Present only on auto-expiring uploads: seconds until deletion (the requested TTL, or the remaining lifetime on a replay). Keyless uploads report 2592000 (30 days).

`temporary`

boolean

Present (true) only on auto-expiring uploads, including every keyless upload.

`deduplicated`

boolean

Present (true) when `dedupe=true` matched an existing image with identical bytes and nothing new was stored or billed.

`replayed`

boolean

Present (true) when an `Idempotency-Key` repeat returned the original upload's image.

The Image object

```
{
  "id": "img_abc123",
  "kind": "image",
  "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
  "branded_url": "https://media.example.com/img_abc123.jpg",
  "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
  "mime_type": "image/jpeg",
  "size": 245782,
  "width": 1920,
  "height": 1080,
  "filename": "photo.jpg",
  "folder": "blog",
  "metadata": {
    "env": "prod",
    "run": "42"
  },
  "description": {
    "status": "done",
    "alt": "A red fishing boat moored in a small harbour at sunset",
    "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
    "ocr_text": "HARBOUR MASTER",
    "tags": [
      "boat",
      "harbour",
      "sunset"
    ],
    "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
    "described_at": "2026-11-16T12:00:04.000Z",
    "cached": false,
    "error": "describe_timeout"
  },
  "describe_skipped": "unsupported_type",
  "created_at": "2026-11-16T12:00:00.000Z",
  "expires_in": 86400,
  "temporary": true,
  "deduplicated": true,
  "replayed": true
}
```

## List images

GET `/v1/images`

A page of the project's images and PDF documents, newest first (best match first when `q` is set). Filters combine with AND. `q` and `tag` look at the AI description, so they only match images that have one (see [`describe_image`](/docs/api/images/#describe_image)). Video and audio assets are listed by [`list_videos`](/docs/api/videos/#list_videos) and [`list_audio`](/docs/api/audio/#list_audio).

URLs are unsigned: a private image's `url` is refused by the CDN until you mint a link with [`sign_image_url`](/docs/api/images/#sign_image_url).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Query parameters

Query parameters

Name

Type

Required

Description

`page`

integer

Optional

Page number, from 1.

Default: `1`

min 1

`per_page`

integer

Optional

Images per page (max 100).

Default: `20`

min 1 · max 100

`collection_id`

string

Optional

Only images in this collection.

`q`

string

Optional

Full-text search over the AI description (alt text, caption, OCR text), best match first. Words are ANDed; `"quoted phrases"` and `-word` work. Max 200 characters. Not plan-gated. Images that were never described are not matched.

max length 200

`tag`

string

Optional

Only images carrying this AI tag (one tag, e.g. `boat`; see [`list_image_tags`](/docs/api/images/#list_image_tags) for the tags in use). Matched in the lowercase form tags are stored in. Images that were never described have no tags.

max length 40

`metadata`

string

Optional

JSON object; returns images whose custom metadata contains every key/value pair (e.g. `{"env":"prod"}`). Typed values match exactly; nested objects match by containment. Conflicting duplicates (the same key with different values across `metadata` and `meta[key]`) return 400.

`meta[key]`

string

Optional

Shorthand string match on one metadata key, e.g. `?meta[env]=prod`. Use it once per key, for several different keys; combines (AND) with `metadata`.

### Responses

-   200
    
    A page of images
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): malformed `metadata` filter, conflicting `meta[key]` values, `q` longer than 200 characters, or an invalid `tag`.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl "https://api.pixelvault.dev/v1/images?per_page=20" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": [
    {
      "id": "img_abc123",
      "kind": "image",
      "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
      "branded_url": "https://media.example.com/img_abc123.jpg",
      "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
      "mime_type": "image/jpeg",
      "size": 245782,
      "width": 1920,
      "height": 1080,
      "filename": "photo.jpg",
      "folder": "blog",
      "metadata": {
        "env": "prod",
        "run": "42"
      },
      "description": {
        "status": "done",
        "alt": "A red fishing boat moored in a small harbour at sunset",
        "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
        "ocr_text": "HARBOUR MASTER",
        "tags": [
          "boat",
          "harbour",
          "sunset"
        ],
        "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
        "described_at": "2026-11-16T12:00:04.000Z",
        "cached": false,
        "error": "describe_timeout"
      },
      "describe_skipped": "unsupported_type",
      "created_at": "2026-11-16T12:00:00.000Z",
      "expires_in": 86400,
      "temporary": true,
      "deduplicated": true,
      "replayed": true
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}
```

## Upload an image or PDF

POST `/v1/images`

Upload a file and receive a CDN URL. Supported formats: JPEG, PNG, GIF, WebP, AVIF, SVG and PDF, detected from the bytes. Images return `kind: "image"` and `width`/`height` when the file header carries them. PDFs return `kind: "document"`, always download with `Content-Disposition: attachment`, are marked `X-Robots-Tag: noindex`, and reject image transforms. Prefer a browser? Use the free [PDF-to-URL tool](https://pixelvault.dev/tools/pdf-to-url/).

Send `multipart/form-data` with a `file`, or, with an API key, `application/json` with `{ "url": "https://…" }` to import from an https URL: the file is fetched server-side (https only, public hosts, up to 3 redirects, 10-second timeout) and stored. Maximum file size: 5 MB on Free and keyless, 10 MB on Starter, 15 MB on Pro.

**Keyless quickstart:** this endpoint works without an API key. Keyless uploads are temporary (`temporary: true`, `expires_in` of 30 days, plus a top-level `hint`), are limited to 20 per hour per IP, and ignore `metadata`, `describe`, `dedupe` and `Idempotency-Key`. For a managed image without that fixed expiration, re-upload with an `Authorization: Bearer` key and use the new URL; the anonymous URL still expires, and free-plan retention applies to the new upload.

**Publishable keys** (`pv_pub_`) may upload files only (no URL import, no private uploads) from a browser whose `Origin` exactly matches one of the key's allowed origins.

**Auto-expiring uploads:** pass `expires_in` (60–2,592,000 seconds, 1 minute to 30 days) as a form field or JSON field. Deletion runs in an hourly sweep, so removal can lag the TTL by up to about two hours. The response echoes `expires_in` and `temporary: true`.

**Retry-safe uploads:** send an `Idempotency-Key` and a retry after a timeout returns the original image (HTTP 200, `replayed: true`) instead of storing a second copy. Or send `dedupe=true` to reuse an existing image with identical bytes (HTTP 200, `deduplicated: true`). The two cannot be combined.

**Custom metadata:** attach a JSON object (up to 50 top-level keys, 4 KB) with `metadata`, replace it later with [`update_image_metadata`](/docs/api/images/#update_image_metadata), and filter [`list_images`](/docs/api/images/#list_images) by it. Do not store secrets in it.

**AI descriptions:** `describe=true` writes alt text, a caption, OCR text and tags in the background; see [`describe_image`](/docs/api/images/#describe_image).

**Private images:** `visibility=private` (secret key) stores the image behind a signed URL; the response `url` is signed for `sign_expires_in` seconds and carries `signed_expires`. The free plan includes 100 private assets per project; paid plans are unlimited.

**Optimized URL:** keyed public uploads of raster images (not SVG, GIF or private) also return `optimized_url`, the same image as WebP/AVIF at quality 85.

The response also carries `visibility`. A successful new upload emits the `media.created` webhook (`source` `upload` or `url_import`).

### Authentication

Optional. Works without a key; send a secret or publishable API key as `Authorization: Bearer <key>` for keyed behaviour.

### Headers

Headers

Name

Type

Required

Description

`Idempotency-Key`

string

Optional

Keyed uploads; up to 255 non-space printable ASCII characters. A repeat with the same key and the same bytes returns the original image (200, `replayed: true`); the same key with different bytes, a different visibility, or after the image expired returns 422 [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse). A replay describes the stored image, not the retry: the `metadata` and `describe` you send are ignored. Keys are scoped to the project and live as long as the image. Cannot be combined with `dedupe`.

max length 255 · pattern ^\[\\x21-\\x7e\]+$

### Request body (multipart/form-data)

`multipart/form-data`, required

Request body (multipart/form-data)

Name

Type

Required

Description

`file`

file

Required

Image or PDF file. Max 5 MB on Free and keyless, 10 MB on Starter, 15 MB on Pro.

`folder`

string

Optional

Optional folder (letters, numbers, hyphens, underscores; max 64). It becomes part of the CDN path. Ignored for private images.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`visibility`

string

Optional

`private` (secret key only) stores the image behind a signed URL and the response `url` is signed.

One of: `public`, `private`

Default: `public`

`sign_expires_in`

integer

Optional

Signature lifetime in seconds for a private upload's returned URL. Mint fresh links later with [`sign_image_url`](/docs/api/images/#sign_image_url).

Default: `3600`

min 60 · max 2592000

`expires_in`

integer

Optional

Optional auto-expiry in seconds (60–2592000). The image is deleted by an hourly sweep after this time, so removal can lag the TTL by up to about two hours; the response echoes `expires_in` and `temporary: true`. Omit for no fixed expiry (keyed uploads).

min 60 · max 2592000

`metadata`

object

Optional

Optional custom metadata (JSON object, max 50 top-level keys / 4 KB serialized) stored with the image and filterable via [`list_images`](/docs/api/images/#list_images) (`metadata=` or `meta[key]=`). Multipart: send it as a JSON string. Keyed uploads only (ignored on keyless uploads), and ignored when `dedupe` or an `Idempotency-Key` replay returns an existing image: use [`update_image_metadata`](/docs/api/images/#update_image_metadata) to change it. NUL characters and unpaired surrogates are rejected. Client-supplied; do not store secrets.

`describe`

boolean

Optional

Keyed uploads. When true, an AI description (alt text, caption, OCR text, tags) is generated for the new image in the background and stored as `description`; poll [`get_image`](/docs/api/images/#get_image) until `description.status` is `done`. Plan-gated: Free 20 in total, Starter 1,000 a month, Pro 10,000 a month. Needs a secret key and a verified email. Over quota, unsupported type (JPEG, PNG, WebP and GIF up to 4 MB only) or a busy service never fail the upload: the response carries `describe_skipped` instead. Identical bytes already described in the project are reused at no charge. Ignored when dedupe or an Idempotency-Key replay returns an existing image.

Default: `false`

`dedupe`

boolean

Optional

Keyed uploads. When true and the project already has an image with identical bytes, the same visibility, folder and a lifetime at least as long as requested, that image is returned (200, `deduplicated: true`) and no upload is stored or counted. Best-effort: simultaneous uploads of the same bytes can each be stored. Cannot be combined with `Idempotency-Key`.

Default: `false`

### Request body (application/json)

`application/json`, required

Request body (application/json)

Name

Type

Required

Description

`url`

string (uri)

Required

Source image or PDF URL to import (https only, public host). Requires an API key (not a publishable key).

`folder`

string

Optional

Optional folder (letters, numbers, hyphens, underscores; max 64). Ignored for private images.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`visibility`

string

Optional

`private` stores the image behind a signed URL and the response `url` is signed.

One of: `public`, `private`

Default: `public`

`sign_expires_in`

integer

Optional

Signature lifetime in seconds for a private upload's returned URL.

Default: `3600`

min 60 · max 2592000

`expires_in`

integer

Optional

Optional auto-expiry in seconds (60–2592000). The image is deleted by an hourly sweep after this time, so removal can lag the TTL by up to about two hours; the response echoes `expires_in` and `temporary: true`.

min 60 · max 2592000

`metadata`

object

Optional

Optional custom metadata (JSON object, max 50 top-level keys / 4 KB serialized), filterable via [`list_images`](/docs/api/images/#list_images). Ignored when `dedupe` or an `Idempotency-Key` replay returns an existing image. NUL characters and unpaired surrogates are rejected. Client-supplied; do not store secrets.

`describe`

boolean

Optional

When true, an AI description is generated in the background (see the multipart field of the same name).

Default: `false`

`dedupe`

boolean

Optional

When true and the project already has an image with identical bytes, the same visibility, folder and a lifetime at least as long as requested, that image is returned (200, `deduplicated: true`) and nothing is stored or counted. Cannot be combined with `Idempotency-Key`.

Default: `false`

### Responses

-   200
    
    Nothing new was stored: an `Idempotency-Key` replay or a `dedupe` match. The image carries `replayed` or `deduplicated`.
    
-   201
    
    Image uploaded
    
-   400
    
    [`missing_file`](/docs/errors/#missing_file): no `file` field. [`invalid_file`](/docs/errors/#invalid_file): the bytes are not a supported image or PDF. [`invalid_json`](/docs/errors/#invalid_json) / [`missing_url`](/docs/errors/#missing_url): bad URL-import body. [`validation_error`](/docs/errors/#validation_error): bad `expires_in`, `visibility`, `sign_expires_in`, `metadata`, `describe`, `dedupe` or `Idempotency-Key`, or `dedupe` combined with `Idempotency-Key`. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name. URL imports: [`invalid_url`](/docs/errors/#invalid_url), [`unsupported_scheme`](/docs/errors/#unsupported_scheme) (not https), [`blocked_host`](/docs/errors/#blocked_host) (private or internal address), [`url_fetch_failed`](/docs/errors/#url_fetch_failed) (network error, timeout, too many redirects or a non-2xx response), [`url_too_large`](/docs/errors/#url_too_large).
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): URL import without a key. [`invalid_api_key`](/docs/errors/#invalid_api_key): the `Authorization` header is present but malformed, unknown or revoked (an absent header uploads anonymously).
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached): the monthly upload quota is used up. [`storage_limit_reached`](/docs/errors/#storage_limit_reached): the storage quota is full. [`private_limit_reached`](/docs/errors/#private_limit_reached): the free plan's 100 private assets are used. Plan ceilings, not rate limits: retrying cannot succeed until you delete media, upgrade, or the month resets.
    
-   403
    
    Publishable keys: [`origin_required`](/docs/errors/#origin_required) (no `Origin` header), [`origin_not_allowed`](/docs/errors/#origin_not_allowed), [`no_allowed_origins`](/docs/errors/#no_allowed_origins), [`url_import_forbidden`](/docs/errors/#url_import_forbidden), [`private_forbidden`](/docs/errors/#private_forbidden). [`email_verification_required`](/docs/errors/#email_verification_required): an unverified account already stores 5 images. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than the plan's per-file cap (5 MB Free and keyless, 10 MB Starter, 15 MB Pro).
    
-   422
    
    [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse): the `Idempotency-Key` was already used with different image bytes or a different visibility, or its image has expired. Use a new key.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): keyed uploads share the per-key limit (60 per minute, 300 per minute per project); keyless uploads are limited to 20 per hour per IP plus a short burst guard. Honour `Retry-After`. [`account_budget_exceeded`](/docs/errors/#account_budget_exceeded): keyless uploads are temporarily paused.
    

Request

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@photo.jpg" \
  -F "folder=blog" \
  -F "expires_in=86400" \
  -F 'metadata={"env":"prod"}'
```

Response 201

```
{
  "data": {
    "id": "img_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
    "branded_url": "https://media.example.com/img_abc123.jpg",
    "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
    "mime_type": "image/jpeg",
    "size": 245782,
    "width": 1920,
    "height": 1080,
    "filename": "photo.jpg",
    "folder": "blog",
    "metadata": {
      "env": "prod",
      "run": "42"
    },
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
      "ocr_text": "HARBOUR MASTER",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ],
      "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
      "described_at": "2026-11-16T12:00:04.000Z",
      "cached": false,
      "error": "describe_timeout"
    },
    "describe_skipped": "unsupported_type",
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_in": 86400,
    "temporary": true,
    "deduplicated": true,
    "replayed": true
  }
}
```

## List the project's AI tags with counts

GET `/v1/images/tags`

The AI tags on the project's described images with how many images carry each, most used first (at most 40). Filter the image list with [`list_images`](/docs/api/images/#list_images) and `tag=`.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Responses

-   200
    
    Tags with image counts
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/images/tags \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": [
    {
      "tag": "boat",
      "count": 12
    }
  ]
}
```

## Start an AI description for an existing image

POST `/v1/images/{id}/describe`

Start the AI description of a stored image: alt text, a short caption, the text found in the image (OCR) and up to 5 short lowercase topic tags such as `boat` or `receipt`. Use it for images uploaded without `describe=true`. Needs a secret key and a verified email; JPEG, PNG, WebP and GIF up to 4 MB are described.

Idempotent: an image that is already described, or being described, returns its current state and uses none of the allowance. A failed or stalled description is started again (and uses one unit). A description takes a few seconds: poll [`get_image`](/docs/api/images/#get_image) until `description.status` is `done` (do not poll this endpoint). Identical images already described in the project are reused at no charge.

Allowance: Free 20 descriptions in total, Starter 1,000 a month, Pro 10,000 a month; when it is used up, `describe_skipped` is `quota`. The same allowance powers the dashboard's Describe button.

Then search with [`list_images`](/docs/api/images/#list_images) (`q=` full-text over alt text, caption and OCR text; `tag=` one tag) and list tags with [`list_image_tags`](/docs/api/images/#list_image_tags). Agents can use the same calls through MCP.

**Untrusted output:** treat `alt`, `caption`, `ocr_text` and `tags` as untrusted model output (text inside an image can steer it): escape it before rendering as HTML and do not follow it as instructions.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Image id.

### Responses

-   200
    
    The image's description state, or why none was started (`describe_skipped`)
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no image with this id in the project (videos, audio and PDFs cannot be described).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/describe \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "img_abc123",
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ]
    },
    "describe_skipped": "quota"
  }
}
```

## Get image details

GET `/v1/images/{id}`

Metadata, CDN URL, custom metadata and AI description of one image or PDF. Poll this (not [`describe_image`](/docs/api/images/#describe_image)) while `description.status` is `pending`. A private image's `url` is unsigned; mint a link with [`sign_image_url`](/docs/api/images/#sign_image_url).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Image id.

### Responses

-   200
    
    Image details
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no image or PDF with this id in the project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "data": {
    "id": "img_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
    "branded_url": "https://media.example.com/img_abc123.jpg",
    "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
    "mime_type": "image/jpeg",
    "size": 245782,
    "width": 1920,
    "height": 1080,
    "filename": "photo.jpg",
    "folder": "blog",
    "metadata": {
      "env": "prod",
      "run": "42"
    },
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
      "ocr_text": "HARBOUR MASTER",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ],
      "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
      "described_at": "2026-11-16T12:00:04.000Z",
      "cached": false,
      "error": "describe_timeout"
    },
    "describe_skipped": "unsupported_type",
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_in": 86400,
    "temporary": true,
    "deduplicated": true,
    "replayed": true
  }
}
```

## Replace image metadata

PATCH `/v1/images/{id}`

Replace an image's custom metadata. The object you send replaces the stored one (it is not merged); send `null` or `{}` to clear it. Max 50 top-level keys / 4 KB serialized; the request body may be at most 16 KB.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Image id.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`metadata`

object nullable

Required

New metadata object, or null to clear. NUL characters and unpaired surrogates are rejected.

### Responses

-   200
    
    Updated metadata
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): the body is not JSON, has no `metadata` field, or the metadata is not an object, has more than 50 keys, exceeds 4 KB or contains unsafe characters.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no image or PDF with this id in the project.
    
-   413
    
    [`payload_too_large`](/docs/errors/#payload_too_large): the request body is larger than 16 KB.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X PATCH https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"env":"prod","reviewed":true}}'
```

Response 200

```
{
  "data": {
    "id": "img_abc123",
    "metadata": {
      "env": "prod",
      "reviewed": true
    }
  }
}
```

## Delete image

DELETE `/v1/images/{id}`

Permanently delete an image or PDF: the stored file and its record are removed, its storage is freed, and its URLs (signed ones included) stop working. Emits the `media.deleted` webhook.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Image id.

### Responses

-   200
    
    Image deleted
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no image or PDF with this id in the project. Delete videos and audio with [`delete_video`](/docs/api/videos/#delete_video) and [`delete_audio`](/docs/api/audio/#delete_audio).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl -X DELETE https://api.pixelvault.dev/v1/images/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "success": true
}
```

## Generate an image from a text prompt

POST `/v1/images/generate`

Create an image from a text prompt with a Cloudflare Workers AI model and host it in one call. Returns the same payload as an upload (CDN URL with no fixed expiry, dimensions, `optimized_url`) plus a `generation` block. Free-plan retention still applies. Requires a **secret** key and a **verified email**.

Models and credits per image:

-   `flux-1-schnell` (FLUX.1 schnell, default): 1 credit, all plans
-   `sdxl-lightning`, `sdxl-base` (Stable Diffusion XL, beta): 1 credit, Starter and Pro
-   `lucid-origin`, `phoenix-1.0` (Leonardo): 20 credits, Starter and Pro

**Credits:** each plan includes a monthly grant (10 Free, 300 Starter, 1,500 Pro) that resets on the 1st (UTC). Check what is left with [`get_usage`](/docs/api/usage/#get_usage) (`generation.credits_remaining`). Credits are reserved before the model runs and refunded if generation or storage fails, so a failed call costs nothing. A generated image also counts toward the upload and storage quotas, and a request that would be refused for plan, quota, credit or validation reasons never runs the model.

Prompts that clearly ask for adult content are refused (see the [Terms](https://pixelvault.dev/terms/)). Do not retry a 402. A successful generation emits `media.created` with `source: generation`.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`prompt`

string

Required

What to draw.

min length 1 · max length 2000

`model`

string

Optional

Model id. Credits per image: flux-1-schnell 1, sdxl-lightning 1, sdxl-base 1, lucid-origin 20, phoenix-1.0 20. The free plan can use flux-1-schnell only; the SDXL models are in beta.

One of: `flux-1-schnell`, `sdxl-lightning`, `sdxl-base`, `lucid-origin`, `phoenix-1.0`

Default: `flux-1-schnell`

`folder`

string

Optional

Optional folder (letters, numbers, hyphens, underscores; max 64 chars).

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`visibility`

string

Optional

`private` returns a signed URL; counts toward the free plan's 100 private assets.

One of: `public`, `private`

Default: `public`

`expires_in`

integer

Optional

Delete the image after this many seconds. Omit for no fixed expiry.

min 60 · max 2592000

`sign_expires_in`

integer

Optional

Signature lifetime for a private result URL, in seconds.

Default: `3600`

min 60 · max 2592000

### Responses

-   201
    
    Image generated and hosted
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): missing or too long prompt, unknown model, or bad `visibility`, `expires_in` or `sign_expires_in`. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   402
    
    [`generation_credits_exhausted`](/docs/errors/#generation_credits_exhausted): out of credits until the 1st (UTC), or upgrade. [`model_requires_paid_plan`](/docs/errors/#model_requires_paid_plan): the free plan can use `flux-1-schnell` only. [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached), [`private_limit_reached`](/docs/errors/#private_limit_reached): a plan quota is full. Do not retry.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   422
    
    [`prompt_rejected`](/docs/errors/#prompt_rejected): the prompt was refused (for example, it clearly asks for adult content).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): 60 generations per hour per account, the day's overall generation capacity, or the per-key request limit. Honour `Retry-After`; credits are not spent.
    
-   502
    
    [`generation_failed`](/docs/errors/#generation_failed): the model failed or returned no usable image. Credits are refunded; safe to retry.
    
-   503
    
    [`generation_unavailable`](/docs/errors/#generation_unavailable): image generation is temporarily unavailable. Credits are refunded; safe to retry.
    
-   504
    
    [`generation_timeout`](/docs/errors/#generation_timeout): the model timed out. Credits are refunded; safe to retry.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/generate \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A minimalist hero image of a mountain at sunrise, flat illustration",
  "model": "flux-1-schnell",
  "folder": "heroes"
}'
```

Response 201

```
{
  "data": {
    "id": "img_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg",
    "branded_url": "https://media.example.com/img_abc123.jpg",
    "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
    "mime_type": "image/jpeg",
    "size": 245782,
    "width": 1920,
    "height": 1080,
    "filename": "photo.jpg",
    "folder": "blog",
    "metadata": {
      "env": "prod",
      "run": "42"
    },
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
      "ocr_text": "HARBOUR MASTER",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ],
      "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
      "described_at": "2026-11-16T12:00:04.000Z",
      "cached": false,
      "error": "describe_timeout"
    },
    "describe_skipped": "unsupported_type",
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_in": 86400,
    "temporary": true,
    "deduplicated": true,
    "replayed": true,
    "visibility": "public",
    "signed_expires": 1795449600,
    "generation": {
      "model": "flux-1-schnell",
      "credits_charged": 1,
      "credits_remaining": 9
    }
  }
}
```

## Edit an image with a natural-language instruction

POST `/v1/images/{id}/edit`

Edit an existing image you own with a natural-language instruction and host the result as a **new image**; the source is never overwritten. For a local file, upload it first with [`upload_image`](/docs/api/images/#upload_image) and use the returned id. Cloudflare FLUX.2 processes the source and prompt with zero data retention.

Use a secret key, or the signed-in dashboard session (the Edit button beside an image); both paths use the same models and edit-credit allowance. A verified email is required.

Models:

-   `fast` (FLUX.2 Klein 4B, default): 1 edit credit, all plans
-   `quality` (FLUX.2 Klein 9B): 5 edit credits, Starter and Pro

**Credits:** monthly grants are 5 on Free, 100 on Starter and 500 on Pro. They reset on the 1st (UTC), are independent from generation credits, and are refunded if preparation, inference or storage fails. Check `editing.credits_remaining` in [`get_usage`](/docs/api/usage/#get_usage). JPEG, PNG, WebP, AVIF and GIF sources up to 20 MB are supported. The edited image counts toward the upload and storage quotas.

Optional `folder`, `visibility`, `expires_in` and `sign_expires_in` apply to the new image; visibility and folder default to the source's. The new image's `metadata` records `pixelvault_edit.source_image_id` and `pixelvault_edit.model`. A successful edit emits `media.created` with `source: edit`.

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Source image id.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`prompt`

string

Required

Natural-language edit instruction.

min length 1 · max length 2000

`model`

string

Optional

`fast` costs 1 edit credit. `quality` costs 5 and requires a paid plan.

One of: `fast`, `quality`

Default: `fast`

`folder`

string

Optional

Folder for the new image. Defaults to the source folder (none for a private source).

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`visibility`

string

Optional

Visibility for the new image. Defaults to the source visibility.

One of: `public`, `private`

`expires_in`

integer

Optional

Delete the new image after this many seconds. Omit for no fixed expiry.

min 60 · max 2592000

`sign_expires_in`

integer

Optional

Signature lifetime for a private result URL, in seconds.

Default: `3600`

min 60 · max 2592000

### Responses

-   201
    
    Edited image created and hosted
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): missing or too long prompt, unknown model, or bad `visibility`, `expires_in` or `sign_expires_in`. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key, or an invalid dashboard session.
    
-   402
    
    [`edit_credits_exhausted`](/docs/errors/#edit_credits_exhausted): out of edit credits until the 1st (UTC). [`edit_model_requires_paid_plan`](/docs/errors/#edit_model_requires_paid_plan): `quality` needs Starter or Pro. [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached), [`private_limit_reached`](/docs/errors/#private_limit_reached): a plan quota is full. Do not retry.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no source image with this id that you own, or it has expired.
    
-   422
    
    [`source_not_editable`](/docs/errors/#source_not_editable): the source is not JPEG, PNG, WebP, AVIF or GIF, or is larger than 20 MB. [`prompt_rejected`](/docs/errors/#prompt_rejected): the instruction was refused.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): the editing rate or daily cost limit, or the per-key request limit. Honour `Retry-After`.
    
-   502
    
    [`editing_failed`](/docs/errors/#editing_failed): source preparation or the model failed, or returned an unusable image. Edit credits are refunded.
    
-   503
    
    [`editing_unavailable`](/docs/errors/#editing_unavailable): image editing is temporarily unavailable. Edit credits are refunded.
    
-   504
    
    [`editing_timeout`](/docs/errors/#editing_timeout): the model timed out. Edit credits are refunded.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/edit \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Remove the people in the background",
  "model": "fast"
}'
```

Response 201

```
{
  "data": {
    "id": "img_edited123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_edited123.png",
    "branded_url": "https://media.example.com/img_abc123.jpg",
    "optimized_url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?fmt=auto&q=85",
    "mime_type": "image/jpeg",
    "size": 245782,
    "width": 1920,
    "height": 1080,
    "filename": "photo.jpg",
    "folder": "blog",
    "metadata": {
      "pixelvault_edit": {
        "source_image_id": "img_abc123",
        "model": "fast"
      }
    },
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "caption": "A small red fishing boat rests at a stone quay while the sun sets behind the harbour wall.",
      "ocr_text": "HARBOUR MASTER",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ],
      "model": "@cf/mistralai/mistral-small-3.1-24b-instruct",
      "described_at": "2026-11-16T12:00:04.000Z",
      "cached": false,
      "error": "describe_timeout"
    },
    "describe_skipped": "unsupported_type",
    "created_at": "2026-11-16T12:00:00.000Z",
    "expires_in": 86400,
    "temporary": true,
    "deduplicated": true,
    "replayed": true,
    "visibility": "public",
    "signed_expires": 1795449600,
    "edit": {
      "source_image_id": "img_abc123",
      "model": "fast",
      "credits_charged": 1,
      "credits_remaining": 4
    }
  }
}
```

## Batch upload into a collection

POST `/v1/images/batch`

Upload up to 50 images in one request, grouped into a **collection** (for example one CI run). Secret key only. Partial-failure tolerant: each item reports `ok` independently, so one bad image does not sink the batch. Re-running with the same collection `type` and `name` reuses the same collection, so a retried job lands in one place (items themselves are not deduplicated).

`collection.visibility: "private"` returns a **signed URL** per image (lifetime `sign_expires_in`, default 7 days); `"public"` returns a plain CDN URL. Optional: `expires_in` (image deletion TTL) and freeform `metadata` on the collection and on each image. Each item is either base64 `data` or a public `source_url` to import, and is capped at the plan's per-file size. The whole request body may be at most 40 MB.

For GitHub Actions, the [PixelVault screenshots action](https://github.com/marketplace/actions/pixelvault-upload-screenshots) wraps this endpoint: on a failed run it uploads Playwright or visual-regression screenshots and posts a sticky pull-request comment ([walkthrough](https://pixelvault.dev/blog/host-playwright-ci-screenshots/)). Close the collection with [`close_collection`](/docs/api/collections/#close_collection) when the pull request merges.

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`collection`

object

Required

Child properties of `collection`

Properties of collection

Name

Type

Required

Description

`type`

string

Required

Collection kind, e.g. `ci_build`. Closing a `ci_build` collection deletes its images.

max length 32

`name`

string

Optional

Reuse key within (project, type), e.g. the CI run id.

max length 255

`visibility`

string

Optional

One of: `public`, `private`

Default: `public`

`expires_in`

integer

Optional

Image deletion TTL in seconds.

min 60 · max 2592000

`sign_expires_in`

integer

Optional

Signature lifetime for private URLs in seconds. Defaults to 7 days.

Default: `604800`

min 60 · max 2592000

`metadata`

object

Optional

Freeform collection metadata (e.g. commit, pr\_number, branch).

`images`

array of object

Required

min items 1 · max items 50

Child properties of `images`

Properties of images

Name

Type

Required

Description

`data`

string (byte)

Optional

Base64-encoded image bytes. Send this or `source_url`.

`source_url`

string (uri)

Optional

Public https URL to import instead of `data`.

`filename`

string

Optional

Defaults to `image` (or the URL's last path segment).

`metadata`

object

Optional

Freeform image metadata (max 50 keys, 4 KB); invalid metadata fails the item with [`invalid_metadata`](/docs/errors/#invalid_metadata).

### Responses

-   201
    
    Batch result. Check each item's `ok`.
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json): the body is not JSON. [`invalid_collection`](/docs/errors/#invalid_collection): `collection.type` missing or longer than 32 characters, or bad visibility. [`no_images`](/docs/errors/#no_images) / [`too_many_images`](/docs/errors/#too_many_images): `images` must hold 1–50 items. [`validation_error`](/docs/errors/#validation_error): bad `expires_in`. [`invalid_sign_expires_in`](/docs/errors/#invalid_sign_expires_in): `sign_expires_in` outside 60–2592000.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   402
    
    [`private_limit_reached`](/docs/errors/#private_limit_reached): the free plan's 100 private assets are used (upgrade for unlimited).
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`email_verification_required`](/docs/errors/#email_verification_required): an unverified account already stores 5 images. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   413
    
    [`batch_too_large`](/docs/errors/#batch_too_large): the request body is larger than 40 MB; send fewer or smaller images.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/batch \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection": {
    "type": "ci_build",
    "name": "gh-run-1234567890",
    "visibility": "private",
    "expires_in": 2592000,
    "metadata": {
      "commit": "9f8e7d6",
      "pr_number": 128
    }
  },
  "images": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "filename": "login-diff.png",
      "metadata": {
        "testName": "login page"
      }
    }
  ]
}'
```

Response 201

```
{
  "data": {
    "collection_id": "col_abc123",
    "items": [
      {
        "filename": "login-diff.png",
        "id": "img_abc123",
        "url": "https://img.pixelvault.dev/proj_xyz789/cp/col_abc123/img_abc123.png?token=3f9a…&expires=1795449600",
        "branded_url": "https://media.example.com/cp/col_abc123/img_abc123.png?token=3f9a…&expires=1795449600",
        "ok": true
      }
    ]
  }
}
```

## Mint a signed (private) URL

POST `/v1/images/{id}/sign-url`

Return a time-limited HMAC-signed URL for an image or PDF. Private images, videos and audio are served only behind signed URLs: the link works while the signature is valid, but strip the token (or let it expire) and the CDN returns 403. The free plan includes up to 100 private assets per project; paid plans are unlimited.

The signature binds the stored object (and project), so a URL cannot be replayed against another image. The project's signing secret is created on first use. Use a long `expires_in` (for example a pull request's lifetime) and re-sign on updates to avoid link rot. Deleting the image revokes its URLs. Videos and audio have their own [`sign_video_url`](/docs/api/videos/#sign_video_url) and [`sign_audio_url`](/docs/api/audio/#sign_audio_url).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Image id.

### Request body

`application/json`, optional

Request body

Name

Type

Required

Description

`expires_in`

integer

Optional

Signature lifetime in seconds.

Default: `3600`

min 60 · max 2592000

### Responses

-   200
    
    Signed URL
    
-   400
    
    [`invalid_expires_in`](/docs/errors/#invalid_expires_in): `expires_in` is not an integer between 60 and 2592000.
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no image or PDF with this id in the project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images/img_abc123/sign-url \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in":2592000}'
```

Response 200

```
{
  "data": {
    "url": "https://img.pixelvault.dev/proj_xyz789/cp/i/img_abc123.png?token=3f9a…&expires=1795449600",
    "branded_url": "https://media.example.com/cp/i/img_abc123.png?token=3f9a…&expires=1795449600",
    "expires": 1795449600
  }
}
```
