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

POST /v1/videos/generations

Создаёт асинхронную джобу. Новая принятая джоба получает 202; replay и немедленные отказы могут вернуть 200/400 — точная таблица. Результат приходит через polling, вебхук добавляет push-уведомление, итоговая ссылка сейчас в data[0].url (mp4). Видео генерируется от ~1 до десятков минут в зависимости от модели и длительности.

Параметры

Поле	Тип	Описание
model	string, обяз.	ID модели, например souz/veo3-fast — каталог
prompt	string, обяз.	Описание сцены (до 5000 символов)
aspect_ratio	string	16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / auto. По умолчанию 16:9. Значение вне списка → короткий invalid_request; каноническое, но недоступное lossless-варианту → failed/capability_mismatch, price: 0, без резерва. У video auto вариант обязан объявить enum явно. Kling image-to-video сейчас не заявляет lossless aspect mapping и поэтому fail-closed не маршрутизируется до RSA-99/RSA-101
duration	string или число	Целое число секунд — строкой или числом ("5" или 5). Если поле не передано, берётся доказанный общий default доступных вариантов (Veo — 8 с, Seedance и Kling — 5 с); неоднозначный или отсутствующий proof fail-closed. Не-число → короткий invalid_request; каноническое, но неподдержанное значение → failed/capability_mismatch, price: 0, без резерва
image	string	Картинка-референс (data URL или https URL): первый кадр / оживление
images	string[]	Legacy bridge: глобальный cap 14 проверяется до обхода списка, затем модель ограничивает его до 1–2; Kling/Seedance декодируют first/last frame; Veo требует явный generationType, а FIRST_AND_LAST_FRAMES_2_VIDEO — ровно две картинки даже при нуле
audio	{generate:boolean}	Каноническая генерация звука: generate строго JSON boolean; deprecated sound/generate_audio отдельно принимают восемь legacy boolean-форм, но не сочетаются с audio
callback_url	string	Вебхук для этой джобы — подробнее
priority	string	cost / speed, default cost — что оптимизировать при выборе порядка маршрутов: цену или ожидаемое время до успеха. Меняет только порядок попыток; на цену и допустимость запроса не влияет. Значение вне словаря → короткий invalid_request. Режима «надёжность» нет: надёжность — свойство всей системы
продвинутые поля	—	Параметры конкретной модели верхним уровнем; каждый вариант проверяется отдельно, /v1/models до сертификации выключен

Цена видео = посекундный тариф провайдера × длительность × наценка платформы. Тариф зависит от ступени качества (mode у Kling 3, resolution у Seedance 2) и — только там, где звук платный (Kling 3 в режимах std/pro), — от звука; у Seedance звук бесплатен и цену не меняет. Верхняя оценка возвращается в price сразу при создании; итоговое списание после успеха считается по фактической себестоимости и оценку не превышает. Длительность, по которой считается цена, — это длительность, с которой запрос уходит к модели: значение вне capabilities.durations модели отвергается до резервирования кредитов (400, в теле failed-джоба с error.code: capability_mismatch и price: 0), а не оплачивается по запросу с молчаливой подменой на дефолт. Отказы бывают двух форм: значение вне общего словаря параметра — короткий конверт invalid_request без джобы; значение из словаря, которое не умеет выбранная модель, — failed-джоба. То же самое про aspect_ratio пока верно только для Seedance 2.0 и Veo 3.1 — см. предупреждение о Kling выше. auto — каноническое имя «пусть решает модель»: наружу оно одно, а во что оно превращается у конкретного апстрима — наша забота. Поддерживают его только модели, у которых auto есть в capabilities.aspect_ratios (сегодня Seedance 2.0 и Veo 3.1); у остальных видео-моделей запрос с auto отклоняется до резерва, как любое неподдержанное значение. Тарифы — в каталоге.

Текст → видео

curl https://api.souz.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-souz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "souz/kling-3",
    "prompt": "волна разбивается о скалы в замедленной съёмке, золотой час",
    "aspect_ratio": "16:9",
    "duration": "5",
    "mode": "pro",
    "sound": true
  }'

mode — v0 compatibility-поле Kling 3.0 (std/pro/4K): до RSA-99 оно не называется каноническим quality/resolution. sound — deprecated alias для audio.generate.

Картинка → видео (оживление)

import base64, requests

img = base64.b64encode(open("photo.jpg", "rb").read()).decode()

r = requests.post(
    "https://api.souz.ai/v1/videos/generations",
    headers={"Authorization": "Bearer sk-souz-..."},
    json={
        "model": "souz/kling-2.6",
        "prompt": "лёгкий ветер, человек улыбается и машет рукой",
        "image": f"data:image/jpeg;base64,{img}",
        "duration": "5",
    },
)

Для видео-референсов строже лимиты: PNG/JPEG, до 10 МБ; WEBP мы безопасно декодируем и конвертируем, HEIC пока отклоняется fail-closed. Всё JSON-тело ограничено 25 MiB по фактически прочитанным байтам, включая base64; для большого референса используй HTTPS URL.

Примеры продвинутых полей

Модель	Поля	Что делают
souz/kling-3	mode, sound, negative_prompt	режим std/pro/4K, звук, негативный промпт. Мультишот (multi_shots, multi_prompt) снят с профиля: запрос с любым из этих полей получает короткий 400 invalid_request до claim/job/reserve, а не «молча одним шотом». Типизированный мультишот — RSA-99
souz/kling-2.1	negative_prompt, cfg_scale	негативный промпт, строгость следования промпту (0–1)
souz/seedance-2	resolution, audio.generate (generate_audio deprecated)	разрешение 480p/720p/1080p/4k (меняет посекундный тариф) и генерация звука — звук у Seedance бесплатен и цену не меняет. Canonical форма требует boolean; legacy alias сохраняет прежние восемь представлений и сразу нормализуется. Любое другое значение → короткий invalid_request без job/reserve. camera_fixed остаётся запрещён. Полный lossless-мэппинг остальных полей — RSA-100
souz/veo3, souz/veo3-fast	generationType	режим генерации (TEXT_2_VIDEO, FIRST_AND_LAST_FRAMES_2_VIDEO, REFERENCE_2_VIDEO; последний — только на souz/veo3-fast, ровно 8 секунд и минимум один референс). seeds отсутствует в official schema и получает короткий 400 invalid_request до claim/job/reserve. Полный parity — RSA-108

Таблица выше сверена с текущими манифестами. Нормализатор принимает только typed frozen-профиль, а per-variant resolver RSA-97 исключает маршрут, который не перенесёт параметр lossless. /v1/models на первом внутреннем профиле выключен до единого сертифицированного allow-list; структурированная provider-opaque несовместимость реализована в RSA-98. Video degradation всё ещё работает fail-closed и относится к family gates RSA-99/RSA-100/RSA-108; RSA-101 публикует только Nano image first-8.

Provider-native URL-поля first_frame_url, last_frame_url, reference_*_urls, imageUrls и весь kling_elements сейчас отклоняются по факту присутствия до создания job и резерва. Используй канонические image / images. Каждое семейство вернёт типизированные aliases только через свой gate: Kling RSA-99, Seedance RSA-100, Veo RSA-108; один gate не включает другое семейство (RSA-107).

Забрать результат

Опрашивай GET /v1/jobs/{id} раз в 5–10 секунд (видео — не торопится). Можно также указать callback_url и получить ссылку вебхуком, но до устранения редкой race в RSA-109 polling остаётся обязательным fallback.

{
  "id": "job_...",
  "object": "video",
  "status": "completed",
  "price": 472500,
  "data": [{ "url": "https://api.souz.ai/v1/files/res_....mp4?exp=...&sig=..." }]
}

Скачивай файл сразу: минимальная доступность и срок фактического удаления не гарантированы; недоступная ссылка сама по себе не доказывает удаления.