Видео API

Polling или webhook для video API: как выбрать надёжный сценарий

Генерация видео через API почти всегда асинхронна: клиент отправляет запрос, получает task ID и узнаёт результат позднее. Polling и webhook решают эту задачу по-разному. Polling проще для первого контролируемого запуска, webhook уменьшает лишние запросы при устойчивом серверном endpoint. В обоих случаях успех зависит не от названия механизма, а от состояния задачи, идемпотентности, проверки подписи, ограниченных повторов и безопасной выдачи готового файла.

Опубликовано 25 августа 2026 · 11 минут чтения · Ключевой запрос: polling или webhook video API

Сначала опишите жизненный цикл задачи

После отправки видео-задачи приложение сохраняет собственный operation ID, внешний task ID, пользователя, параметры в допустимой форме, время создания и начальный статус. Затем оно получает обновления до одного из терминальных состояний: готово, отклонено, отменено или неизвестно. Не считайте обрыв HTTP-соединения доказательством неуспеха: задача могла быть принята внешней системой. Вместо повторной отправки найдите существующую операцию и запросите её состояние.

Список статусов, форматы результатов и срок доступности URL зависят от выбранной модели и endpoint. Подтверждайте их по текущей документации и каталогу RussiaAPI перед интеграцией. Не обещайте пользователю конкретную модель, длительность, качество, цену или время выполнения на основании тестового запуска. Видеоматериалы также требуют прав на входные изображения, лица, товарные знаки и предполагаемое использование результата.

Когда начинать с polling

Polling означает, что ваш сервер сам периодически читает статус задачи. Он удобен, когда у вас пока нет публичного callback URL, обработчик не должен принимать внешние запросы или задачи редки. Сервер может применять единый deadline, хранить состояние рядом с операцией и показывать пользователю предсказуемый прогресс. Важно, что poller работает только на сервере: браузер не должен обращаться к API с ключом и не должен самостоятельно решать, что задача потеряна.

Интервал не должен быть постоянным и агрессивным. Первые проверки можно сделать с небольшой паузой, затем увеличить её с ограничением общего времени и jitter. Для статусов 429 и временных 5xx применяйте конечный backoff; для 4xx конфигурации не повторяйте запрос вслепую. После terminal status остановите polling. Если дедлайн истёк, сохраните unknown и предложите контролируемую проверку, а не создавайте скрытую копию видео-задачи.

Когда webhook лучше

Webhook подходит для постоянного сервера, который может принимать HTTPS-запросы и быстро подтверждать их получение. Поставщик отправляет событие, а ваш endpoint проверяет подпись, время, event ID и связь с задачей, после чего ставит короткую работу в очередь. Ответ 2xx должен означать, что событие надёжно принято, а не что видео уже скачано и обработано. Тяжёлая работа в обработчике повышает риск timeout и повторной доставки.

Нельзя доверять одному факту, что запрос пришёл по ожидаемому пути. Проверьте подпись по исходному сырому телу, используйте постоянное сравнение, ограничьте размер тела, проверяйте допустимое время события и сохраняйте event ID с уникальным ограничением. Если конкретный endpoint не публикует схему подписи, не изобретайте её: используйте polling или запросите подтверждённую документацию. Не печатайте тело callback целиком в журнале, потому что оно может содержать URL или пользовательские данные.

Пример безопасного приёма события

Следующий Node.js-пример показывает локальную проверку HMAC и дедупликацию по event ID. Это шаблон, а не договорённость о точных заголовках конкретного video API: названия заголовка, алгоритм и формат payload обязательно сверяются с документацией выбранного endpoint. Секрет подписи хранится только в серверном secret store; его нельзя добавлять в приложение браузера или репозиторий.

import crypto from 'node:crypto';

const seenEventIds = new Set(); // Replace with a DB table + unique index in production.

export function acceptVideoWebhook(rawBody, signature, eventId) {
  if (!process.env.VIDEO_WEBHOOK_SECRET) throw new Error('Missing webhook secret');
  if (!eventId || seenEventIds.has(eventId)) return { accepted: true, duplicate: true };

  const expected = crypto
    .createHmac('sha256', process.env.VIDEO_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
  const supplied = Buffer.from(signature || '', 'hex');
  const actual = Buffer.from(expected, 'hex');
  if (supplied.length !== actual.length || !crypto.timingSafeEqual(supplied, actual)) {
    throw new Error('Invalid webhook signature');
  }

  const event = JSON.parse(rawBody);
  if (!event.task_id || !['completed', 'failed'].includes(event.status)) throw new Error('Unexpected event');
  seenEventIds.add(eventId);
  return { accepted: true, taskId: event.task_id, status: event.status };
}

После успешной проверки обработчик должен положить минимальное задание в очередь и быстро вернуть ответ. Воркер отдельно читает актуальный статус по task ID, валидирует, что он относится к ожидаемой операции, и только затем меняет состояние. Такой второй шаг защищает от устаревшего или повторно доставленного уведомления и даёт единое место для правил выдачи результата.

Дедупликация и повторы важнее транспорта

И polling, и webhook могут повториться. Сеть может задержать ответ, клиент может обновить страницу, поставщик может доставить одно событие дважды. Заведите идемпотентный ключ для создания задачи и уникальные ограничения для external task ID и event ID. Одно пользовательское действие должно иметь одну операцию, даже если технических попыток несколько. Это особенно важно для платных или долгих задач, где дубль приводит к непредсказуемой стоимости и путанице в интерфейсе.

Разделяйте статус доставки события и статус видео. «Webhook принят» — это не «видео готово», а «событие сохранено для обработки». Аналогично «poll вернул timeout» — не «внешняя задача отменена». Храните историю попыток, но не раскрывайте её целиком пользователю. Руководство о повторных запросах без дублей помогает построить этот слой для разных API-вызовов.

Выдача результата и права доступа

Когда задача завершена, не показывайте URL результата всем, кто знает task ID. Свяжите результат с владельцем операции, проверьте сессию и возвращайте файл через свой авторизованный маршрут или короткоживущую ссылку в соответствии с вашей политикой. Не записывайте временные подписанные URL в общие логи, чаты или аналитические события. Если результат истёк или был удалён, сообщите это честно и предложите допустимое действие, а не выдавайте ссылку из старого кеша.

Срок хранения видео, формат и доступность результата могут меняться. Явно покажите пользователю, где он видит текущий статус, какие действия доступны и когда данные будут удалены согласно политике продукта. Перед отправкой входа проверьте права на материал и соответствие применимым правилам. Асинхронная интеграция не даёт разрешения обходить ограничения площадок, законы или договорные условия.

Решение и чек-лист

Выберите polling, если нужна минимальная зависимость от входящего HTTPS и задачи редки; выберите webhook, если вы готовы безопасно принимать подписанные события и хотите снизить число проверок. На практике полезен гибрид: webhook ускоряет обновление, а редкий контролируемый polling проверяет зависшие операции. Независимо от выбора наблюдайте время до terminal status, число повторов, 429, невалидные подписи, долю unknown и стоимость завершённой задачи.

1. У операции есть внутренний ID, внешний task ID, владелец и терминальные статусы.
2. Создание защищено идемпотентностью; polling и webhook не создают дублей.
3. Webhook проверяет документированную подпись, время, event ID и быстро ставит работу в очередь.
4. Polling имеет deadline, jitter, backoff и прекращается после terminal status.
5. Результат выдаётся только авторизованному владельцу, а ссылки и секреты не попадают в логи.

FAQ

Читайте также

• Асинхронная генерация видео
• Безопасный webhook video API
• Очередь задач для видео
• Документы RussiaAPI