---
title: Generation queue
description: How the Clipia REST API async queue works — submitting a job, polling status, fetching results, and webhooks for image, video and audio generation.
icon: ListOrdered
---

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

<Steps>
<Step>
### 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](/en/docs/api-reference/submit).
</Step>

<Step>
### Wait

There are two ways to learn when a job is done:

- **polling** — call `GET /v1/requests/:id/status` for the status, queue position and progress from 0 to 100;
- **webhook** — pass a `webhook_url` on submit and Clipia sends a signed `POST` when the job finishes, so no polling is needed. See [Webhooks](/en/docs/api-reference/webhooks).
</Step>

<Step>
### Result

`GET /v1/requests/:id` returns the result with an `output` field (links on `media.clipia.ai`) once the status is terminal, or `202` while the generation is still running. See [Result](/en/docs/api-reference/result).
</Step>
</Steps>

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

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

## Request IDs

A `request_id` is usually a UUID. Jobs created through the [MCP server](/en/docs/mcp) 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:

```http
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

`Authorization: Key <key>` and `X-Api-Key: <key>` are accepted too. Keys are created in the [Developer Console](/en/developer) and shown once. See [Authentication](/en/docs/getting-started/authentication) for more.

<Callout type="info" title="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](/en/docs/getting-started/sandbox).
</Callout>