Очередь генераций

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

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

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

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

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 пока генерация ещё в работе.

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

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

Отмены через API нет

Публичный API не предоставляет cancel-эндпоинт. Генерация резервирует кредиты в момент старта, и вычисление нельзя прервать у исполнителя. Статус CANCELED всё же может прийти в status или result, если генерацию отменили вне API — обрабатывайте его как финальный.

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

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

Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxx

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

Тестовый режим

Ключ с префиксом clipia_test_ работает в песочнице: submit не списывает кредиты и не запускает реальную генерацию — он мгновенно возвращает status: COMPLETED с фиксированным sample-ассетом. Удобно отладить интеграцию до подключения боевого ключа.