Задачи и результаты видео
Опрос статуса видео, получение файла, ошибки генерации и проверка подписи webhook.
Обновлено
После создания видео сохраните id. Используйте API-ключ того же рабочего пространства.
Проверить статус
export VIDEO_ID="$(jq -er '.id' video-job.json)"
curl --fail-with-body --silent --show-error \
"$API_BASE_URL/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $PROVOD_API_KEY" -o video-status.json
jq '{id, status, error_code, error, unsigned_urls, usage}' video-status.jsonpolling_url может быть относительным путём: разрешайте его относительно базового URL API. Пока статус pending или in_progress, повторяйте GET с паузой, например 5 секунд. Ограничьте время ожидания своего приложения и сохраните ID для последующей проверки. Истечение клиентского тайм-аута не отменяет серверную задачу.
| Статус | Действие |
|---|---|
pending | Задача ожидает обработки |
in_progress | Генерация выполняется |
completed | Результат готов к скачиванию |
failed | Прочитайте error_code и error |
cancelled, expired | Терминальные значения схемы; прекратите опрос |
Публичной ручки отмены задачи сейчас нет. generation_id — дополнительный идентификатор результата; для опроса используйте id.
Скачать результат
test "$(jq -r '.status' video-status.json)" = "completed" || exit 1
curl --fail-with-body --silent --show-error \
"$API_BASE_URL/v1/videos/$VIDEO_ID/content?index=0" \
-H "Authorization: Bearer $PROVOD_API_KEY" -o video-output.binПараметр index выбирает результат, начиная с нуля. Определяйте формат по Content-Type; пример сохраняет байты в файл без предположения о контейнере. В unsigned_urls возвращаются адреса контента нашего API. Несмотря на название поля, скачивание требует Authorization: Bearer ...; это не публичные ссылки для вставки в браузер без ключа.
Уведомления webhook
Передайте callback_url при создании задачи. Адрес должен использовать HTTPS и разрешаться только в публичные IP. Секрет подписи своего пространства получите через GET /v1/videos/webhook-secret с API-ключом и храните на сервере.
Тело события содержит type, created_at и data. Для завершения используются video.generation.completed и video.generation.failed; внутри data находятся id, status и доступные поля результата или ошибки.
Проверяйте заголовок X-OpenRouter-Signature формата t=<timestamp>,v1=<hex>. Ожидаемая подпись — HMAC-SHA256 от строки timestamp + "," + rawBody с полученным секретом. rawBody — исходные UTF-8 байты, а не повторно сериализованный JSON. Сравнивайте подписи за постоянное время, проверяйте свежесть timestamp и обрабатывайте событие идемпотентно по X-OpenRouter-Idempotency-Key (id-status). Это ключ дедупликации уведомлений, а не создания генераций.
Сначала сохраните событие, затем быстро верните 2xx: обработчик доставки ждёт до 10 секунд. Webhook не заменяет GET статуса при потере уведомления и не меняет исход генерации.
Ошибки и повтор
В задаче со статусом failed смотрите error_code, а не разбирайте текст сообщения. Основные коды:
| Код | Что проверить |
|---|---|
VIDEO_INPUT_UNAVAILABLE | Доступность и срок жизни ссылок на материалы |
VIDEO_UPSTREAM_INVALID_REQUEST | Параметры и ограничения модели |
VIDEO_CONTENT_REJECTED, VIDEO_COPYRIGHT_RESTRICTED | Допустимость запроса и исходных материалов |
VIDEO_UPSTREAM_RATE_LIMITED, VIDEO_UPSTREAM_UNAVAILABLE, VIDEO_UPSTREAM_TIMEOUT | Возможность повторить позже |
VIDEO_UPSTREAM_INVALID_RESPONSE, VIDEO_ARTIFACT_STORAGE_FAILED, VIDEO_GENERATION_FAILED | Сохраните ID и время для поддержки |
HTTP 200 при GET задачи не означает успешную генерацию: проверяйте status. При окончательной ошибке резерв освобождается. Новый POST создаёт отдельную платную задачу; перед повтором убедитесь, что предыдущая завершилась.