Видео API

Очередь задач для видео API: статусы, воркеры и выдача

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

Опубликовано 23 августа 2026 · 12 минут чтения · Ключевой запрос: очередь задач для видео API

Сначала опишите контракт своей задачи

Не делайте идентификатор внешнего провайдера единственным ключом продукта. До отправки запроса создайте внутренний jobId, укажите владельца, версию формы, допустимый тип входа, время создания и безопасный хеш полезной нагрузки. Сам prompt, исходные файлы и персональные сведения сохраняйте лишь при наличии отдельной политики доступа и срока хранения. Затем приложению проще показать пользователю одну понятную операцию даже тогда, когда внешний маршрут меняет формат task_id или временно недоступен.

Минимальный автомат состояний полезнее набора неясных флагов. Например: accepted после серверной проверки, queued перед выдачей воркеру, submitted после подтверждённого запуска, processing после статуса или callback, succeeded, failed и expired. Разрешите только известные переходы. Если callback приходит после expired, не возвращайте результат автоматически: сначала выполните контролируемую сверку владельца, срока и условий хранения.

Поставьте идемпотентность перед очередью

Пользователь может дважды нажать кнопку, мобильный клиент — повторить запрос после разрыва сети, а ваш gateway — получить сетевой timeout после фактического принятия операции. Поэтому сервер принимает Idempotency-Key или генерирует эквивалентный ключ из безопасного контекста, сохраняет его вместе с задачей и повторно возвращает существующий jobId. Нельзя решать эту проблему сравнением текста prompt: одинаковый текст может быть сознательно отправлен для двух разных проектов.

Ключ имеет ограниченный срок и область действия: пользователь, проект и вид операции. При несовпадении тела или владельца отдайте ясную ошибку, а не молча заменяйте задачу. О том, как не создавать дубли при повторных запросах, подробнее сказано в руководстве по идемпотентности AI API. Для видео это особенно важно: повтор может занять очередь и увеличить фактический расход.

Отделите приём HTTP от работы воркера

Контроллер HTTP отвечает за аутентификацию своим ключом RussiaAPI, валидацию вашей формы, ограничение размера входа и создание записи. Он не ждёт генерации и не передаёт секрет в браузер. Воркер берёт одну задачу с блокировкой, ещё раз проверяет, что она не отменена, и вызывает выбранный endpoint с серверной переменной окружения. Число воркеров задаётся отдельно для каждого проекта и маршрута: общий максимум не должен превращать один всплеск в лавину запросов.

Ниже — запускаемый каркас для Node.js 20+. Хранилище и функция отправки намеренно заменены интерфейсами: подключите свою очередь и официальный для выбранного маршрута клиент по текущей документации. В коде нет настоящего ключа; до запуска задайте RUSSIAAPI_API_KEY только в защищённой серверной среде.

import assert from 'node:assert/strict';

const transitions = new Map([
  ['accepted', new Set(['queued', 'cancelled'])],
  ['queued', new Set(['submitted', 'cancelled'])],
  ['submitted', new Set(['processing', 'failed'])],
  ['processing', new Set(['succeeded', 'failed', 'expired'])]
]);

export function move(job, next) {
  assert(transitions.get(job.status)?.has(next), `invalid transition ${job.status} -> ${next}`);
  return { ...job, status: next, updatedAt: new Date().toISOString() };
}

export async function runOne(queue, submitVideo) {
  const job = await queue.reserve();
  if (!job || job.cancelled) return;
  const submitted = move(job, 'submitted');
  await queue.save(submitted);
  const remote = await submitVideo({ jobId: job.id, input: job.input });
  await queue.save({ ...submitted, providerTaskId: remote.taskId, status: 'processing' });
}

Перед production-подключением добавьте обработку ошибки: 4xx обычно требуют исправления конфигурации или входных данных и не должны бесконечно повторяться; 429 и временные 5xx проходят через ограниченный backoff; timeout без подтверждённого результата требует запросить статус, а не слепо создать новую операцию. Граница между timeout и повтором разобрана в статье о deadline, отмене и повторах.

Webhook — быстрый сигнал, не источник без проверки

Если маршрут предоставляет callback, дайте ему отдельный HTTPS-обработчик. Он читает ограниченное тело, проверяет подпись согласно актуальной документации конкретного endpoint, сохраняет event ID и отвечает быстро. Долгую обработку, загрузку результата и уведомление пользователя перенесите в свой фон. Это уменьшает риск повторной доставки и не заставляет удалённую сторону ждать вашу базу данных.

Не доверяйте только полю status из тела запроса. Свяжите callback с ранее сохранённой задачей, ожидаемым проектом и task_id; не позволяйте входящему событию выбрать URL выдачи или пользователя. Event ID нужен для дедупликации, потому что корректный webhook может приходить больше одного раза. Если подпись, связь или схема неизвестны, сохраните минимальный безопасный факт инцидента и верните контролируемую ошибку. Практика подписи и повторов описана в статье о webhook для video API.

Polling оставьте резервным и экономным

Даже с callback полезен редкий polling. Он покрывает недоставленное событие, но не должен создавать тысячи одинаковых запросов. Для каждой задачи храните следующий момент проверки и увеличивайте интервал с jitter, пока задача не достигла терминального статуса или не превысила собственный deadline. Сервер возвращает клиенту внутренний статус, а не детали маршрута и не значение ключа. Пользователь может обновить страницу и продолжить наблюдение по своему jobId.

Сверяйте результат с правилами продукта: формат файла, длительность, размер, срок ссылки и разрешение владельца. Временную ссылку на результат не публикуйте как постоянную. Если контент зависит от входов пользователя, продумайте удаление и право отзыва ещё до первой задачи. Общий асинхронный жизненный цикл — task_id, polling и callback — показан в руководстве по генерации видео через API.

Очередь защищает качество обслуживания, а не только сервер

Ограничение параллелизма должно учитывать классы задач. Интерактивная короткая задача, пакетная обработка и тестовая генерация не обязаны бороться за один FIFO-список. Выделите очередь или вес для каждого класса, ограничьте число задач от одного проекта и фиксируйте максимальное время ожидания. При переполнении возвращайте понятный статус и ориентировочный порядок, но не выдумывайте точное время готовности: оно зависит от текущего каталога, входа, очереди и внешнего маршрута.

Метрики должны отвечать на операционные вопросы: сколько задач ждёт, сколько выполняется, какой процент завершается, каковы p50 и p95 времени по классу, сколько callback отклонено и сколько повторов защищено идемпотентностью. Не кладите в метрики prompt, Authorization или полный URL результата. Если расходы учитываются, измеряйте стоимость успешной задачи вместе с отменами и дублями, как предложено в материале о мониторинге стоимости.

FAQ

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

• Асинхронная генерация видео
• Webhook для video API
• Ошибка 429 и backoff
• Документы RussiaAPI