API reference
The PixelVault API is a JSON REST API for hosting images, PDF documents, original MP4 video and original audio. Every page here is generated from the OpenAPI 3.1 spec, the same file agents and SDK generators read, so the reference and the API cannot disagree.
Base URL
https://api.pixelvault.dev
Media is served from the CDN at https://img.pixelvault.dev/{project_id}/{asset_id}.{ext},
not from the API host. Image URLs take on-the-fly transform parameters; see
Image Delivery and Transforms.
Authentication
Send an API key as a Bearer token. Secret keys start with pv_live_ (production) or
pv_test_ (test) and grant full access to their project. Publishable keys (pv_pub_) are safe in
browser code: upload-only, and restricted to an allowlist of request origins. Keys are hashed server-side; the raw key is shown once.
curl "https://api.pixelvault.dev/v1/images?per_page=20" \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" Signing up needs no key (create an account, or sign in with an emailed code), and a multipart image upload works without one too, but is then temporary (expires in 30 days). Endpoints the web dashboard drives also accept a dashboard session token. Each operation lists what it accepts under Authentication. More in Authentication & API keys.
Responses and errors
Requests and responses are JSON unless an endpoint says otherwise (raw MP4 and audio uploads, tar export downloads).
A successful response wraps its payload in a top-level data object; paginated lists add a meta object
with pagination. A few responses (export jobs, billing URLs) return their object directly; each operation's response example
shows the exact shape.
{
"data": {
"id": "img_abc123",
"url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png"
}
}{
"data": [ { "id": "img_abc123" } ],
"meta": { "total": 42, "page": 1, "per_page": 20 }
}{
"error": {
"code": "invalid_file",
"message": "Human-readable description"
}
}
A failed request returns an error object with a stable, machine-readable code and a human-readable
message; branch on the code. Plan quotas return 402, not 429: retrying cannot succeed until
you delete media, upgrade, or the month resets. Every code, what causes it and whether to retry is in the
error catalog; quota and rate limits are in Limits.
Conventions
- Retries. Uploads accept an
Idempotency-Keyheader, so a retry after a timeout never stores a second copy. See Idempotency. - Pagination. Paginated lists take
pageandper_pageand returnmeta.total. See Pagination. - Long-running work. Descriptions, video jobs, transcription and exports run in the background; poll the resource or subscribe to webhooks. See Async jobs.
- Identifiers. IDs are prefixed by type:
img_,vid_,aud_,col_,exp_,key_,whk_,proj_.
Versioning
Every endpoint lives under /v1. This reference is generated from spec version 1.0.0.
Fetch /openapi.json to generate a client or to give an agent the full contract.
Resources
- Authentication Create an account and get an API key without a browser:
register_accountreturns a live key instantly; the emailed-code flow (device_login_start+device_login_complete) signs an existing account in and mints a new key. 3 endpoints - 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. 11 endpoints
- Videos Host original MP4 files byte-for-byte with a seekable CDN URL and a poster frame. Optional jobs create a social-ready H.264/AAC copy, a transcript and a storyboard. Files over 100 MB use the multipart upload session endpoints. 14 endpoints
- Audio Host original MP3, WAV, M4A and OGG files without transcoding (max 25,000,000 bytes), served with HTTP range support. Optional transcription produces plain-text, WebVTT and timestamped JSON transcripts. 7 endpoints
- Collections A collection is a typed group of media (a CI run, a generation set, an album) with shared metadata and its own lifecycle. Batch uploads create or reuse one; images, videos and audio can be filtered by
collection_id. 3 endpoints - Exports Download every non-expired image, video and audio original in a project as one tar archive with a
manifest.json. Exports run asynchronously: start one, poll the job, then download it within 24 hours. 3 endpoints - Projects Isolate media, API keys, usage, webhooks and idempotency keys inside one account. Free includes 1 project, Starter 3 and Pro 10. 4 endpoints
- Custom Domains Serve one project's media from a customer-owned hostname. Starter includes 1 hostname per account and Pro 3. Add the CNAME target returned by the API; Cloudflare provisions and renews HTTPS automatically. 4 endpoints
- API Keys List, create and revoke the secret keys on a project, so an agent can rotate its own credentials. All key endpoints need a secret key (
pv_live_/pv_test_); publishable keys get 403. 3 endpoints - Usage Plan, limits and current usage for the calling key's project, so an agent can check quota before a bulk upload. 1 endpoint
- Billing Start an upgrade or open the Stripe customer portal without a dashboard session. Both return a Stripe URL for a person to open; nothing is charged by the API call itself. 2 endpoints
- Webhooks Starter and Pro projects receive signed HTTPS callbacks for media lifecycle events (up to 3 endpoints on Starter, 10 on Pro). Manage endpoints, rotate signing secrets and read the delivery log. 6 endpoints
- Uploads Media-library endpoints the web dashboard calls. They authenticate with a dashboard session token (JWT), not an API key; callers with an API key should use the Images endpoints. 5 endpoints
- Playground Anonymous, rate-limited endpoints behind the free browser tools: temporary uploads and generations that expire within 24 hours unless claimed into an account with
claim_upload. 5 endpoints - Image Delivery The CDN on img.pixelvault.dev serves every image and applies on-the-fly transforms from query parameters. No API call or auth for public images; private images need a signed URL. 1 endpoint
- Health Liveness check for the API worker. 1 endpoint