---
title: Generation queue
description: 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

<Steps>

### 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.

</Steps>

## 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 |

<Callout type="warn" title="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.
</Callout>

## Authentication

Every `/v1/*` request needs an API key in the `Authorization` header using the `Bearer` scheme:

```http
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxx
```

`Authorization: Key <key>` and the `X-Api-Key: <key>` header are also accepted. Keys are created in the Developer Console (`/developer`, API keys tab) and shown once — treat them as a server-side secret.

<Callout type="info" title="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.
</Callout>