API Reference
Generation queue
How the Clipia REST API async queue works — submitting a job, polling status, fetching results, and webhooks for image, video and audio generation.
The Clipia REST API generates images, video and audio through an asynchronous queue. You enqueue a job with POST /v1/models/:model, receive a request_id, then collect the result by polling its status or via a webhook. The base URL is https://api.clipia.ai/v1.
There is no synchronous mode: a generation request doesn't hold the connection until the output is ready — it returns an identifier right away, which you use to track progress.
Request lifecycle
Submit
POST /v1/models/:model enqueues the generation and immediately returns a request_id, the status_url and response_url links, and the reserved cost in credits. See Submit a generation.
Generation statuses
| Status | Description |
|---|---|
IN_QUEUE | queued; the queue_position field is deprecated and always 0 |
IN_PROGRESS | running; progress from 0 to 100 |
COMPLETED | done; the result is available at response_url |
FAILED | failed; credits fully refunded |
CANCELED | canceled outside the API, for example by support; terminal status |
No cancellation via the API
The public API has no cancel endpoint: credits are reserved at start, and most models can't stop a generation once it begins. A CANCELED status may still appear in status or result if the job was canceled outside the API — treat it as final.
Request IDs
A request_id is usually a UUID. Jobs created through the MCP server may carry a prefix: cmp_… for video compositions and prs_… for presentations. The status and result endpoints accept all three forms, so you don't need to handle them separately. A malformed ID returns 400; an unknown ID, or one that belongs to another account, returns 404.
Authentication
Every /v1/* request needs an API key. The recommended header:
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: Key <key> and X-Api-Key: <key> are accepted too. Keys are created in the Developer Console and shown once. See Authentication for more.
Sandbox
A key with the clipia_test_ prefix runs in the sandbox: a submit charges no credits and runs no real generation — it returns status: COMPLETED right away with a fixed sample asset. See Sandbox.
Overview
The interactive Clipia REST API reference — parameters, response schemas, error codes, and sending a test request straight from the docs page.
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.