# Генерация видео: как использовать

> Гайд по /v1/videos в Sora-стиле — создание задачи, опрос статуса, скачивание MP4, параметры seconds/size/input_reference и legacy-алиас.

Веб-версия: https://ai.trackly.one/developers/docs/video · Индекс документации: https://ai.trackly.one/llms.txt

Видео генерируется асинхронно, цикл Sora-совместимый: `POST /v1/videos`
создаёт задачу, `GET /v1/videos/{id}` опрашивает статус,
`GET /v1/videos/{id}/content` отдаёт готовый MP4. Модель обязательна —
например, `google/veo-3.1-fast` или `kling/v3`. Баланс проверяется при
создании задачи, а списание (тариф за секунду) происходит только после
успешного завершения генерации.

## Как устроен цикл генерации?

Три шага. Создали задачу — получили video object со статусом `queued`.
Опрашиваете статус — он проходит `queued` → `in_progress` → `completed`
(или `failed`, тогда в `error` будут `code` и `message`). Дождались
`completed` — скачиваете MP4. Генерация занимает минуты, поэтому опрашивать
раз в 5-10 секунд более чем достаточно.

## Как создать задачу?

Эндпоинт принимает и `application/json`, и `multipart/form-data` — второй
формат использует `client.videos.create()` из OpenAI SDK.

**POST /v1/videos**

```bash
curl https://api.trackly.one/v1/videos \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1-fast",
    "prompt": "Дрон летит над зимним лесом на рассвете",
    "seconds": "8",
    "size": "1280x720"
  }'
```

```python
video = client.videos.create(
    model="google/veo-3.1-fast",
    prompt="Дрон летит над зимним лесом на рассвете",
    seconds="8",
    size="1280x720",
)
print(video.id, video.status)  # video_<uuid> queued
```

```javascript
const video = await client.videos.create({
  model: "google/veo-3.1-fast",
  prompt: "Дрон летит над зимним лесом на рассвете",
  seconds: "8",
  size: "1280x720",
});
console.log(video.id, video.status); // video_<uuid> queued
```

Параметры:

- `prompt` — обязателен, до 5000 символов.
- `model` — обязателен, дефолта нет. Видео-модели помечены в
  [каталоге](https://ai.trackly.one/developers/models).
- `seconds` — длительность, строкой или числом («4», «6», «8»). Шлюз
  принимает 1-60, фактический набор длительностей задаёт модель: Veo 3.1 —
  4, 6 или 8 секунд.
- `size` — «ШИРИНАxВЫСОТА»: `1280x720` (16:9), `720x1280` (вертикальное
  9:16), `1920x1080` (16:9 в 1080p). Внутри маппится на соотношение сторон
  и разрешение; 1080p получается, когда меньшая сторона ≥ 1080.
- `input_reference` — стартовый кадр для image-to-video: в multipart —
  файл (до 20 МБ), в JSON — URL картинки.
- provider-specific поля — `generate_audio`, `seed`, `negative_prompt` —
  принимаются в JSON и уходят провайдеру.

Полная схема запроса и ответа — в
[референсе создания видео](https://ai.trackly.one/developers/docs/reference/videos-create).

## Как узнать, что видео готово?

Опрашивать `GET /v1/videos/{id}` — именно этот запрос продвигает статус
(мы ходим к провайдеру в момент вашего опроса). `progress` грубый: 0, 50 или
100 — точных процентов провайдеры не отдают. Поля ответа — в
[референсе статуса](https://ai.trackly.one/developers/docs/reference/videos-retrieve).

**Опрос до готовности**

```bash
curl https://api.trackly.one/v1/videos/video_5f2c1d8e-... \
  -H "Authorization: Bearer $TRACKLY_API_KEY"
```

```python
import time

while video.status in ("queued", "in_progress"):
    time.sleep(10)
    video = client.videos.retrieve(video.id)

if video.status == "failed":
    raise RuntimeError(video.error)
```

```javascript
while (video.status === "queued" || video.status === "in_progress") {
  await new Promise((r) => setTimeout(r, 10_000));
  video = await client.videos.retrieve(video.id);
}
if (video.status === "failed") throw new Error(video.error?.message);
```

Списание за генерацию происходит в момент перехода в `completed`. Задача
завершилась с `failed` — денег не берём.

## Как скачать результат?

`GET /v1/videos/{id}/content` отдаёт байты MP4 (`Content-Type: video/mp4`).
Скачивание бесплатное, сколько угодно раз. Если генерация ещё идёт, придёт
409 `video_not_ready`; чужой или несуществующий id — 404 (коды разобраны в
гайде [«Ошибки API»](https://ai.trackly.one/developers/docs/errors)).

**GET /v1/videos/{id}/content**

```bash
curl https://api.trackly.one/v1/videos/video_5f2c1d8e-.../content \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  --output video.mp4
```

```python
content = client.videos.download_content(video.id)
content.write_to_file("video.mp4")
```

```javascript
import fs from "node:fs";

const content = await client.videos.downloadContent(video.id);
fs.writeFileSync("video.mp4", Buffer.from(await content.arrayBuffer()));
```

Список всех задач ключа — `GET /v1/videos` с курсорной пагинацией
(`limit` до 100, `after` — id последнего видео предыдущей страницы, в ответе
`has_more`). Список статусы не продвигает — только `GET /v1/videos/{id}`.

## Что за /v1/video/generations?

Наш исходный, до-Sora формат: `POST /v1/video/generations` возвращает 202 и
job в статусе `processing`, статус и скачивание — по
`GET /v1/video/generations/{job_id}` и `.../download`. Он остаётся рабочим
документированным алиасом — существующие интеграции ломать не будем. Для
нового кода берите `/v1/videos`: его понимает OpenAI SDK.

## Сколько стоит видео?

Тариф — за секунду готового ролика, у каждой модели свой. Актуальные цены —
на странице [цен для разработчиков](https://ai.trackly.one/developers/pricing). Посмотреть, как
генерирует Veo 3.1, без кода можно [на сайте](https://ai.trackly.one/chat/veo-3-1).