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_url in the submit body and Clipia sends a signed POST on 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_xxxxxxxxxxxxxxxxxxxxxx

Authorization: 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.