---
title: Очередь генераций
description: Асинхронная очередь Clipia REST API — submit, status, result и вебхуки для генерации изображений и видео.
---

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

API работает **только в асинхронном режиме**. Запрос на генерацию не блокирует соединение до готовности кадра — он мгновенно ставится в очередь и возвращает идентификатор, по которому вы отслеживаете прогресс.

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

<Steps>

### Submit

`POST /v1/models/:model` ставит генерацию в очередь и сразу возвращает `request_id`, ссылки `status_url` / `response_url` и стоимость операции в кредитах.

### Ожидание (status или webhook)

Узнайте о готовности одним из двух способов:

- **polling** — опрашивайте `GET /v1/requests/:id/status` (статус, позиция в очереди, прогресс 0–100);
- **webhook** — передайте `webhook_url` в теле `submit`, и Clipia сам пришлёт подписанный `POST` по завершении (рекомендуется — опрашивать не нужно).

### Result

`GET /v1/requests/:id` отдаёт результат с полем `output` (медиа-URL на `media.clipia.ai`), когда статус терминальный, либо `202` пока генерация ещё в работе.

</Steps>

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

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

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

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

Все запросы к `/v1/*` требуют API-ключ в заголовке `Authorization` со схемой `Bearer`:

```http
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxx
```

Также принимаются `Authorization: Key <ключ>` и заголовок `X-Api-Key: <ключ>`. Ключ создаётся в консоли разработчика (`/developer`, вкладка «API-ключи») и показывается один раз — это серверный секрет.

<Callout type="info" title="Тестовый режим">
Ключ с префиксом `clipia_test_` работает в песочнице: `submit` не списывает кредиты и не запускает реальную генерацию — он мгновенно возвращает `status: COMPLETED` с фиксированным sample-ассетом. Удобно отладить интеграцию до подключения боевого ключа.
</Callout>