Generation queue
Clipia REST API async queue — submit, status, result, and webhooks for image and video generation.
The Clipia REST API generates images and video 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.
The API is queue-only. A generation request never blocks the connection until the frame is ready — it is enqueued immediately and returns an identifier you use to track progress.
Request lifecycle
Submit
POST /v1/models/:model enqueues the generation and instantly returns a request_id, the status_url / response_url links, and the operation cost in credits.
Wait (status or webhook)
Learn when it is done in one of two ways:
- polling — call
GET /v1/requests/:id/status(status, queue position, progress 0–100); - webhook — pass
webhook_urlin thesubmitbody and Clipia sends a signedPOSTon completion (recommended — no polling needed).
Result
GET /v1/requests/:id returns the result with an output field (media URLs on media.clipia.ai) once the status is terminal, or 202 while the generation is still running.
Generation statuses
| Status | Description |
|---|---|
IN_QUEUE | queued, queue_position ≥ 0 |
IN_PROGRESS | running, progress from 0 to 100 |
COMPLETED | done — fetch the result via response_url |
FAILED | error, credits fully refunded |
CANCELED | canceled outside the public API (e.g. from the web dashboard) — terminal status |
No cancel via the API
The public API has no cancel endpoint. A generation reserves credits the moment it starts and the computation cannot be interrupted at the executor. A CANCELED status may still arrive in status or result if the generation was canceled outside the API — treat it as final.
Authentication
Every /v1/* request needs an API key in the Authorization header using the Bearer scheme:
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxAuthorization: Key <key> and the X-Api-Key: <key> header are also accepted. Keys are created in your account (Settings → API keys) and shown once — treat them as a server-side secret.
Test mode
A key with the clipia_test_ prefix runs in the sandbox: submit charges no credits and triggers no real generation — it returns status: COMPLETED instantly with a fixed sample asset. Handy for wiring up your integration before plugging in a live key.