---
title: Очередь генераций
description: Как устроена асинхронная очередь Clipia REST API — отправка задачи, статус, результат и вебхуки для генерации изображений, видео и аудио.
icon: ListOrdered
---

Clipia REST API генерирует изображения, видео и аудио через асинхронную очередь. Вы ставите задачу запросом `POST /v1/models/:model`, получаете `request_id`, а затем забираете результат опросом статуса или через вебхук. Базовый URL — `https://api.clipia.ai/v1`.

Синхронного режима нет: запрос на генерацию не держит соединение до готовности, а сразу возвращает идентификатор, по которому вы отслеживаете прогресс.

## Жизненный цикл запроса

<Steps>
<Step>
### Отправка

`POST /v1/models/:model` ставит генерацию в очередь и сразу возвращает `request_id`, ссылки `status_url` и `response_url` и зарезервированную стоимость в кредитах. См. [«Постановка генерации»](/ru/docs/api-reference/submit).
</Step>

<Step>
### Ожидание

Узнать о готовности можно двумя способами:

- **опрос** — запрашивайте `GET /v1/requests/:id/status`: статус, позиция в очереди, прогресс от 0 до 100;
- **вебхук** — передайте `webhook_url` при отправке, и Clipia пришлёт подписанный `POST`, когда задача завершится. Опрашивать тогда не нужно. См. [«Вебхуки»](/ru/docs/api-reference/webhooks).
</Step>

<Step>
### Результат

`GET /v1/requests/:id` отдаёт результат с полем `output` (ссылки на `media.clipia.ai`), когда статус терминальный, или `202`, пока генерация ещё идёт. См. [«Результат»](/ru/docs/api-reference/result).
</Step>
</Steps>

## Статусы генерации

| Статус | Описание |
|--------|----------|
| `IN_QUEUE` | в очереди; поле `queue_position` устарело и всегда равно 0 |
| `IN_PROGRESS` | выполняется, `progress` от 0 до 100 |
| `COMPLETED` | готово, результат доступен по `response_url` |
| `FAILED` | ошибка, кредиты возвращены полностью |
| `CANCELED` | задача отменена вне API, например службой поддержки; терминальный статус |

<Callout type="warn" title="Отмены через API нет">
В публичном API нет эндпоинта отмены: кредиты резервируются при старте, а начатую генерацию у большинства моделей остановить нельзя. Статус `CANCELED` всё же может прийти в `status` или `result`, если задачу отменили вне API, — обрабатывайте его как финальный.
</Callout>

## Идентификаторы запросов

Обычно `request_id` — это UUID. Задачи, созданные через [MCP-сервер](/ru/docs/mcp), могут иметь префикс: `cmp_…` у монтажа видео и `prs_…` у презентаций. Эндпоинты статуса и результата принимают все три вида, отдельно обрабатывать их не нужно. Идентификатор в неверном формате вернёт `400`, несуществующий или чужой — `404`.

## Аутентификация

Все запросы к `/v1/*` требуют API-ключ. Рекомендуемый заголовок:

```http
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

Также принимаются `Authorization: Key <ключ>` и `X-Api-Key: <ключ>`. Ключ создаётся в [консоли разработчика](/ru/developer) и показывается один раз. Подробнее — в разделе [«Аутентификация»](/ru/docs/getting-started/authentication).

<Callout type="info" title="Тестовый режим">
Ключ с префиксом `clipia_test_` работает в песочнице: отправка не списывает кредиты и не запускает реальную генерацию, а сразу возвращает `status: COMPLETED` с фиксированным образцом. См. [«Тестовый режим»](/ru/docs/getting-started/sandbox).
</Callout>