--- title: "Результат запроса" method: GET path: "/v1/requests/{request_id}" tags: ["Queue"] --- # Результат запроса `GET /v1/requests/{request_id}` ## Request - Base URL: `https://api.clipia.ai` - URL: `https://api.clipia.ai/v1/requests/{request_id}` - Auth: API key in header `Authorization` Возвращает результат генерации (`200`) когда статус терминальный (`COMPLETED` / `FAILED`), либо `202` пока запрос ещё в очереди или выполняется. Доступно любому валидному ключу (scope не требуется). Все медиа-URL ведут на CDN `media.clipia.ai`. Если при исполнении сервер отступил от параметров запроса, ответ (и `200` для `COMPLETED`, и `202`) содержит массив `warnings`. Сейчас причина одна — `audio_dropped`: звук был включён, но звуковая дорожка не прошла проверку безопасности модели, и ролик создан без звука. Стоимость запроса при этом не меняется. ## Path parameters - `request_id` string, uuid, required ## Response `200` Терминальный результат. Для `COMPLETED` содержит `output`; для `FAILED` — санитизированный `error`. - ResultResponse - `request_id` string, uuid, required: Идентификатор запроса генерации. - `status` 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELED', required: Статус генерации в очереди. `CANCELED` — терминальный: генерацию можно отменить вне публичного API (например, из веб-интерфейса Clipia); cancel-эндпоинта в публичном API нет, но `status` может вернуть `CANCELED`, поэтому клиент обязан считать его финальным. - `model` string, required: Slug модели, выполнившей генерацию. - `output` object, required: Результат генерации. Для изображений — `images: [{ url, original_url? }]` (`url` — оптимизированный WebP для показа; `original_url` — полноразмерный оригинал PNG/JPG для скачивания, когда доступен); для видео — `video: { url, original_url?, thumbnail_url? }` (`thumbnail_url` — статичный кадр-обложка от провайдера, доступен не для всех моделей); для аудио (TTS, музыка) — `audio: { url, format? }` и `audios: [{ url, format? }]`. Музыкальные модели отдают несколько вариантов трека за один запрос: `audios` содержит их все, `audio` — первый из них (первый элемент `audios` совпадает с `audio`). Все медиа-URL ведут на CDN `media.clipia.ai`. Полей `width`, `height` и `duration` в ответе нет: размеры и длительность читайте из самого файла. `original_url` и `thumbnail_url` заполняются не всегда — считайте их опциональными. - `cost` number, required: Стоимость генерации в кредитах. Пока запрос в работе — резерв; после завершения — фактически списанное. При `FAILED` и `CANCELED` резерв возвращается, поле равно 0. - `created_at` string, date-time, required: Время создания запроса (ISO 8601). - `completed_at` string, date-time: Время завершения генерации (ISO 8601). - `error` GenerationError: Санитизированная ошибка генерации — без деталей внутренней инфраструктуры. Кредиты за FAILED возвращаются всегда. `code` — закрытый словарь (snake_case), по нему клиент решает, повторять ли запрос: | code | Смысл | Повтор | | --- | --- | --- | | `generation_failed` | Общая ошибка генерации | можно | | `content_moderated` | Запрос отклонён модерацией контента | с тем же вводом бесполезен | | `invalid_input` | Ввод не принят моделью (размер/формат/параметры) | исправьте запрос | | `model_unavailable` | Модель временно недоступна | позже | | `timeout` | Генерация не уложилась во время | можно | | `rate_limited` | Модель перегружена | с паузой | | `insufficient_credits` | Не хватило кредитов на момент списания | после пополнения | | `result_unavailable` | Результат получен, но не сохранён/недоступен | можно | | `empty_result` | Модель вернула пустой результат | можно / измените запрос | | `canceled` | Отменено пользователем или системой | — | - `code` 'generation_failed' | 'content_moderated' | 'invalid_input' | 'model_unavailable' | 'timeout' | 'rate_limited' | 'insufficient_credits' | 'result_unavailable' | 'empty_result' | 'canceled', required - `message` string, required: Нейтральное описание на английском; без имён внутренних систем. - `warnings` InputWarning[]: Предупреждения о ходе исполнения запроса: сервер отступил от параметров `input`, чтобы запрос завершился. Сейчас причина одна — `audio_dropped` (ролик создаётся без звука). Поле присутствует, только когда есть о чём предупредить, и не приходит при `FAILED` и `CANCELED`. На приёме запроса эти предупреждения ещё неизвестны, поэтому в ответе на создание их нет. - `code` string, required: Машинная причина: - `unknown_parameter` — ключ серверу неизвестен (например, опечатка) и отбрасывается у любой модели; - `unsupported_parameter` — ключ существует, но эта модель его не объявляет и не использует; - `audio_dropped` — звук был включён, но звуковая дорожка не прошла проверку безопасности модели: ролик создаётся без звука, стоимость запроса не меняется. Приходит только в ответах о состоянии запроса (`RequestWarnings`), `parameter` равен `generate_audio`. Список причин может пополняться: незнакомое значение обрабатывайте как «параметр не применён». - `parameter` string, required: Имя ключа из `input` (длинное имя обрезается до 64 символов). - `message` string, required: Пояснение на английском: называет параметр и перечисляет параметры, которые модель объявляет в `input_schema`. Для `audio_dropped` — сообщает, что ролик создаётся без звука. ## Other responses - `202`: Запрос ещё выполняется (`IN_QUEUE` / `IN_PROGRESS`). Продолжайте опрашивать `status_url`. - `401`: Ключ отсутствует, неверный или отозван. - `404`: Неизвестный `request_id` или `model`. - `429`: Превышен лимит. `error.type` всегда `rate_limit_error`; различайте по `error.code`: - `rate_limit_exceeded` — запросов в минуту (RPM) или токенов в минуту (TPM) по ключу; - `concurrency_limit_exceeded` — слишком много генераций одновременно (по ключу или по аккаунту). Дождитесь завершения одной и повторите. В обоих случаях сервер отдаёт заголовок `Retry-After` и дублирует подсказку в `error.retry_after_seconds`. --- [API](https://skmtc.dev/clipia/apis/clipia-api.md) · [All operations](https://skmtc.dev/clipia/apis/clipia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clipia/apis/clipia-api/revisions/cc55924a3381?raw)