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

API reference

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.

Claim anonymous media into your account

POST /v1/claim

Exchange the claim_token from playground_upload, playground_video_upload or playground_audio_upload for media in your account, without uploading it again. Authenticates with a dashboard session token (JWT), not an API key; the media lands in the account's default project and counts toward its upload and storage quotas. Idempotent per project: re-claiming returns the media already saved (200, already_claimed: true). Tokens are valid for 24 hours, after which the temporary upload no longer exists. Limited to 20 claims per hour per IP. Emits media.created with source: claim.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Request body

application/json, required

Request body
Name Type Required Description
token string Required

The claim_token returned by an anonymous playground upload.

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/claim \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InRtcF9hYmMxMjMifQ.c2lnbmF0dXJl"
}'
Response 201
{
  "data": {
    "id": "img_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
    "mime_type": "image/png",
    "size": 51234,
    "project_id": "proj_xyz789",
    "already_claimed": false
  }
}

Anonymous image generation (browser tool)

POST /v1/playground/generate

Powers the free AI image generator: generate one image from a prompt with FLUX.1 schnell, no account or API key, and get a temporary public CDN URL (removed within 24 hours; keep it by signing up and redeeming claim_token with claim_upload). Requires a Cloudflare Turnstile token, so it is meant for browsers; agents and scripts should use generate_image with an API key. Limited to 3 images per IP per day, a small global daily cap, and 10 playground requests per hour per IP.

Authentication

None. This endpoint is public.

Request body

application/json, required

Request body
Name Type Required Description
prompt string Required

What to draw.

min length 1 · max length 2000

turnstile_token string Required

Token from the Cloudflare Turnstile widget.

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/playground/generate \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "a watercolor fox reading a book",
  "turnstile_token": "0.zYx8wVu7tSr6qPo5nMl4kJi3hGf2eDc1bA"
}'
Response 201
{
  "data": {
    "id": "tmp_abc123",
    "url": "https://img.pixelvault.dev/playground/tmp_abc123.jpg",
    "mime_type": "image/jpeg",
    "size": 142000,
    "expires_in": 86400,
    "claim_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InRtcF9hYmMxMjMifQ.c2lnbmF0dXJl",
    "claim_expires_in": 86400,
    "generation": {
      "model": "flux-1-schnell"
    }
  }
}

Anonymous image or PDF upload (no API key)

POST /v1/playground/upload

Upload an image or PDF without an account or API key and get a temporary public CDN URL plus a claim token; it powers the free browser tools. Max 2 MB; limited to 10 uploads per hour per IP. PDFs are always served as download attachments. Uploads are removed within 24 hours unless claimed with claim_upload. For a 30-day keyless upload use upload_image without a key; for managed hosting, use it with a key.

Authentication

None. This endpoint is public.

Request body

multipart/form-data, required

Request body
Name Type Required Description
file file Required

Image or PDF file to upload (max 2 MB).

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/playground/upload \
  -F "file=@photo.jpg"
Response 201
{
  "data": {
    "id": "tmp_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/playground/tmp_abc123.png",
    "mime_type": "image/png",
    "size": 51234,
    "expires_in": 86400,
    "claim_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InRtcF9hYmMxMjMifQ.c2lnbmF0dXJl",
    "claim_expires_in": 86400
  }
}

Anonymous temporary MP4 upload

POST /v1/playground/video

Powers the free Video to URL tool: upload an MP4 without an account or API key and get a temporary public CDN URL plus a claim token. Limited to 25 MB and 3 uploads per hour per IP. Videos are removed within 24 hours unless claimed into a signed-in account with claim_upload (without uploading again); then create a social-ready copy with optimize_video.

Authentication

None. This endpoint is public.

Headers

Headers
Name Type Required Description
X-PixelVault-Filename string Optional

Original filename, 1–255 UTF-8 bytes. Defaults to video.mp4.

max length 255

Request body

The file bytes as the request body, with Content-Type set to video/mp4.

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/playground/video \
  -H "X-PixelVault-Filename: launch-demo.mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @launch-demo.mp4
Response 201
{
  "data": {
    "id": "tmp_abc123",
    "kind": "video",
    "url": "https://img.pixelvault.dev/playground/tmp_abc123.mp4",
    "mime_type": "video/mp4",
    "size": 12000000,
    "expires_in": 86400,
    "claim_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InRtcF9hYmMxMjMifQ.c2lnbmF0dXJl",
    "claim_expires_in": 86400
  }
}

Anonymous temporary audio upload

POST /v1/playground/audio

Powers the free Audio to URL tool: upload MP3, WAV, M4A or OGG audio without an account or API key and get a temporary public CDN URL plus a claim token. The container and codec are derived from the file bytes. Limited to 25,000,000 bytes and 3 large-media uploads per hour per IP. Audio is removed within 24 hours unless claimed into a signed-in account with claim_upload (without uploading again). Transcription requires an owned asset and authentication.

Authentication

None. This endpoint is public.

Headers

Headers
Name Type Required Description
X-PixelVault-Filename string Optional

Original filename. Its extension, when recognized, must match the uploaded container.

max length 255

Request body

The file bytes as the request body, with Content-Type set to audio/mpeg, audio/wav, audio/mp4 or audio/ogg.

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/playground/audio \
  -H "X-PixelVault-Filename: episode.mp3" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @episode.mp3
Response 201
{
  "data": {
    "id": "tmp_abc123",
    "kind": "audio",
    "url": "https://img.pixelvault.dev/playground/tmp_abc123.mp3",
    "original_url": "https://img.pixelvault.dev/playground/tmp_abc123.mp3",
    "mime_type": "audio/mpeg",
    "size": 834,
    "container": "mp3",
    "codec": "mp3",
    "duration_seconds": 1.25,
    "sample_rate": 44100,
    "channels": 2,
    "expires_in": 86400,
    "claim_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InRtcF9hYmMxMjMifQ.c2lnbmF0dXJl",
    "claim_expires_in": 86400
  }
}