# Видео

`POST /v1/videos` — всегда `202` с задачей. Результат —
`GET /v1/jobs/{id}` (или `GET /v1/videos/{id}`, совместимо с `videos.retrieve` SDK OpenAI),
поток событий или вебхук. Поля — схема `VideoGenerationRequest` и `input_schema` модели.

```bash
curl https://api.souz.ai/v1/videos \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: teaser-7" \
  -d '{"model": "seedance-2", "prompt": "рассвет над морем, камера медленно поднимается", "duration_seconds": 5, "callback_url": "https://example.com/hooks/souz"}'
```

## Поля ролика

По карточке модели: `duration_seconds`, `aspect_ratio`, `resolution`, `audio`, кадры
`first_frame` и `last_frame`, наборы `references[]`, `reference_videos[]`,
`reference_audio[]`, именованные `elements[]` (промпт ссылается на них как `@name`), сцены
`shots[]`, `return_last_frame` — последний кадр вторым файлом с `role: "last_frame"`. Кадры
и набор референсов взаимоисключающие. Для `reference_videos[]` и `reference_audio[]`
подойдут HTTPS-ссылки или `file_…` из [`POST /v1/files`](https://souz.ai/docs/files.md).

## `videos.create` SDK OpenAI

`client.videos.create` шлёт форму `multipart/form-data` — она принимается так же, как JSON:
`seconds` (`"8"`) — то же, что `duration_seconds`; `size` (`"1280x720"`) — соотношение
сторон из `aspect_ratio` модели и разрешение по короткой стороне; `input_reference` (файл
картинки или ссылка) — первый кадр. Остальные поля — через `extra_body`. `size` вместе с
`aspect_ratio` или `resolution`, `seconds` с другим `duration_seconds` — `400` с
`mutually_exclusive`.

```python tab="Python"
video = client.videos.create(model="seedance-2", prompt="волны у маяка", seconds="8", size="1280x720")
video = client.videos.retrieve(video.id)
```

У `kling-3.0` и `kling-3.0-motion-control` кадр — картинка с пропорциями от 1:2.5 до 2.5:1.
Другой кадр — `400 invalid_input` до запуска модели: в `detail[]` поле кадра,
`out_of_range` и `"allowed": ["aspect ratio from 1:2.5 to 2.5:1"]`.

## Как получить ролик

Серверу — `callback_url` ([вебхук](https://souz.ai/docs/webhooks.md)); скрипту — поток событий или опрос
`GET /v1/jobs/{id}` раз в `Retry-After` секунд
([Задачи и долгие операции](https://souz.ai/docs/jobs.md)). Цена — за оплачиваемые секунды
ролика (`billed_seconds`).

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.