Видео API

Генерация видео через API для сайта: серверный сценарий

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

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

Короткий ответ

Постройте путь из шести шагов: принять запрос на своём сервере, проверить пользователя и входные данные, создать внутренний job, отправить задачу разрешённому endpoint, сохранить внешний task ID, а затем обновлять статус через polling или webhook. Frontend получает ваш безопасный идентификатор работы и спрашивает только ваш backend. Ключ API, адрес поставщика, лимит и цена остаются на сервере.

Главная ошибка — сделать запрос из браузера и ждать минуту в одном HTTP-ответе. При закрытии вкладки, повторном клике или сетевой ошибке приложение теряет состояние, а секрет может оказаться в DevTools. Очередь и таблица задач позволяют восстановить ход операции: кто запросил видео, когда оно создано, сколько попыток было сделано, в каком состоянии оно находится и когда результат можно показать.

Состояния, которые нужны ещё до первой интеграции

Минимальная модель состояния обычно включает queued, submitted, processing, succeeded, failed и cancelled. Названия не принципиальны; принципиально, чтобы переходы были однозначными. Например, callback не должен переводить отменённую задачу обратно в processing, а повторная доставка одного события не должна создавать новый заказ.

Запишите для каждой задачи внутренний UUID, ID пользователя, версию входа, выбранную модель из текущего каталога, время создания, внешний task ID, состояние, попытки и безопасный код ошибки. Не сохраняйте API Key, заголовок Authorization, cookie или полный чувствительный prompt в незашифрованном журнале. При необходимости оставляйте хеш, сокращённую версию или ссылку на защищённое хранилище с правилами доступа.

Архитектура: браузер говорит с вашим backend

1. Клиент отправляет описание задачи на POST /api/video-jobs вашего приложения.
2. Backend проверяет сессию, квоту, допустимый размер и правила использования.
3. Backend создаёт job с idempotency key и ставит работу в очередь.
4. Воркер вызывает выбранный video endpoint ключом из секретного хранилища.
5. Воркер сохраняет внешний task ID и обновляет внутреннее состояние.
6. Клиент читает GET /api/video-jobs/:id, а готовый результат получает по ограниченному URL.

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

Иллюстративный серверный пример

Формы video endpoint отличаются у моделей и gateway. Поэтому код ниже — запускаемый каркас вашего backend, а поле submitToProvider нужно реализовать по актуальным документам RussiaAPI и каталогу. Он намеренно не называет неподтверждённую модель и не обещает конкретное время или формат результата. Секрет берётся только из окружения воркера.

import crypto from 'node:crypto';

export async function createVideoJob(req, res) {
  const prompt = String(req.body?.prompt ?? '').trim();
  if (!prompt || prompt.length > 1_000) return res.status(400).json({ error: 'invalid_prompt' });

  const job = await db.jobs.insert({
    id: crypto.randomUUID(), userId: req.user.id,
    status: 'queued', idempotencyKey: req.get('Idempotency-Key')
  });
  await queue.add('video', { jobId: job.id });
  return res.status(202).json({ id: job.id, status: job.status });
}

export async function runVideoJob(job) {
  const provider = await submitToProvider({
    apiKey: process.env.RUSSIAAPI_API_KEY,
    model: process.env.RUSSIAAPI_VIDEO_MODEL,
    prompt: await loadSanitizedPrompt(job.id)
  });
  await db.jobs.update(job.id, { status: 'submitted', providerTaskId: provider.taskId });
}

Перед запуском добавьте проверку того, что один idempotency key принадлежит одному пользователю и одному входу. Воркер должен иметь дедлайн, ограниченное число повторов только для безопасных операций и явный журнал переходов. Если отправка завершилась неизвестно из-за сетевой ошибки, сначала попытайтесь определить состояние уже созданной внешней задачи по своему ключу и task ID; не создавайте новую вслепую.

Polling: простой, но ограниченный

Polling подходит для небольшой нагрузки, когда у поставщика есть endpoint состояния. После получения task ID планировщик спрашивает статус с возрастающим интервалом — например, 2, 4, 8 и затем не чаще заданного максимума. Числа являются примером, а не универсальным лимитом: учитывайте условия конкретного API и свой бюджет. При succeeded проверьте, что URL результата соответствует ожидаемой схеме, сохраните нужные метаданные и отправьте пользователю уведомление.

Не позволяйте каждому браузеру самостоятельно опрашивать внешнее API. Иначе 100 открытых вкладок создадут 100 потоков одинаковых запросов. Опрос должен выполнять один серверный воркер, а frontend — читать кэшированное внутреннее состояние. Если задача слишком долго остаётся в processing, перейдите в понятный статус ожидания, зафиксируйте время и предложите пользователю повторить только по безопасной процедуре.

Webhook: экономнее, но требует проверки подписи

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

Обработчик должен ответить быстро: проверить подпись, записать событие и передать тяжёлую работу в очередь. Не скачивайте большой файл и не перекодируйте видео до отправки HTTP 200, если это создаёт риск тайм-аута. Валидацию формата и последующее скачивание выполнит воркер. Подробная модель task ID, polling и callback разобрана в руководстве по асинхронной генерации видео; для общей практики webhook полезна документация Vidu API, но сверять нужно именно тот маршрут, который выбран в вашем каталоге.

Повторы без дублей и контроль расходов

Видео-задача обычно имеет стоимость и побочный эффект, поэтому повтор нельзя воспринимать как безобидную сетевую кнопку. Генерируйте idempotency key на стороне сервера или принимайте его от клиента после проверки. Храните связь «пользователь + ключ + хеш входа → job ID». Если пользователь повторно отправил тот же запрос, верните уже созданную задачу вместо нового вызова.

Для временного 429 используйте ограниченный backoff с jitter, но не запускайте одновременно десятки повторов. Для 4xx сначала исправьте вход, права или конфигурацию. Для 5xx и сетевых ошибок сохраняйте причину и применяйте максимум попыток. Стратегию ограниченных повторов можно взять из статьи о 429, retry и backoff; идемпотентность особенно важна для видео, потому что результат появляется далеко после исходного HTTP-запроса.

Контент, права и ожидания пользователя

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

Не обещайте «видео за N секунд» или постоянную доступность конкретной модели. Очередь, лимиты, исходный материал и каталог меняются. Пользовательский интерфейс должен показывать фактическое состояние: «задача принята», «обрабатывается», «готово», «нужна проверка» или «не удалось выполнить». Такой статус честнее и полезнее, чем анимация без объяснения.

Чек-лист перед production

• Ключ RussiaAPI живёт только в серверном секрете, не во фронтенде.
• У каждой работы есть внутренний ID, идемпотентность и явные состояния.
• Проверены лимиты пользователя, бюджет, размер входа и политика контента.
• Polling ограничен, webhook проверяет подпись и дедуплицирует события.
• Ошибки, отмена и долгие задачи имеют понятный пользовательский статус.
• Модель, цена и возможности подтверждены в текущем каталоге RussiaAPI.

FAQ

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

• Асинхронная генерация видео: task ID и callback
• 429 и безопасные повторы
• Ротация API Key без простоя
• Документы RussiaAPI