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

API reference

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

A hosted image or PDF document. Upload responses (upload_image, generate_image, 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 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.

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; null when none. Client-supplied: do not store secrets in it.

description object nullable

AI description from describe=true or 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 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.

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 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). Video and audio assets are listed by list_videos and list_audio.

URLs are unsigned: a private image's url is refused by the CDN until you mint a link with 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 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: malformed metadata filter, conflicting meta[key] values, q longer than 200 characters, or an invalid tag.

  • 401

    missing_api_key: no Authorization header. 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: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 429

    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
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.

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, and filter 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.

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. 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.

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 (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 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 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. 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

Request
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 and tag=.

Authentication

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

Responses

  • 200

    Tags with image counts

  • 401

    missing_api_key: no Authorization header. 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: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 429

    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
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 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 (q= full-text over alt text, caption and OCR text; tag= one tag) and list tags with 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: no Authorization header. 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: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 404

    image_not_found: no image with this id in the project (videos, audio and PDFs cannot be described).

  • 429

    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
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) while description.status is pending. A private image's url is unsigned; mint a link with 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: no Authorization header. 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: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 404

    image_not_found: no image or PDF with this id in the project.

  • 429

    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
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: 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: no Authorization header. 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: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 404

    image_not_found: no image or PDF with this id in the project.

  • 413

    payload_too_large: the request body is larger than 16 KB.

  • 429

    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
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

Request
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 (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). 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

Request
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 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. 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

Request
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 wraps this endpoint: on a failed run it uploads Playwright or visual-regression screenshots and posts a sticky pull-request comment (walkthrough). Close the collection with 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.

Responses

Request
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 and 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

Request
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
  }
}