Перейти к содержимому

Справочник API

Статус запроса

GET /v1/requests/{request_id}/status — лёгкий опрос статуса и прогресса генерации по request_id; отдельное право ключа для него не требуется.

Проверьте статус поставленной генерации по её request_id. Запрос лёгкий и подходит для частого опроса, если вы не используете вебхук.

Песочница

Для проб — тестовый ключ

В форму ниже вставляйте ключ clipia_test_…: он не списывает кредиты и не вызывает модели, а ответ приходит в том же формате. Форма запоминает ключ в этом браузере, поэтому боевой clipia_live_… — серверный секрет — в неё не вводите. Подробнее — «Тестовый режим».

GET
/v1/requests/{request_id}/status

Авторизация

headerАвторизацияBearer <токен>

API-ключ в заголовке Authorization со схемой Bearer — основной способ. Сгенерированные клиенты добавляют префикс Bearer сами, а в плейграунде поле уже содержит его: допишите ключ после него. Плейграунд запоминает ключ в этом браузере, поэтому для проб берите тестовый:

Authorization: Bearer <CLIPIA_API_KEY>

Тот же ключ принимается и со схемой Key (Authorization: Key <ключ>, слово Key — в любом регистре), и в отдельном заголовке X-Api-Key (схема apiKeyHeader) — выбирайте удобную форму, сервер различает их сам. Ключ создаётся в консоли разработчика (clipia.ai/developer, вкладка «API-ключи») и показывается один раз. Формат: clipia_live_… (боевой), clipia_test_… (песочница).

Sandbox / тестовый режим. Ключ с префиксом clipia_test_… работает в песочнице: submit не списывает кредиты и не запускает реальную генерацию — он мгновенно возвращает status: COMPLETED с детерминированным mock-результатом (фиксированный sample-ассет на media.clipia.ai). Поле cost показывает расчётную стоимость, но она не списывается. Вебхуки приходят тем же подписанным механизмом (HMAC-SHA256). Режим предназначен для отладки интеграции до подключения боевого ключа.

Параметры пути

request_id*string

Идентификатор запроса генерации, полученный при submit.

Форматuuid

Тело ответа

Текущий статус запроса.

application/json
  1. response
request_id*string

Идентификатор запроса генерации.

Форматuuid
status*GenerationStatus

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

Одно из"IN_QUEUE""IN_PROGRESS""COMPLETED""FAILED""CANCELED"
queue_position?integerУстарело

Устарело — всегда 0, позиция в очереди не считается. Поле сохранено для совместимости; ориентируйтесь на status и progress.

progress?integer

Прогресс выполнения 0..100 (для IN_PROGRESS).

Диапазон0 <= value <= 100
warnings?array<>

Предупреждения о ходе исполнения запроса: сервер отступил от параметров input, чтобы запрос завершился. Сейчас причина одна — audio_dropped (ролик создаётся без звука). Поле присутствует, только когда есть о чём предупредить, и не приходит при FAILED и CANCELED. На приёме запроса эти предупреждения ещё неизвестны, поэтому в ответе на создание их нет.

Элементыitems <= 20
curl -X GET "https://example.com/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status"
{  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",  "status": "IN_PROGRESS",  "queue_position": 0,  "progress": 45}

GET /v1/requests/:id/status возвращает текущий статус генерации и, если он известен, прогресс выполнения. Хватит любого действующего ключа того же аккаунта — отдельное право не нужно.

GET/v1/requests/:id/status

Запрос

Свойство

Тип

curl https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status \
  -H "Authorization: Bearer $CLIPIA_KEY"

Ответ 200

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_PROGRESS",
  "queue_position": 0,
  "progress": 45
}

Свойство

Тип

Ошибки

HTTPcodemessageКогда
400invalid_requestinvalid_request_idидентификатор не похож на request_id
404not_foundrequest_not_foundзапроса нет или он принадлежит другому аккаунту

Когда что использовать

/status удобен для частого опроса. Ссылки на медиа забирайте через GET /v1/requests/:id. Если при отправке передан webhook_url, опрашивать статус не нужно — см. «Вебхуки». Опрашивайте не чаще раза в секунду: запросы считаются в общем лимите.

Постановка генерации

POST /v1/models/{model} — поставить генерацию изображения, видео или аудио в очередь, получить request_id и отправить запрос прямо со страницы.

Результат генерации

GET /v1/requests/{request_id} — забрать готовый результат со ссылками на изображение, видео или аудио; пока задача выполняется, API отвечает 202.