Генерация видео

Генерируйте видео из текстовых промптов через RouterAI API.

RouterAI поддерживает генерацию видео через модели, у которых "video" указан в output_modalities. Генерация асинхронная: вы создаёте задачу, а готовое видео получаете позже — опросом статуса (polling) или через webhook на ваш callback_url.

Полный жизненный цикл:

1. Создание — POST /api/v1/videos возвращает id задачи и polling_url.
2. Ожидание — опрашивайте статус (GET /api/v1/videos/{id}) или получите webhook, если указали callback_url.
3. Скачивание — когда статус completed, заберите mp4 через content-эндпоинт.

Поиск моделей

Модели для генерации видео — это модели с "video" в output_modalities. Найти их можно:

• на странице моделей, отфильтровав по выходным модальностям;
• запросом общего каталога моделей GET /api/v1/models — видео-модели отличаются значением video в architecture.output_modalities:

curl https://routerai.ru/api/v1/models \
  -H "Authorization: Bearer $ROUTERAI_API_KEY"

Шаг 1. Создание генерации

Отправьте POST /api/v1/videos с обязательными model и prompt. Необязательное поле callback_url — HTTPS-адрес, на который придёт webhook о готовности (см. Шаг 3).

curl https://routerai.ru/api/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "x-ai/grok-imagine-video",
    "prompt": "Кот в скафандре медленно плывёт в невесомости на космической станции, кинематографичный свет",
    "aspect_ratio": "16:9",
    "duration": 4,
    "resolution": "480p",
    "callback_url": "https://example.com/hooks/routerai-video"
  }'

Ответ 202 Accepted — задача принята:

{
  "id": "Cq4gNzomlZDrNyy72GHC",
  "status": "pending",
  "polling_url": "https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC"
}

• id — идентификатор задачи (используется во всех последующих запросах).
• status — текущий статус (pending сразу после создания).
• polling_url — URL для опроса статуса (указывает на домен RouterAI).

Параметры запроса

Помимо перечисленных, модель может принимать провайдер-специфичные параметры (например, watermark у Seedance или personGeneration у Veo) — они передаются в корне тела запроса и пробрасываются провайдеру как есть. Какие параметры и значения поддерживает конкретная модель — см. в разделе «Поддержка по моделям» или на странице модели в каталоге.

Референсы и кадры на входе

Есть два способа передать вход помимо промпта, и каждый включает свой режим генерации:

• frame_images — опорные кадры для image-to-video: у каждого элемента есть frame_type — first_frame (первый кадр видео) или last_frame (последний).
• input_references — референсы для reference-to-video: модель использует их как ориентир, а не как точные кадры. Тип элемента определяется полем type:
  • image_url — референс-изображение (персонаж, стиль, объект);
  • video_url — исходное видео для video-to-video (например, редактирование футажа в runway/aleph-2);
  • audio_url — аудиодорожка (например, речь для липсинка в bytedance/seedance-2.0).

Набор поддерживаемых типов зависит от входных модальностей модели — см. страницу модели в каталоге. url внутри image_url/video_url/audio_url — публично доступный HTTPS-URL или data URI в base64.

У Seedance (bytedance/seedance-2.x) эти два режима взаимоисключающие. Не передавайте frame_images и input_references в одном запросе: часть таких запросов провайдер отклоняет ошибкой 400 last frame image content cannot be mixed with first frame or reference image content (не тарифицируется), а прошедшие обрабатываются как image-to-video — референсы, включая аудиодорожку для липсинка, молча игнорируются, и модель озвучивает реплику сама. Для липсинка используйте только input_references: изображения персонажа, при необходимости исходное видео и audio_url; первый и последний кадр в этом режиме не задаются.

Продление и редактирование видео у Seedance — без aspect_ratio и size. Если в input_references есть video_url, а промпт просит продолжить или изменить ролик, модель распознаёт задачу как video extension/editing и наследует геометрию исходника. Не передавайте в таком запросе ни aspect_ratio, ни size — провайдер выставит адаптивное соотношение сам; с явным соотношением задача завершится ошибкой `ratio` must be `adaptive` (не тарифицируется). Значение adaptive в поле aspect_ratio передать нельзя: оно отклоняется на валидации запроса.

Image-to-video (frame_images)

{
  "model": "bytedance/seedance-2.0",
  "prompt": "Персонаж идёт через осенний лес, камера следует за ним",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.png" },
      "frame_type": "first_frame"
    }
  ],
  "resolution": "1080p"
}

Reference-to-video (input_references)

{
  "model": "bytedance/seedance-2.0",
  "prompt": "Гигантская солнечная вспышка рядом с планетой",
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/style-ref.png" }
    }
  ],
  "resolution": "1080p"
}

Типы можно комбинировать — например, персонаж с референс-изображения поёт под переданную аудиодорожку:

{
  "model": "bytedance/seedance-2.0-mini",
  "prompt": "Кот поёт песню",
  "duration": 4,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/cat.jpeg" }
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/song.wav" }
    }
  ]
}

Video-to-video: редактирование готового ролика (runway/aleph-2)

runway/aleph-2 редактирует существующее видео по текстовой инструкции: исходный ролик передаётся элементом video_url в input_references (обязателен, публичный HTTPS-URL), prompt описывает изменения. Это единственный вход модели: изображения-референсы (image_url) она не принимает — запрос с картинкой в input_references отклоняется ошибкой 400 Unrecognized key: "references" ещё до старта генерации (не тарифицируется); frame_images тоже не поддерживаются. Референс внешности персонажа или объекта передать нельзя — описывайте желаемое текстом в prompt.

{
  "model": "runway/aleph-2",
  "prompt": "Замени небо на закатное, остальное не менять",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/source.mp4" }
    }
  ]
}

Особенности модели:

• Длительность выходного ролика равна длительности исходника, а разрешение задаёт провайдер (до 1080p) по выбранному aspect_ratio — поэтому supported_durations и supported_resolutions в каталоге пусты (null). Поля duration, resolution и size передавать не нужно: на результат они не влияют. Из общих параметров поддерживаются aspect_ratio и seed.
• Нативные параметры Runway keyframes (картинки, привязанные к моментам ролика) и prompt_images через наш API сейчас недоступны: keyframes до провайдера не доходит и молча отбрасывается (генерация выполняется и тарифицируется без него), prompt_images у Aleph 2 нет и в API Runway. Из провайдер-специфичных параметров в каталоге остаётся contentModeration (формат — в документации Runway; значение не валидируется, некорректное молча игнорируется).
• Редактирование отдельного временно́го участка не поддерживается: модель обрабатывает ролик целиком, отдельного поля временно́го диапазона нет.
• Тарификация — посекундно за выходной ролик (плюс минимальная стоимость генерации); итоговая сумма — в usage.cost ответа поллинга. Цены — на странице модели в каталоге.

Talking-head: оживление фото (heygen/avatar-iv)

heygen/avatar-iv анимирует одну фотографию в говорящий портрет: фото передаётся элементом image_url в input_references, а prompt — это текст, который персонаж произнесёт (скрипт), а не описание сцены.

Особенности модели:

• Голос обязателен при текстовом prompt. Модель озвучивает текст сама, поэтому нужно выбрать голос — идентификатор передаётся только во вложенном объекте provider.options.heygen.voice_id (корневой voice_id, в отличие от обычных провайдер-специфичных параметров, не сработает). Без голоса запрос отклоняется ошибкой 400. Базовые голоса — в таблице ниже; для русской речи подходят мультиязычные Kore и Orus. Полный каталог — GET /v3/voices HeyGen (нужен ключ HeyGen).
• Остальные опции модели — там же. Все специфичные параметры avatar-iv (voice_settings, motion_prompt, expressiveness, fit, remove_background, background, caption, title) передаются, как и voice_id, внутри provider.options.heygen, а не в корне тела.
• Голос тоньше: voice_settings — объект {"speed": 0.5–1.5, "pitch": −50…50, "volume": 0–1} (все поля необязательны). Замедление речи удлиняет ролик и пропорционально увеличивает его посекундную стоимость.
• Анимация и кадр: expressiveness — "low" | "medium" | "high"; fit — "cover" (заполнить кадр с обрезкой, поведение по умолчанию) либо "contain" (вписать фото целиком, с полями).
• Замена фона — пара remove_background + background. background — объект: {"type": "color", "value": "#RRGGBB"} либо {"type": "image", "url": …} (data-URI не принимается, только настоящий URL); работает только вместе с "remove_background": true, без него молча игнорируется. Фон-картинка накладывается в границах исходного фото персонажа и растягивается под его пропорции, а область кадра за пределами фото заливается белым — чтобы фон покрыл кадр целиком и без искажений, соотношение сторон фото, фоновой картинки и ролика должно совпадать. Внутренних полей вписывания (fit и т. п.) у объекта нет — неизвестные ключи молча игнорируются.
• Субтитры (caption) — объектом: {"file_format": "srt", "style": "default"} (единственные поддерживаемые значения). Ссылку на srt-файл API сейчас не возвращает, в кадр субтитры не вжигаются — практической пользы от параметра пока нет.
• Альтернатива голосу — готовая аудиодорожка. Передайте элемент audio_url в input_references — модель липсинкует под неё, voice_id тогда не нужен.
• Фото — только JPEG. Data URI с image/png провайдер отклоняет ошибкой Content type not match image/png != image/jpeg — сконвертируйте изображение в JPEG заранее.
• На фото должно быть различимое лицо — иначе провайдер вернёт ошибку No face detected.

Базовые голоса:

{
  "model": "heygen/avatar-iv",
  "prompt": "Привет! Рады видеть вас на нашей платформе.",
  "resolution": "720p",
  "aspect_ratio": "9:16",
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "data:image/jpeg;base64,..." }
    }
  ],
  "provider": {
    "options": {
      "heygen": { "voice_id": "80441555167a467e967ab9487d844a30" }
    }
  }
}

Поддержка по моделям

Точный набор параметров и допустимых значений у каждой модели свой. Ниже — актуальный список видео-моделей RouterAI (обновляется автоматически из каталога): раскройте модель, чтобы увидеть её параметры и допустимые значения.

Шаг 2. Поллинг статуса

Опрашивайте статус задачи, пока он не станет терминальным:

curl https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC \
  -H "Authorization: Bearer $ROUTERAI_API_KEY"

Статусы:

Ответ для готовой задачи (completed):

{
  "id": "Cq4gNzomlZDrNyy72GHC",
  "status": "completed",
  "polling_url": "https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC",
  "unsigned_urls": [
    "https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC/content?index=0"
  ],
  "usage": { "cost": 18.2 }
}

unsigned_urls — ссылки на content-эндпоинт RouterAI; по ним скачивается готовое видео (см. Шаг 4).

Шаг 3. Webhook о готовности

Если при создании указан callback_url, RouterAI отправит на него POST с JSON-телом, когда задача достигнет терминального статуса (completed, failed, expired, cancelled). Это избавляет от постоянного опроса статуса.

Что приходит

{
  "type": "video.generation.completed",
  "created_at": "2026-01-01T00:00:00.000Z",
  "data": {
    "id": "Cq4gNzomlZDrNyy72GHC",
    "status": "completed",
    "generation_id": "gen-abc123",
    "model": "x-ai/grok-imagine-video",
    "unsigned_urls": [
      "https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC/content?index=0"
    ],
    "usage": { "cost": 18.2 }
  }
}

• type — тип события, одно из:
  • video.generation.completed
  • video.generation.failed
  • video.generation.expired
  • video.generation.cancelled
• data.unsigned_urls — ссылки на content-эндпоинт RouterAI (только при completed).
• data.usage.cost — стоимость в рублях (только при completed).
• data.error — текст ошибки (для failed/expired).

Заголовки запроса:

Подпись

Подпись считается над строкой "<timestamp>.<body>", где body — сырое тело запроса (та же JSON-строка, что пришла):

signature = HMAC_SHA256(secret, "<X-RouterAI-Timestamp>.<raw_body>")

Особенность RouterAI: отдельный секрет не нужен — секретом служит SHA-256-дайджест вашего API-ключа в hex. То есть вы вычисляете секрет прямо из своего ключа:

secret = sha256_hex(ROUTERAI_API_KEY)

Так подпись можно проверить, имея только свой API-ключ. Запрос подписывается ключом, которым была создана задача.

Секрет вычисляется от текущего значения ключа в момент доставки webhook. Если вы перевыпустили ключ, пока задача выполнялась, webhook будет подписан секретом от нового токена — проверяйте подпись, пересчитав секрет от актуального ключа.

Как проверить подпись

1. Прочитайте X-RouterAI-Timestamp и сырое тело запроса (до парсинга JSON).
2. Вычислите secret = sha256_hex(api_key).
3. Пересчитайте HMAC_SHA256(secret, "<ts>.<raw_body>") и сравните с X-RouterAI-Signature в постоянном времени (constant-time), не обычным ==.
4. Проверьте свежесть timestamp (например, ±5 минут) — защита от повторного воспроизведения (replay).

Node.js (Express)

const crypto = require("crypto");

// важно получить сырое тело: app.use(express.raw({ type: "application/json" }))
app.post("/hooks/routerai-video", (req, res) => {
  const apiKey = process.env.ROUTERAI_API_KEY;
  const ts = req.get("X-RouterAI-Timestamp");
  const sig = req.get("X-RouterAI-Signature");
  const rawBody = req.body; // Buffer

  // свежесть метки времени (анти-replay)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(401).end();
  }

  // секрет = sha256(api_key) в hex
  const secret = crypto.createHash("sha256").update(apiKey).digest("hex");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const ok =
    sig &&
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(rawBody.toString("utf8"));
  // ... ваша логика: event.type, event.data.unsigned_urls ...
  res.status(200).end();
});

Python (Flask)

import os, hmac, hashlib, time
from flask import request, abort

@app.post("/hooks/routerai-video")
def routerai_video():
    api_key = os.environ["ROUTERAI_API_KEY"]
    ts = request.headers.get("X-RouterAI-Timestamp", "")
    sig = request.headers.get("X-RouterAI-Signature", "")
    raw = request.get_data()  # bytes, сырое тело

    if abs(time.time() - int(ts)) > 300:
        abort(401)

    # секрет = sha256(api_key) в hex
    secret = hashlib.sha256(api_key.encode()).hexdigest()
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = request.get_json()
    # ... ваша логика: event["type"], event["data"]["unsigned_urls"] ...
    return "", 200

Доставка и ретраи

• Доставка считается успешной при ответе HTTP 2xx. Любой другой код или таймаут — неуспех.
• При неуспехе RouterAI повторяет отправку: до 10 попыток с экспоненциальной задержкой (несколько часов суммарно).
• Бюджет одной попытки — около 8 секунд (на установку соединения и ответ).
• Endpoint должен быть публично доступен — RouterAI не подключается к адресам внутри приватных сетей (защита от SSRF).

Шаг 4. Скачивание видео

Когда статус completed, скачайте готовое видео через content-эндпоинт. index — позиция ссылки в массиве unsigned_urls (по умолчанию 0):

curl "https://routerai.ru/api/v1/videos/Cq4gNzomlZDrNyy72GHC/content?index=0" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -o video.mp4

Эндпоинт отдаёт бинарный mp4. Если модель вернула несколько видео, в unsigned_urls будет несколько ссылок — скачайте каждую, меняя index (?index=1, ?index=2, …).

Лимит одновременных генераций

Одновременно у одного аккаунта может выполняться ограниченное число незавершённых видео-задач: базовый лимит — 3, он автоматически растёт с балансом (примерно один дополнительный слот на каждые 1000 ₽ баланса, но не более 50). При превышении POST /v1/videos отвечает 429 Too many active video generations — дождитесь завершения текущих задач и повторите запрос.

Активной считается задача, ещё не перешедшая в терминальный статус (completed/failed/cancelled/expired). Отклонённый провайдером или валидацией запрос слот не занимает. Если задача не получила терминального статуса от провайдера, она перестаёт учитываться в лимите через 24 часа после создания.

Устранение неполадок

429 Too many active video generations?

• Достигнут лимит одновременных незавершённых задач (см. Лимит одновременных генераций). Дождитесь завершения текущих генераций — опросите их статус через GET /v1/videos/{id}.

Не приходит webhook?

• Убедитесь, что callback_url — валидный HTTPS-адрес и публично доступен (приватные сети блокируются).
• Endpoint должен отвечать 2xx; при ошибках/таймаутах RouterAI ретраит, но после исчерпания попыток перестаёт.
• Webhook отправляется только при терминальном статусе (completed/failed/expired/cancelled).

Подпись не сходится?

• Считайте HMAC по сырым байтам тела, без JSON.parse + пересериализации.
• Секрет — это sha256_hex(api_key) именно того ключа, которым создавалась задача, а не сам ключ и не отдельный секрет.
• Подписываемая строка — "<X-RouterAI-Timestamp>.<raw_body>" (timestamp, точка, тело).

Статус failed или expired?

• Смотрите data.error (в webhook) или поле error в ответе поллинга.
• expired означает, что срок хранения результата истёк — создайте задачу заново.