# Создать видео-задачу

`POST /v1/videos`

> Sora-совместимое создание видео: принимает и application/json, и multipart/form-data (как `client.videos.create()` в SDK). `seconds` маппится на длительность, `size` ("1280x720") — на соотношение сторон и разрешение, `input_reference` (файл или URL) — на первый кадр. Генерация асинхронная: в ответ приходит video object со статусом `queued`, дальше статус опрашивается через GET /v1/videos/{id}. На входе проверяется баланс, а списание (по тарифу модели за секунду) — только после успешного завершения генерации.

Авторизация: заголовок `Authorization: Bearer <API-ключ>` (ключ sk-aiagg-… из личного кабинета). Base URL: `https://api.trackly.one/v1`.

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

## Тело запроса

Content-Type: `multipart/form-data`, `application/json`.

Неизвестные поля не отбрасываются, а уезжают passthrough-ем в provider-specific параметры генерации — за их валидность отвечает клиент. Файл `input_reference` в multipart — до 20 МБ.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `model` | `string` | да | Id видео-модели, например google/veo-3.1-fast |
| `prompt` | `string` | да | Текстовое описание ролика. Длина 1–5000 символов |
| `seconds` | `string \| integer` | нет | Длительность в секундах. По умолчанию: "4" |
| `size` | `string \| null` | нет | Размер кадра "WxH", например "1280x720". Маппится на соотношение сторон и разрешение (меньшая сторона ≥1080 → 1080p, иначе 720p) |
| `input_reference` | `file \| url \| ImageInput \| null` | нет | Первый кадр: файл в multipart, URL-строка или ImageInput-объект в JSON |
| `generate_audio` | `boolean \| null` | нет | Генерировать ли звуковую дорожку (для моделей со звуком) |
| `seed` | `integer \| null` | нет | Сид для воспроизводимости. Диапазон 0–∞ |
| `negative_prompt` | `string \| null` | нет | Чего в кадре быть не должно |

## Схема ImageInput

Картинка, которую юзер передал во входе запроса.

Два варианта `type`:
  - `url`     — внешний URL, провайдер (или мы) скачаем по запросу.
  - `base64`  — уже сырые байты в base64 (без data:image/...; префикса).

`mime_type` обязателен для base64 (нужен Gemini для inline_data),
для url — опционально (можно определить из ответа).

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `data` | `string` | да | Длина 1–∞ символов |
| `mime_type` | `string \| null` | нет | image/png, image/jpeg, image/webp |
| `type` | `"url" \| "base64"` | да | — |

## Схема VideoObject

Video job object в формате Sora API.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `completed_at` | `integer \| null` | нет | — |
| `created_at` | `integer` | да | — |
| `error` | `VideoErrorObject \| null` | нет | — |
| `expires_at` | `integer \| null` | нет | — |
| `id` | `string` | да | — |
| `model` | `string` | да | — |
| `object` | `"video"` | нет | По умолчанию: "video" |
| `progress` | `integer` | да | — |
| `prompt` | `string` | да | — |
| `seconds` | `string` | да | — |
| `size` | `string \| null` | нет | — |
| `status` | `"queued" \| "in_progress" \| "completed" \| "failed"` | да | — |

## Схема VideoErrorObject

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `code` | `string` | да | — |
| `message` | `string` | да | — |

## Ответы

| Код | Описание | Схема |
| --- | --- | --- |
| 200 | Успешный ответ | `VideoObject` |

## Пример запроса

```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
from openai import OpenAI

client = OpenAI(
    api_key="sk-aiagg-...",
    base_url="https://api.trackly.one/v1",
)

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

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-aiagg-...",
  baseURL: "https://api.trackly.one/v1",
});

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
```

## Пример ответа

```json
{
  "id": "video_5f2c1d8e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
  "object": "video",
  "model": "google/veo-3.1-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1752396600,
  "seconds": "8",
  "size": "1280x720",
  "prompt": "Дрон летит над зимним лесом на рассвете, мягкий свет"
}
```