Справочник API
Очередь генераций
Как устроена асинхронная очередь Clipia REST API — отправка задачи, статус, результат и вебхуки для генерации изображений, видео и аудио.
Clipia REST API генерирует изображения, видео и аудио через асинхронную очередь. Вы ставите задачу запросом POST /v1/models/:model, получаете request_id, а затем забираете результат опросом статуса или через вебхук. Базовый URL — https://api.clipia.ai/v1.
Синхронного режима нет: запрос на генерацию не держит соединение до готовности, а сразу возвращает идентификатор, по которому вы отслеживаете прогресс.
Жизненный цикл запроса
Отправка
POST /v1/models/:model ставит генерацию в очередь и сразу возвращает request_id, ссылки status_url и response_url и зарезервированную стоимость в кредитах. См. «Постановка генерации».
Ожидание
Узнать о готовности можно двумя способами:
- опрос — запрашивайте
GET /v1/requests/:id/status: статус, позиция в очереди, прогресс от 0 до 100; - вебхук — передайте
webhook_urlпри отправке, и Clipia пришлёт подписанныйPOST, когда задача завершится. Опрашивать тогда не нужно. См. «Вебхуки».
Результат
GET /v1/requests/:id отдаёт результат с полем output (ссылки на media.clipia.ai), когда статус терминальный, или 202, пока генерация ещё идёт. См. «Результат».
Статусы генерации
| Статус | Описание |
|---|---|
IN_QUEUE | в очереди; поле queue_position устарело и всегда равно 0 |
IN_PROGRESS | выполняется, progress от 0 до 100 |
COMPLETED | готово, результат доступен по response_url |
FAILED | ошибка, кредиты возвращены полностью |
CANCELED | задача отменена вне API, например службой поддержки; терминальный статус |
Отмены через API нет
В публичном API нет эндпоинта отмены: кредиты резервируются при старте, а начатую генерацию у большинства моделей остановить нельзя. Статус CANCELED всё же может прийти в status или result, если задачу отменили вне API, — обрабатывайте его как финальный.
Идентификаторы запросов
Обычно request_id — это UUID. Задачи, созданные через MCP-сервер, могут иметь префикс: cmp_… у монтажа видео и prs_… у презентаций. Эндпоинты статуса и результата принимают все три вида, отдельно обрабатывать их не нужно. Идентификатор в неверном формате вернёт 400, несуществующий или чужой — 404.
Аутентификация
Все запросы к /v1/* требуют API-ключ. Рекомендуемый заголовок:
Authorization: Bearer clipia_live_xxxxxxxxxxxxxxxxxxxxxxxxТакже принимаются Authorization: Key <ключ> и X-Api-Key: <ключ>. Ключ создаётся в консоли разработчика и показывается один раз. Подробнее — в разделе «Аутентификация».
Тестовый режим
Ключ с префиксом clipia_test_ работает в песочнице: отправка не списывает кредиты и не запускает реальную генерацию, а сразу возвращает status: COMPLETED с фиксированным образцом. См. «Тестовый режим».
Обзор
Интерактивная справка Clipia REST API — параметры, схемы ответов, коды ошибок и отправка тестового запроса прямо со страницы документации.
Постановка генерации
POST /v1/models/{model} — поставить генерацию изображения, видео или аудио в очередь, получить request_id и отправить запрос прямо со страницы.