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
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Required | The |
Responses
- 200
Already claimed: the same media, returned without storing a second copy. Videos also carry
poster_url, their metadata andsocial_optimization; audio carries the full Audio object. - 201
Media saved to the account
- 400
invalid_json: the body is not JSON.validation_error: notoken.invalid_claim_token: the token is not valid.invalid_file,invalid_audio,unsupported_audio_codec: the stored media could not be verified and was not saved. - 401
unauthorized: no dashboard session, or it is invalid or expired. - 402
upload_limit_reached,storage_limit_reached: a plan quota is full. Plan ceilings, not rate limits. - 403
email_verification_required: an unverified account already stores 5 images.account_suspended: the account is suspended. - 404
no_project: the account has no project to save into. - 410
claim_expired: the token or the temporary upload has expired and is gone. - 413
file_too_large: the video exceeds the plan's video limit (25 MB Free, 100 MB Starter, 250 MB Pro) or the audio exceeds 25,000,000 bytes. - 429
rate_limit_exceeded: more than 20 claims per hour from this IP. - 503
audio_policy_pending: audio hosting is not configured on this deployment.
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"
}' {
"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
| Name | Type | Required | Description |
|---|---|---|---|
prompt | string | Required | What to draw. |
turnstile_token | string | Required | Token from the Cloudflare Turnstile widget. |
Responses
- 201
Image generated
- 400
validation_error: missing or too long prompt or token.prompt_rejected: the prompt was refused. - 403
human_check_failed: the Turnstile check failed; reload and try again. - 429
free_limit_reached: 3 free images per IP per day are used.free_capacity_reached: the day's global free capacity is used.rate_limit_exceeded: too many playground requests from this IP.account_budget_exceeded: anonymous tools are temporarily paused. HonourRetry-After. - 502
generation_failed: the model failed or returned an unusable image. - 503
generation_unavailable: generation or the human check is temporarily unavailable. - 504
generation_timeout: the model timed out.
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"
}' {
"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
| Name | Type | Required | Description |
|---|---|---|---|
file | file | Required | Image or PDF file to upload (max 2 MB). |
Responses
- 201
Image uploaded
- 400
missing_file: nofilefield.invalid_file: the bytes are not a supported image or PDF. - 413
file_too_large: larger than the 2 MB playground limit. - 429
rate_limit_exceeded: more than 10 playground uploads per hour from this IP.account_budget_exceeded: anonymous uploads are temporarily paused.
curl -X POST https://api.pixelvault.dev/v1/playground/upload \
-F "file=@photo.jpg" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
X-PixelVault-Filename | string | Optional | Original filename, 1–255 UTF-8 bytes. Defaults to |
Request body
The file bytes as the request body, with Content-Type set to
video/mp4.
Responses
- 201
Temporary video uploaded
- 400
missing_file: empty body.invalid_file: not an MP4 container.validation_error: badX-PixelVault-Filename. - 411
length_required:Content-Lengthis missing, invalid or under 16 bytes. - 413
file_too_large: larger than the 25 MB temporary limit. - 415
unsupported_media_type:Content-Typeis notvideo/mp4. - 429
rate_limit_exceeded: more than 3 large-media uploads per hour from this IP.account_budget_exceeded: anonymous uploads are temporarily paused.
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 {
"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
| Name | Type | Required | Description |
|---|---|---|---|
X-PixelVault-Filename | string | Optional | Original filename. Its extension, when recognized, must match the uploaded container. |
Request body
The file bytes as the request body, with Content-Type set to
audio/mpeg, audio/wav, audio/mp4 or audio/ogg.
Responses
- 201
Temporary audio uploaded
- 400
invalid_audio/unsupported_audio_codec: not an accepted container and codec combination.container_mismatch: the filename extension conflicts withContent-Type.content_length_mismatch: the body length differs fromContent-Length.missing_file: empty body.validation_error: badX-PixelVault-Filename. - 411
length_required:Content-Lengthis missing or invalid. - 413
file_too_large: larger than the 25,000,000-byte temporary limit. - 415
unsupported_media_type:Content-Typeis not MP3, WAV, M4A or OGG. - 429
rate_limit_exceeded: more than 3 large-media uploads per hour from this IP.account_budget_exceeded: anonymous uploads are temporarily paused.
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 {
"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
}
}