Создание задачи генерации видео

Общие сведения

• Base URL: https://api.routeapi.ai
• Аутентификация: Authorization: Bearer $ROUTEAPI_KEY с API Key, начинающимся с sk- (создаётся на странице API-ключи). Управляющие ключи с префиксом rat_ не могут вызывать модели.
• Формат ошибок: после маршрутизации эндпоинты задач отвечают телом {"code": "...", "message": "...", "data": null}. Запросы, отклонённые до маршрутизации (отсутствующий или недействительный API Key, ограничение по IP, нет доступа к группе или модели), получают стандартное тело {"error": {"message": "...", "type": "error", "code": "..."}}. Значения кодов состояния см. в разделе Частые ошибки.

Генерация видео в RouteAPI — это асинхронный API задач. Вы отправляете запрос, получаете task_id, опрашиваете задачу до её завершения, а затем скачиваете видео. Все видеомодели платформы — Seedance, Sora, Veo, Wan, Kling, Hailuo, Vidu и другие — вызываются через одни и те же эндпоинты, потому что RouteAPI преобразует ваш запрос в формат, ожидаемый выбранным вышестоящим поставщиком.

Видеомодели присутствуют в GET /v1/models; в supported_endpoint_types отображается openai-video для каналов, работающих через формат видео OpenAI, а на странице модели в консоли значение можно задать для каждой модели. В любом случае берите ID модели из этого списка — см. Модели. Параметры конкретных моделей описаны по поставщикам: Seedance, Hailuo, Wan. Диалект OpenAI/Sora того же API описан в разделе Формат видео OpenAI.

Эндпоинты

Метод	Путь	Назначение	Где описано
POST	/v1/video/generations	Отправить задачу генерации	Эта страница
GET	/v1/video/generations/{task_id}	Прочитать запись задачи	Получение задачи видео
POST	/v1/videos	Отправить задачу генерации (диалект OpenAI)	Формат видео OpenAI
GET	/v1/videos/{task_id}	Прочитать задачу как объект видео OpenAI	Формат видео OpenAI
POST	/v1/videos/{video_id}/remix	Создать задачу на основе существующего видео	Формат видео OpenAI
GET	/v1/videos/{task_id}/content	Скачать байты готового видео	Получение задачи видео

POST /v1/video/generations и POST /v1/videos — два пути к одной операции с разными диалектами запроса и ответа. Ответ на отправку в обоих случаях — объект видео OpenAI; GET-эндпоинты различаются (запись задачи и объект видео), поэтому каждый путь отправки сочетайте с соответствующим GET.

Как выполняется задача

1. Отправка — передайте промпт и модель в POST /v1/video/generations (или POST /v1/videos) и сохраните task_id из ответа. На этом шаге оценочная стоимость резервируется на вашем балансе.
2. Опрос — вызывайте соответствующий GET каждые 10–15 секунд. Генерация обычно занимает от одной до нескольких минут; более высокое разрешение и большая длительность требуют больше времени.
3. Завершение — когда статус сообщает об успехе, скачайте видео или прочитайте его URL. Если задача завершилась ошибкой или так и не достигла конечного состояния, зарезервированная сумма возвращается.

Note

RouteAPI опрашивает вышестоящего поставщика в фоне примерно каждые 15 секунд, поэтому ваш опрос лишь читает запись задачи. Задача, не достигшая конечного состояния, помечается как неуспешная и возвращается после тайм-аута платформы (по умолчанию 24 часа), так что бесконечно повторять запросы не нужно.

Отправка задачи

POST /v1/video/generations

Поля запроса

Каждая видеомодель принимает эту общую структуру. Параметры конкретной модели помещаются в metadata; страницы поставщиков перечисляют ключи, которые фактически читает каждый адаптер.

Поле	Тип	Обязательно	Описание
model	string	Да	ID модели из GET /v1/models
prompt	string	Да	Текстовый промпт. Отсутствующий, пустой или состоящий из пробелов промпт отклоняется с 400
image	string	Нет	Одно изображение (URL или Base64/data URI). Считается первым элементом images
images	string[]	Нет	Референсные / первые кадры. Смысл зависит от модели
size	string	Нет	Подсказка размера или разрешения, например 1280x720 или 720p, в зависимости от модели
duration	integer	Нет	Длительность в секундах. RouteAPI отклоняет отрицательные значения и значения больше 3600
seconds	string	Нет	Устаревшая строковая форма длительности. Модели, которые её читают, используют её вместо duration
input_reference	string	Нет	Поле референсного изображения в стиле OpenAI, читается поддерживающими его адаптерами (например, Sora и Wan)
ratio	string	Нет	Соотношение сторон, например 16:9 или 9:16; читается адаптером Seedance
resolution	string	Нет	Уровень выходного разрешения, например 720p или 1080p; читается адаптером Seedance
generate_audio	boolean	Нет	Генерировать звуковую дорожку. В Seedance явный false передаётся, а не отбрасывается
metadata	object	Нет	Параметры поставщика. В Seedance при совпадении имён значение из metadata важнее значения верхнего уровня

Неизвестные RouteAPI поля верхнего уровня игнорируются; параметры конкретной модели помещайте в metadata.

Эндпоинты отправки также принимают тело multipart/form-data: скалярные поля формы сопоставляются с теми же именами, а файлы загружаются напрямую (например, input_reference для Sora). Неизвестные поля формы становятся записями metadata.

Caution

Не каждый поставщик читает каждое общее поле. ratio, resolution и generate_audio интерпретирует адаптер Seedance; Veo читает metadata.durationSeconds, metadata.resolution и metadata.aspectRatio, используя size как запасной вариант; Wan читает size и metadata; Sora читает size, seconds и входные изображения. Перед тем как полагаться на поле, проверьте страницу поставщика: поле, которое поставщик не распознаёт, молча отбрасывается, а не отклоняется.

Пример отправки

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "An orange cat stretching on a windowsill at sunrise",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

Ответ на отправку

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

task_id (и его псевдоним id) — это ID задачи RouteAPI; все последующие вызовы используют его. ID задачи вышестоящего поставщика — не то значение, которое нужно опрашивать: если оно вообще видно, то находится в сохранённой полезной нагрузке вышестоящего сервиса (data.data в записи задачи).

Успешная отправка также возвращает заголовок X-New-Api-Other-Ratios с применёнными тарифными множителями — например, {"seconds":5,"size":1} для Sora или {"video_input":0.608695652174} для запроса Seedance с видео на входе. Он полезен при сверке списаний.

Ошибки этапа отправки

После маршрутизации эндпоинты задач отвечают в формате ошибки задач:

{ "code": "invalid_request", "message": "prompt is required", "data": null }

Статус	Код	Значение
400	invalid_request	Отсутствует или пустой prompt, поле metadata неверного типа, или тело не удаётся разобрать
400	invalid_json	Неверный JSON в адаптерах, которые сами проверяют тело (Sora и Wan)
400	missing_model	Отсутствует model; возвращается адаптерами, которые сами проверяют тело (Sora и Wan). Остальные пути отклоняют запрос без модели до маршрутизации, как ошибку middleware
400	invalid_seconds	duration / seconds отрицательно или больше 3600
400	invalid_size	Модель не принимает такой размер, например неподдерживаемый размер Sora
400	model_price_error	RouteAPI не смог рассчитать цену модели; запрос не отправляется
400	model_not_supported	Модель соответствует модели, которую канал больше не обслуживает, например Seedance 1.x
400	task_not_exist	Исходная задача remix неизвестна или принадлежит другому аккаунту
400	task_source_unavailable	Канал исходной задачи remix удалён, отключён, или адаптер для него отсутствует
403	insufficient_user_quota / pre_consume_token_quota_failed	Баланс аккаунта или квота ключа не покрывают оценочную стоимость; запрос не отправляется
429	—	Ёмкость вышестоящего сервиса исчерпана; сообщение заменяется общим текстом «повторите позже»
500	build_request_failed, do_request_failed, invalid_response	Задачу не удалось преобразовать, соединение с вышестоящим сервисом не удалось, или он не вернул ID задачи
500	get_channel_failed, task_persistence_failed, gen_relay_info_failed	RouteAPI не смог выбрать канал или записать задачу; списание не происходит (резерв возвращается)
502	upstream_task_id_missing	Вышестоящий сервис принял задачу, но не вернул её ID; задача помечается как неуспешная, резерв освобождается
любой	fail_to_fetch_task	Вышестоящий сервис ответил на отправку статусом, отличным от 200; HTTP-статус берётся у него

Запросы, отклонённые до маршрутизации — отсутствующий или недействительный API Key (401), ограничение по IP, группа без доступа, модель вне списка разрешённых для ключа (403) или модель без доступного канала (503, код model_not_found) — используют стандартное тело ошибки middleware {"error": {"message": ..., "type": "error", "code": ...}}, а не формат задачи.

Сбои, происходящие после отправки (модерация контента, тайм-аут поставщика, отмена), не проявляются как HTTP-ошибки. Они видны как FAILURE в записи задачи вместе с fail_reason, а зарезервированная сумма возвращается.

Что дальше

• Получение задачи видео — опрос записи, чтение статуса и скачивание результата.
• Seedance, Hailuo, Wan — параметры и ограничения конкретных моделей.
• Материалы (Assets) — загрузка переиспользуемых изображений, видео и аудио и ссылки на них через asset://.
• Частые ошибки — коды состояния, общие для всех эндпоинтов моделей.