Сгенерировать видео

POSThttps://api.souz.ai/v1/videos

Ролик — минуты, поэтому ответ всегда 202 с задачей в работе. Результат — GET /v1/jobs/{id} (или GET /v1/videos/{id}), поток событий или вебхук.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

Заголовки

Idempotency-Keystring

Строка до 255 символов, уникальная для аккаунта. Повтор с тем же ключом и параметрами возвращает ту же задачу с текущим статусом без новой задачи и повторного списания, в том числе при одновременных запросах, даже если настройки аккаунта за это время изменились: сравниваются только поля запроса. Другие параметры — 409 idempotency_key_conflict; store и callback_url в сравнение не входят. У изображений, видео и музыки также не сравнивается response_format; у синтеза речи формат звука сравнивается. Ключ хранится вместе с задачей, сейчас без ограничения срока. Повтор задачи со статусом failed не запускает её заново: для новой попытки нужен новый ключ. Срок хранения файлов результата — retention.files_days из GET /v1/key; повтор его не продлевает. Поддерживается для генерации изображений, видео и музыки, транскрибации, синтеза речи и чата. У чата сравнивается тело запроса целиком; повтор дожидается идущего вызова и получает тот же ответ (и поток), что первый; ответ хранится сутки.

Максимальная длина: 255

Тело запроса обязательно

application/json

Схема VideoGenerationRequest

Других полей нет.

aspect_ratiostring

Пример: "16:9"

Шаблон: ^(auto|[0-9]+:[0-9]+)$

audioboolean | null

Сгенерировать звуковую дорожку.

background_sourcestring

Пример: "input_image"

callback_urlstring · uri

character_orientationstring

Пример: "video"

duration_secondsinteger

Пример: 5

Минимум: 1

elementsarray[VideoElement]

Именованные сущности, на которые промпт ссылается как @name.

first_frameMediaSource

last_frameMediaSource

max_price_multiplierMaxPriceMultiplier | null

modelstringобязательно

Пример: "seedance-2"

output_formatstring

Значения: mp4, mov

promptstringобязательно

Минимальная длина: 1

reference_audioarray[MediaSource]

Звук — https://… или file_….

reference_videosarray[MediaSource]

Клипы — https://… или file_….

referencesarray[MediaSource]

resolutionstring

Пример: "720p"

return_last_frameboolean | null

Вернуть последний кадр вторым файлом (role: last_frame).

routingRouting

routing_optionsRoutingOptions | null

secondsодно из

Длительность в секундах, как в videos.create SDK OpenAI ("8"); то же, что duration_seconds.

Вариант 1string

Шаблон: ^[0-9]+$

Вариант 2integer

Минимум: 1

shotsarray[VideoShot]

Сцены вместо одного промпта; сумма длительностей — в пределах ролика.

sizestring

ШxВ, как в videos.create SDK OpenAI (1280x720): соотношение сторон — ближайшее из aspect_ratio модели, разрешение — по короткой стороне. Вместе с aspect_ratio или resolution не передаётся.

Пример: "1280x720"

Шаблон: ^([0-9]+x[0-9]+|auto)$

storeboolean | null

false — запрос без хранения: тексты запроса и ответа не сохраняются; файлы живут обычный срок. По умолчанию тексты хранятся; true не отменяет режим без хранения аккаунта.

userstring

Поле OpenAI (id конечного пользователя); принимается, ни на что не влияет и не хранится.

web_searchboolean | null

multipart/form-data

Схема VideoGenerationForm

input_referencestring · binary

modelstringобязательно

promptstringобязательно

secondsstring

Пример: "8"

sizestring

Пример: "1280x720"

Ответы

202Задача принята и выполняется.

application/json

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

Фактический цвет канала запроса: при успехе — канал, который выполнил запрос; пока запрос идёт — канал, которому он уже отправлен; при ошибке — последний вызванный канал. null — запрос ещё не отправлялся ни одному каналу или запись старше каналов. Название и HEX цвета — GET /v1/channels.

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

Файлы результата; data[0] — сам результат. У музыкальной модели, которая за запрос даёт два варианта трека, оба — role: result, по порядку. Пустой, пока задача не завершена, и у чата.

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

Транскрибация — язык записи, код ISO 639-1 (ru, en) у любой модели: названный моделью или, если она его не назвала, из подсказки language запроса. Язык неизвестен — поля нет.

max_price_multiplierMaxPriceMultiplier | nullобязательно

Потолок цены, с которым задача принята: из запроса или из настроек аккаунта на момент приёма. null — без потолка.

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Итог в микроединицах currency — фактический объём × цены сработавшего канала на момент приёма; null, пока задача не завершена. У проваленной — 0.

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

Настройки каналов, с которыми задача принята: из запроса или из настроек аккаунта на момент приёма. null — каналы выбирает Авто-роутинг.

segmentsarray[TranscriptionSegment]

Транскрибация, verbose_json у модели с таймкодами — фразы: предложение или отрезок речи до паузы в секунду и дольше, не длиннее 30 с. Начало фразы — начало её первого слова, конец — конец последнего; одинаково у всех моделей.

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

401Нет ключа или ключ недействителен.

application/json

Error

402Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё

Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё выполняются (insufficient_balance), или исчерпан лимит трат ключа (key_spend_limit_exceeded) либо участника, которому он выдан (member_spend_limit_exceeded). Повтор не поможет, пока баланс не пополнят, а лимит не начнётся заново или его не поднимут: потолок ключа со spend_limit_reset: none — на всё время ключа.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

404Нет такого объекта у этого аккаунта.

application/json

Error

409Тот же `Idempotency-Key` с другим телом.

application/json

Error

413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

application/json

Error

415Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

503Модель сейчас некому исполнить — повторите через `Retry-After`. На плановых работах —

Модель сейчас некому исполнить — повторите через Retry-After. На плановых работах — maintenance (ответ Maintenance).

application/json

Error

Платный метод. Запустить в плейграунде модели

Запрос

curl -X POST 'https://api.souz.ai/v1/videos' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -F 'model=<model>' \
  -F 'prompt=<prompt>' \
  --data '{
  "callback_url": "https://example.com/hooks/souz",
  "duration_seconds": 5,
  "model": "seedance-2",
  "prompt": "Рассвет над морем, камера медленно поднимается"
}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "callback_url": "https://example.com/hooks/souz",
        "duration_seconds": 5,
        "model": "seedance-2",
        "prompt": "Рассвет над морем, камера медленно поднимается",
    },
    data={"model": "<model>", "prompt": "<prompt>"},
)
print(response.json())

const form = new FormData();
form.append("model", "<model>");
form.append("prompt", "<prompt>");

const response = await fetch("https://api.souz.ai/v1/videos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "callback_url": "https://example.com/hooks/souz",
    "duration_seconds": 5,
    "model": "seedance-2",
    "prompt": "Рассвет над морем, камера медленно поднимается"
  }),
  body: form,
});
console.log(await response.json());

Ответ

{
  "attempt_count": 0,
  "completed_at": null,
  "created": 1758801600,
  "created_at": "2026-09-25T12:00:00Z",
  "currency": "RUB",
  "data": [],
  "error": null,
  "id": "job_1a2b3c4d5e6f",
  "max_price_multiplier": null,
  "modality": "video",
  "model": "seedance-2",
  "object": "job",
  "price": null,
  "routing": "cheap",
  "routing_options": null,
  "status": "queued",
  "usage": null
}

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient balance",
    "type": "billing_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}