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

[API reference](/docs/api/)

# 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`](/docs/api/playground/#claim_upload).

-   POST [Claim anonymous media into your account](#claim_upload)
-   POST [Anonymous image generation (browser tool)](#playground_generate)
-   POST [Anonymous image or PDF upload (no API key)](#playground_upload)
-   POST [Anonymous temporary MP4 upload](#playground_video_upload)
-   POST [Anonymous temporary audio upload](#playground_audio_upload)

## Claim anonymous media into your account

POST `/v1/claim`

Exchange the `claim_token` from [`playground_upload`](/docs/api/playground/#playground_upload), [`playground_video_upload`](/docs/api/playground/#playground_video_upload) or [`playground_audio_upload`](/docs/api/playground/#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

-   200
    
    Already claimed: the same media, returned without storing a second copy. Videos also carry `poster_url`, their metadata and `social_optimization`; audio carries the full Audio object.
    
-   201
    
    Media saved to the account
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json): the body is not JSON. [`validation_error`](/docs/errors/#validation_error): no `token`. [`invalid_claim_token`](/docs/errors/#invalid_claim_token): the token is not valid. [`invalid_file`](/docs/errors/#invalid_file), [`invalid_audio`](/docs/errors/#invalid_audio), [`unsupported_audio_codec`](/docs/errors/#unsupported_audio_codec): the stored media could not be verified and was not saved.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached): a plan quota is full. Plan ceilings, not rate limits.
    
-   403
    
    [`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.
    
-   404
    
    `no_project`: the account has no project to save into.
    
-   410
    
    [`claim_expired`](/docs/errors/#claim_expired): the token or the temporary upload has expired and is gone.
    
-   413
    
    [`file_too_large`](/docs/errors/#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`](/docs/errors/#rate_limit_exceeded): more than 20 claims per hour from this IP.
    
-   503
    
    [`audio_policy_pending`](/docs/errors/#audio_policy_pending): audio hosting is not configured on this deployment.
    

Request

curlNode.jsPython

```
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](https://pixelvault.dev/tools/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`](/docs/api/playground/#claim_upload)). Requires a Cloudflare Turnstile token, so it is meant for browsers; agents and scripts should use [`generate_image`](/docs/api/images/#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

-   201
    
    Image generated
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): missing or too long prompt or token. [`prompt_rejected`](/docs/errors/#prompt_rejected): the prompt was refused.
    
-   403
    
    [`human_check_failed`](/docs/errors/#human_check_failed): the Turnstile check failed; reload and try again.
    
-   429
    
    [`free_limit_reached`](/docs/errors/#free_limit_reached): 3 free images per IP per day are used. [`free_capacity_reached`](/docs/errors/#free_capacity_reached): the day's global free capacity is used. [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): too many playground requests from this IP. [`account_budget_exceeded`](/docs/errors/#account_budget_exceeded): anonymous tools are temporarily paused. Honour `Retry-After`.
    
-   502
    
    [`generation_failed`](/docs/errors/#generation_failed): the model failed or returned an unusable image.
    
-   503
    
    [`generation_unavailable`](/docs/errors/#generation_unavailable): generation or the human check is temporarily unavailable.
    
-   504
    
    [`generation_timeout`](/docs/errors/#generation_timeout): the model timed out.
    

Request

curlNode.jsPython

```
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`](/docs/api/playground/#claim_upload). For a 30-day keyless upload use [`upload_image`](/docs/api/images/#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

-   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.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than the 2 MB playground limit.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 10 playground uploads per hour from this IP. [`account_budget_exceeded`](/docs/errors/#account_budget_exceeded): anonymous uploads are temporarily paused.
    

Request

curlNode.jsPython

```
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](https://pixelvault.dev/tools/video-to-url/): 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`](/docs/api/playground/#claim_upload) (without uploading again); then create a social-ready copy with [`optimize_video`](/docs/api/videos/#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

-   201
    
    Temporary video uploaded
    
-   400
    
    [`missing_file`](/docs/errors/#missing_file): empty body. [`invalid_file`](/docs/errors/#invalid_file): not an MP4 container. [`validation_error`](/docs/errors/#validation_error): bad `X-PixelVault-Filename`.
    
-   411
    
    [`length_required`](/docs/errors/#length_required): `Content-Length` is missing, invalid or under 16 bytes.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than the 25 MB temporary limit.
    
-   415
    
    [`unsupported_media_type`](/docs/errors/#unsupported_media_type): `Content-Type` is not `video/mp4`.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 3 large-media uploads per hour from this IP. [`account_budget_exceeded`](/docs/errors/#account_budget_exceeded): anonymous uploads are temporarily paused.
    

Request

curlNode.jsPython

```
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](https://pixelvault.dev/tools/audio-to-url/): 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`](/docs/api/playground/#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

-   201
    
    Temporary audio uploaded
    
-   400
    
    [`invalid_audio`](/docs/errors/#invalid_audio) / [`unsupported_audio_codec`](/docs/errors/#unsupported_audio_codec): not an accepted container and codec combination. [`container_mismatch`](/docs/errors/#container_mismatch): the filename extension conflicts with `Content-Type`. [`content_length_mismatch`](/docs/errors/#content_length_mismatch): the body length differs from `Content-Length`. [`missing_file`](/docs/errors/#missing_file): empty body. [`validation_error`](/docs/errors/#validation_error): bad `X-PixelVault-Filename`.
    
-   411
    
    [`length_required`](/docs/errors/#length_required): `Content-Length` is missing or invalid.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than the 25,000,000-byte temporary limit.
    
-   415
    
    [`unsupported_media_type`](/docs/errors/#unsupported_media_type): `Content-Type` is not MP3, WAV, M4A or OGG.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 3 large-media uploads per hour from this IP. [`account_budget_exceeded`](/docs/errors/#account_budget_exceeded): anonymous uploads are temporarily paused.
    

Request

curlNode.jsPython

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