Видео и длительные задачи

Асинхронная генерация видео API: задачи, polling и честные статусы

Генерация видео редко укладывается в время жизни обычного HTTP-запроса. Пользователь отправляет сценарий или изображение, обработка идёт в очереди, а результат может появиться заметно позже. Если держать браузерное соединение открытым и ждать, приложение получает тайм-ауты, дубликаты и непонятные сообщения «что-то пошло не так». Асинхронная задача делает этот путь наблюдаемым и управляемым.

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

Разделите создание задачи и получение результата

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

Названия статусов и точные поля зависят от конкретного API. Не придумывайте endpoint или формат тела по статье: берите их только из актуальной документации выбранного доступного маршрута. В собственном приложении полезно нормализовать состояния в небольшой набор: queued, running, succeeded, failed, cancelled. Тогда UI и очередь не зависят от внутренних формулировок каждого поставщика, а команда может измерять время в очереди и долю завершений.

Определите контракт задачи до интеграции

У записи задачи должны быть собственный ID, владелец, время создания, безопасный хеш входа, версия промпта, выбранная конфигурация, текущий статус и ссылка на результат после успеха. Сам текст сценария, референс-файлы и ответ сервиса храните по правилам приватности продукта и ровно столько, сколько нужно. Не кладите API Key в таблицу задач, логи, metadata или клиентский state. Для отладки достаточно request ID, времени, кода ошибки и обезличенного идентификатора задачи.

Ещё до первого вызова решите, что значит «повторить». Двойной клик, перезагрузка страницы или повторная доставка webhook не должны создавать два ролика и две независимые задачи без согласия пользователя. Для этого клиент передаёт idempotency key или приложение создаёт его само на основании уникального действия пользователя. Сервер хранит соответствие ключа и задачи: одинаковый запрос в коротком допустимом окне возвращает уже созданную задачу, а не запускает новую. Конкретную поддержку идемпотентности у внешнего endpoint обязательно проверьте в его документации.

Polling: просто, но с пределами

Для первого прототипа polling обычно понятнее webhook: фронтенд или сервер запрашивает статус с возрастающим интервалом, пока задача не станет терминальной. Ошибка — отправлять запрос каждые 100 миллисекунд. Это расходует лимит, ухудшает ситуацию в очереди и не делает рендер быстрее. Начните с нескольких секунд, добавьте небольшой случайный jitter, увеличивайте паузу и всегда ставьте максимальное число проверок или дедлайн. После дедлайна сохраните задачу в статусе «ожидает проверки» и сообщите пользователю, что результат пока не подтверждён.

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

Безопасный каркас polling на сервере

Пример ниже показывает идею, а не конкретный контракт видеосервиса. Функции createVideoTask и getTask нужно реализовать строго по актуальной документации доступного маршрута. В коде нет настоящего ключа; секрет остаётся в серверной переменной окружения. Ограничение времени и попыток защищает от бесконечного ожидания.

const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms)); async function waitForVideo(taskId){for(let attempt=0;attempt<8;attempt+=1){const task=await getTask(taskId,{apiKey:process.env.RUSSIAAPI_API_KEY});if(['succeeded','failed','cancelled'].includes(task.status))return task;const jitter=Math.floor(Math.random()*400);await sleep(Math.min(30000,2000*2**attempt)+jitter);}throw new Error('Video task status was not confirmed before timeout');} async function submitVideo(input,idempotencyKey){const task=await createVideoTask(input,{apiKey:process.env.RUSSIAAPI_API_KEY,idempotencyKey});return {taskId:task.id,status:task.status};}

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

Webhook: меньше опросов, больше ответственности

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

Не доверяйте URL результата только потому, что он находится в входящем JSON. Сверьте, что событие относится к известной задаче и её владельцу, а затем выдайте пользователю доступ согласно правилам приложения. Не публикуйте приватный результат в общем логе. Если webhook отсутствует, polling остаётся нормальным вариантом при разумном интервале и конечной точке ожидания. Нельзя «компенсировать» отсутствие уведомлений шквалом запросов.

UX: говорите то, что знаете

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

Продумайте бюджет до запуска. Видео может быть существенно дороже короткого текстового запроса, поэтому полезны подтверждение параметров, лимиты на пользователя, отдельная очередь и видимая история задач. Это не только про деньги: ограничения на размер, длительность и конкурентность делают систему предсказуемой. Принципы измерения полной стоимости операции изложены в статье как контролировать стоимость LLM API; для видео подход тот же — измеряйте успешный результат, а не только цену одного вызова.

Наблюдаемость без секретов

Собирайте количество задач по статусам, время в очереди, длительность работы, p95 до завершения, процент ошибок по причине и число повторных доставок webhook. Добавьте алерт на рост terminal failures и на очередь, которая не сокращается. Метрики не должны содержать текст промпта, URL с временными токенами, Authorization или пользовательские файлы. Если расследование требует деталей, используйте строго ограниченный доступ и срок хранения.

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

FAQ

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

• Ошибка 429: retry и backoff
• Как выбрать модель для API
• Ротация API Key без простоя
• Документы RussiaAPI