API Reference
Request status
GET /v1/requests/{request_id}/status — a lightweight check of a generation's status and progress by request_id. No extra key permission is needed.
Check the status of a submitted generation by its request_id. The call is lightweight and suits frequent polling when you don't use a webhook.
Playground
Use a test key here
Paste a clipia_test_… key into the form below: it charges no credits and calls no models, and the response has the same shape. The form keeps the key in this browser, so never enter a live clipia_live_… key here: it is a server-side secret. See Sandbox.
AuthorizationBearer <token>API key in the Authorization header with the Bearer scheme, the primary form. Generated clients add the Bearer prefix themselves, and in the playground the field already contains it: type the key after it. The playground keeps the key in this browser, so use a test key for trials:
Authorization: Bearer <CLIPIA_API_KEY>The same key is also accepted with the Key scheme (Authorization: Key <key>, the word Key in any case) and in the separate X-Api-Key header (the apiKeyHeader scheme); use whichever form suits you, the server tells them apart. The key is created in the developer console (clipia.ai/developer, "API keys" tab) and shown only once. Format: clipia_live_… (live), clipia_test_… (sandbox).
Sandbox / test mode. A key with the clipia_test_… prefix works in the sandbox: submit charges no credits and starts no real generation; it instantly returns status: COMPLETED with a deterministic mock result (a fixed sample asset on media.clipia.ai). The cost field shows the estimated cost, but it is not charged. Webhooks arrive through the same signed mechanism (HMAC-SHA256). This mode is meant for debugging an integration before you switch to a live key.
request_id*stringID of the generation request returned by submit.
uuidCurrent request status.
application/json- response
request_id*stringGeneration request ID.
uuidstatus*GenerationStatusGeneration status in the queue. CANCELED is terminal: a generation can be canceled outside the public API (for example, from the Clipia web interface); the public API has no cancel endpoint, but status can return CANCELED, so the client must treat it as final.
"IN_QUEUE""IN_PROGRESS""COMPLETED""FAILED""CANCELED"queue_position?integerDeprecatedDeprecated: always 0, the queue position is not computed. The field stays for compatibility; rely on status and progress.
progress?integerExecution progress 0..100 (for IN_PROGRESS).
0 <= value <= 100warnings?array<>Warnings about request execution: the server deviated from the input parameters so that the request could complete. Currently there is one reason, audio_dropped (the video is created without sound). The field is present only when there is something to warn about, and it does not come with FAILED and CANCELED. These warnings are not yet known when the request is accepted, so the creation response does not contain them.
items <= 20curl -X GET "https://example.com/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status"{ "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b", "status": "IN_PROGRESS", "queue_position": 0, "progress": 45}GET /v1/requests/:id/status returns the current status of the generation and, when known, its progress. Any valid key on the same account works — no extra permission is needed.
/v1/requests/:id/statusRequest
Prop
Type
curl https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status \
-H "Authorization: Bearer $CLIPIA_KEY"Response 200
{
"request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
"status": "IN_PROGRESS",
"queue_position": 0,
"progress": 45
}Prop
Type
Errors
| HTTP | code | message | When |
|---|---|---|---|
| 400 | invalid_request | invalid_request_id | the ID doesn't look like a request_id |
| 404 | not_found | request_not_found | the request doesn't exist or belongs to another account |
Which call to use
/status is meant for frequent polling. Fetch media links with GET /v1/requests/:id. If you passed a webhook_url on submit, you don't need to poll at all — see Webhooks. Poll no more than once per second: these calls count toward your rate limit.
Submit a generation
POST /v1/models/{model} — enqueue an image, video or audio generation, get a request_id, and send the request straight from this page.
Generation result
GET /v1/requests/{request_id} — fetch the finished result with links to the image, video or audio; while the job is still running, the API returns 202.