provod.ai / docs
Видео API

Задачи и результаты видео

Опрос статуса видео, получение файла, ошибки генерации и проверка подписи webhook.

Обновлено

После создания видео сохраните id. Используйте API-ключ того же рабочего пространства.

Проверить статус

Terminal
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.json

polling_url может быть относительным путём: разрешайте его относительно базового URL API. Пока статус pending или in_progress, повторяйте GET с паузой, например 5 секунд. Ограничьте время ожидания своего приложения и сохраните ID для последующей проверки. Истечение клиентского тайм-аута не отменяет серверную задачу.

СтатусДействие
pendingЗадача ожидает обработки
in_progressГенерация выполняется
completedРезультат готов к скачиванию
failedПрочитайте error_code и error
cancelled, expiredТерминальные значения схемы; прекратите опрос

Публичной ручки отмены задачи сейчас нет. generation_id — дополнительный идентификатор результата; для опроса используйте id.

Скачать результат

Terminal
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 создаёт отдельную платную задачу; перед повтором убедитесь, что предыдущая завершилась.

Решение проблем

На этой странице