Очередь генераций
Асинхронная очередь 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-ассетом. Удобно отладить интеграцию до подключения боевого ключа.