> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Генерация видео apimart-zoe

> Генерация и редактирование видео по тексту, кадрам и референсам изображений/видео/аудио: 480p–4k, последний кадр, MOV и переход от черновика к финальному видео.

> [!NOTE]
>
> API работает асинхронно. После отправки прочитайте `data[0].task_id` и используйте [запрос статуса задачи](https://docs.apimart.ai/ru/api-reference/tasks/status.md). Обычно генерация занимает 1–3 минуты; рекомендуемый интервал опроса — 5–10 секунд. Фактическое время зависит от задачи.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "apimart-zoe",
    "prompt": "Рыжий котёнок на подоконнике смотрит в камеру, солнечный свет падает сбоку, камера медленно приближается",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "Рыжий котёнок на подоконнике смотрит в камеру, солнечный свет падает сбоку, камера медленно приближается",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "apimart-zoe",
    "prompt": "Рыжий котёнок на подоконнике смотрит в камеру, солнечный свет падает сбоку, камера медленно приближается",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}
```

## Выбор режима

| Режим | Параметры |
| - | - |
| Видео по тексту | `prompt` без материалов. |
| Видео по кадрам | Роли `first_frame` и необязательная `last_frame` в `image_with_roles`, либо `first_frame_image` / `last_frame_image`. |
| Видео по референсам | Референсные изображения или видео, при необходимости с аудио. Только аудио не поддерживается. |
| Черновик | `draft: true`, выходное разрешение `480p`. |
| Финальное видео | `draft_task_id` успешного черновика, выходное разрешение `1080p`. |
| Редактирование видео | Укажите `omni_reference_task_type: "edit"` и хотя бы одно исходное видео. Длительность и формат кадра следуют источнику. |

## Заголовки

**Authorization** `string` *required*

Авторизация: `Bearer <token>`, где `<token>` — ключ API APIMart. Для тела запроса используйте `Content-Type: application/json`.

## Параметры запроса

**model** `string` *required*

Всегда `apimart-zoe`.

**prompt** `string`

До 204 800 символов. Обязателен для видео по тексту; при передаче только материалов можно опустить. При использовании `draft_task_id` передавать нельзя: текст наследуется от черновика.

**resolution** `string`

`480p`, `720p`, `1080p`, `2k`, `4k`, без учёта регистра. Обычная генерация: по умолчанию `720p`. При `draft: true` допускается только `480p`, это же значение используется при пропуске. При `draft_task_id` допускается только `1080p`, включая значение по умолчанию.

**aspect\_ratio** `string`

`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. По умолчанию `adaptive`: формат определяет модель или материалы. Для финального видео поле запрещено — формат наследуется от черновика.

Для редактирования (`edit`) поле нужно опустить или передать `adaptive`, чтобы сохранить формат исходного видео.

**size** `string`

Другое имя для `aspect_ratio`, с теми же значениями. Рекомендуется передавать только одно из полей. Для финального видео опустите.

**duration** `integer`

Обычная генерация: Целые секунды `4`–`30`, по умолчанию `5`. Оплачивается заданная или стандартная длительность, без корректировки по готовому видео. При `-1` решает модель: резервируется 30 секунд, затем сумма пересчитывается по фактической длительности, округлённой до ближайшей целой секунды (0.5 вверх). Для финального видео опустите: длительность наследуется от черновика.

Для редактирования (`edit`) поле нужно опустить или передать `-1`. При пропуске также используется `-1`; длительность следует исходному видео.

**seconds** `integer`

Псевдоним `duration`, с теми же правилами. Передавайте только одно из полей. Для финального видео опустите.

**audio** `boolean`

Логический параметр генерации звука вместе с видео. Псевдоним: `generate_audio`. Если опущен, решает модель. Для финального видео запрещён. Управляет выходным звуком, а не входными референсами `audio_urls`.

При одновременной передаче `audio` и `generate_audio` значения должны совпадать, иначе HTTP 400. Если они опущены, модель решает сама и обычно добавляет звук.

**generate\_audio** `boolean`

Псевдоним `audio` с теми же правилами. Используйте одно из полей; для финального видео опустите.

При одновременной передаче `audio` и `generate_audio` значения должны совпадать, иначе HTTP 400. Если они опущены, модель решает сама и обычно добавляет звук.

**seed** `integer`

Целочисленный случайный seed. Для финального видео запрещён.

**nsfw\_check** `boolean`

По умолчанию модерация отключена. Для включения передайте `true`.

Необязательный логический параметр. `true` включает модерацию `prompt`, `image_urls`, `image_with_roles`, первого/последнего кадров и изображений `asset://`. Референсные видео и аудио не проверяются.

Запрос финального видео не содержит текста или материалов; в процессе «черновик → финальное видео» модерация выполняется при создании черновика.

При обнаружении возвращается HTTP 400 (`nsfw_content_detected`), категории указаны в `error.message`. Показывайте отказ модерации, а не общую ошибку параметров. При сбое или недоступности сервиса модерации генерация продолжается, поэтому включение параметра не гарантирует завершённую проверку каждого запроса.

**omni\_reference\_task\_type** `string`

Поддерживает `auto` (по умолчанию, как при пропуске; решает модель), `reference` и `edit`. `reference` / `edit` требуют референсных материалов; для чистого текста или первого/последнего кадров возвращается HTTP 400. Для `edit` нужно хотя бы одно видео в `video_urls`; сочетание с `draft: true` запрещено. `extend` не поддерживается и возвращает HTTP 400. Не передавать при финальной генерации.

**return\_last\_frame** `boolean`

При `true` дополнительно возвращает PNG последнего кадра в `data.result.last_frame_url`. По умолчанию отключено. Не передавать при финальной генерации.

**output\_format** `string`

`mp4` (по умолчанию) или `mov` (контейнер QuickTime); другие значения дают HTTP 400. Псевдоним — `response_format`; при обоих полях приоритет у `output_format`. Не передавать при финальной генерации.

**response\_format** `string`

Псевдоним `output_format`, значения `mp4` / `mov`. При обоих полях приоритет у `output_format`. Не передавать при финальной генерации.

**enhance\_prompt** `boolean`

При `true` автоматически улучшает промпт перед генерацией. По умолчанию используется исходный промпт без оптимизации. Не передавать при финальной генерации.

**image\_with\_roles** `object[]`

Каждый элемент содержит `url` и `role`. Роли: `first_frame` (первый кадр), `last_frame` (последний), `reference_image` (референс). Не более одного первого и одного последнего кадра. Последний кадр требует первого. Кадры нельзя сочетать с референсными материалами.

Нельзя одновременно передавать `image_urls` и `image_with_roles`: при отправке возвращается HTTP 400 (`invalid_request_error`) без оплаты. Псевдонимы `image`, `images`, `image_url` также считаются `image_urls` и не обходят это ограничение.

**image\_urls** `string[]`

До 30 референсных изображений. Форматы, размеры и ограничения файлов приведены ниже.

Нельзя одновременно передавать `image_urls` и `image_with_roles`: при отправке возвращается HTTP 400 (`invalid_request_error`) без оплаты. Псевдонимы `image`, `images`, `image_url` также считаются `image_urls` и не обходят это ограничение.

**first\_frame\_image** `string`

Адрес первого кадра; эквивалент роли `first_frame` в `image_with_roles`.

**last\_frame\_image** `string`

Адрес последнего кадра; эквивалент роли `last_frame` в `image_with_roles`. Первый кадр также обязателен.

**video\_urls** `string[]`

До 10 референсных видео. Общедоступные URL `http(s)` или `asset://<ID материала>`, без `data:` Base64. Размеры, точная длительность и частота кадров проверяются при отправке по правилам ниже.

Для оплаты длительности складываются, затем сумма округляется вниз до целых секунд и больше не меняется. Это округление не применяется при проверке длительности отдельного видео. Недоступность или ошибка определения длительности: HTTP 400 (`input_video_probe_failed`) без оплаты.

`auto` / `reference`: 2–15 секунд, допустимо `1.8 ≤ t ≤ 15.2`. Исходное видео для `edit`: 4–30 секунд, допустимо `3.8 ≤ t < 30.2`. Проверяется точная длительность без предварительного округления.

**audio\_urls** `string[]`

До 10; WAV / MP3; каждое 2–15 секунд и `≤ 15 MB`, суммарно до 30 секунд. Допуск ±0.2 секунды: каждое `1.8 ≤ t ≤ 15.2`, сумма `≤ 30.2`. Нужно референсное изображение или видео.

Публичный `http(s)` URL или `asset://<ID материала>`, без `data:` Base64. Длительность аудио проверяется при отправке; нарушение даёт синхронный HTTP 400 без оплаты.

**draft** `boolean`

`true` создаёт черновик `480p`. Остальные параметры подчиняются правилам обычной генерации. Не передавайте при создании финального видео.

Редактирование видео (`edit`) не поддерживает черновики.

**draft\_task\_id** `string`

`task_id` успешного черновика для создания финального видео `1080p`. Используйте в течение 24 часов после создания черновика. Текст, материалы, длительность и формат наследуются; повторная передача этих полей запрещена. При создании финального видео также запрещены `seed`, `audio` и его псевдоним `generate_audio`.

## Адреса и ограничения материалов

Изображения, видео и аудио принимают публичные `http(s)` URL или материалы APIMart `asset://<ID материала>`. Ни один тип не принимает `data:` Base64: сначала загрузите файл. Регистрация автоматическая, отдельный API-вызов не нужен. При её сбое задача завершается ошибкой с возвратом средств.

| Материалы | Требования |
| - | - |
| Изображения | До 30; JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF; соотношение сторон 0.4–2.5; ширина и высота по 300–6000 пикселей; каждое `< 30 MB`. |
| Видео | До 10; MP4 / MOV (H.264 / H.265; аудиодорожка: AAC / MP3); каждое `≤ 200 MB`. Требования к размерам, длительности и частоте кадров приведены ниже. |
| Аудио | До 10; WAV / MP3; каждое 2–15 секунд и `≤ 15 MB`, суммарно до 30 секунд. Допуск ±0.2 секунды: каждое `1.8 ≤ t ≤ 15.2`, сумма `≤ 30.2`. Нужно референсное изображение или видео. |

### Проверка референсного видео

| Параметр | Требование |
| - | - |
| Ширина и высота | Ширина и высота — каждая 300–6000 пикселей. |
| Площадь в пикселях (ширина × высота) | 409 600–8 295 044 пикселей. |
| Соотношение сторон (ширина / высота) | 0.4–2.5. |
| Длительность каждого видео | `auto` / `reference`: 2–15 секунд, допустимо `1.8 ≤ t ≤ 15.2`. Исходное видео для `edit`: 4–30 секунд, допустимо `3.8 ≤ t < 30.2`. Проверяется точная длительность без предварительного округления. |
| Частота кадров | Сначала округлить до ближайшего целого (0.5 вверх), затем проверить диапазон 24–60fps. 23.976 и 59.94 допустимы. |

Размеры видео, площадь в пикселях, соотношение сторон, точная длительность и частота кадров, а также длительность референсного аудио проверяются при отправке. Нарушение даёт синхронный HTTP 400 без оплаты. Ошибки видео используют `invalid_request_error` и содержат измерения. Проверяйте площадь, а не короткую сторону от 480 и длинную до 4096.

Только по размерам: 420×1000 (420 000 пикселей) допустимо. 720×480 (345 600), 848×480 (407 040) и 4096×2160 (8 847 360 пикселей) не проходят ограничения площади. Длительность, частота кадров и остальные требования тоже должны соблюдаться.

Размеры изображений, размер файла и кодирование проверяются во время генерации. Несоответствие приводит к ошибке задачи с автоматическим возвратом средств. По возможности проверяйте эти свойства до вызова API.

### Правила сочетания материалов

* Нельзя одновременно передавать `image_urls` и `image_with_roles`: при отправке возвращается HTTP 400 (`invalid_request_error`) без оплаты. Псевдонимы `image`, `images`, `image_url` также считаются `image_urls` и не обходят это ограничение.
* Первый/последний кадры нельзя сочетать в одном запросе с референсными изображениями, видео или аудио.
* Не более одного первого и одного последнего кадра. Последний кадр требует первого.
* До 30 изображений, 10 видео и 10 аудиореференсов; всего не более 50 материалов.
* Нарушение ограничений сочетания или количества возвращает синхронный HTTP 400 без списания средств.
* Для `omni_reference_task_type: "edit"` нужно хотя бы одно исходное видео (`3.8 ≤ t < 30.2` секунд). `duration` / `seconds`: только пропуск или `-1`; `aspect_ratio` / `size`: только пропуск или `adaptive`. Нельзя сочетать с `draft: true`. Для auto/reference сохраняются 2–15 секунд с указанным допуском.

> [!WARNING]
>
> Следующие поля дают HTTP 400 при самом наличии, даже со значениями `""`, `[]`, `false` или `null`; полностью удалите их: `negative_prompt`, `camera_fixed`, `camerafixed`, `extend_from_task_id`, `mask_url`, `video_list`, `element_list`, `multi_shot`, `tools`. `n` нужно опустить или задать `1`.

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

URL ниже приведены для примера. Замените их доступными адресами материалов.

### Первый и последний кадры

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Плавный переход от первого кадра к последнему с сохранением освещения",
  "image_with_roles": [
    {
      "url": "https://example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/end.jpg",
      "role": "last_frame"
    }
  ],
  "duration": 6
}
```

Также можно использовать `first_frame_image` и `last_frame_image`. Не добавляйте референсные изображения, видео или аудио в этот же запрос.

### Изображения, видео и аудио как референсы

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Персонаж с изображения естественно движется в сцене из референсного видео, музыка соответствует ритму изображения",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://example.com/bgm.mp3"
  ],
  "duration": -1
}
```

Изображения в `image_urls` считаются референсами. При `duration: -1` модель определяет длительность результата.

### Редактирование видео

Для `omni_reference_task_type: "edit"` нужно хотя бы одно исходное видео (`3.8 ≤ t < 30.2` секунд). `duration` / `seconds`: только пропуск или `-1`; `aspect_ratio` / `size`: только пропуск или `adaptive`. Нельзя сочетать с `draft: true`. Для auto/reference сохраняются 2–15 секунд с указанным допуском.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Превратить сцену в классический чёрно-белый фильм, сохранив движение камеры и композицию",
  "video_urls": [
    "https://example.com/source_20s.mp4"
  ],
  "omni_reference_task_type": "edit"
}
```

Редактирование использует тариф с референсным видео. Сначала резервируются 30 секунд выхода, затем расчёт корректируется по фактической длительности, округлённой до целых секунд. Длительность референсов учитывается по формуле ниже.

### Последний кадр, MOV и оптимизация промпта

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Рыжий котёнок на подоконнике смотрит в камеру, солнечный свет падает сбоку, камера медленно приближается",
  "duration": 5,
  "return_last_frame": true,
  "output_format": "mov",
  "enhance_prompt": true
}
```

## Черновик → финальное видео

1. Отправьте черновик с `draft: true`. Если `resolution` опущен, используется `480p`; при явном указании также допустим только `480p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Рыжий котёнок на подоконнике смотрит в камеру, солнечный свет падает сбоку, камера медленно приближается",
  "draft": true
}
```

2. Дождитесь успеха черновика и отправьте его `task_id` для финального видео. Достаточно `model` и `draft_task_id`. При явном указании `resolution` допустим только `1080p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}
```

> [!WARNING]
>
> Финальное видео наследует промпт, материалы, длительность, формат кадра, seed и звук черновика. Передавайте `model`, `draft_task_id`, необязательный `resolution: "1080p"` и общие поля вроде `nsfw_check` / `webhook`. Следующие поля генерации должны отсутствовать; пустые строки/массивы, `false` и `null` тоже дают HTTP 400: `prompt`, `image_urls`, `image_with_roles`, `image`, `images`, `image_url`, `first_frame_image`, `last_frame_image`, `video_urls`, `audio_urls`, `duration`, `seconds`, `aspect_ratio`, `size`, `seed`, `audio`, `generate_audio`, `draft`, `omni_reference_task_type`, `return_last_frame`, `output_format`, `response_format`, `enhance_prompt`. Используйте черновик в течение 24 часов с создания; обе генерации оплачиваются отдельно.

## Получение статуса и результата

```bash cURL theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KZOEEXAMPLE \
  --header 'Authorization: Bearer <token>'
```

При отправке `data` — массив, при запросе статуса — объект задачи. Значения `data.status`: `pending` — очередь, `processing` — генерация, `completed` — успех, `failed` — ошибка. Адрес видео находится в массиве `data.result.videos[].url`, например `data.result.videos[0].url[0]`. Видео копируется в хранилище APIMart. Ниже показаны только основные поля успешного ответа.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZOEEXAMPLE",
    "status": "completed",
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "expires_at": 1794475442
        }
      ],
      "last_frame_url": "https://example.com/generated-last-frame.png"
    },
    "progress": 100,
    "completed": 1794389042
  }
}
```

При неудаче прочитайте причину в `data.error.message`. Списанные средства возвращаются автоматически.

| Поле | Описание |
| - | - |
| `data.progress` | Прогресс задачи, 0–100. |
| `data.result.videos[].url` | Массив адресов видео в хранилище APIMart. |
| `data.result.videos[].expires_at` | Срок действия адреса — 24 часа после завершения задачи. Скачайте видео своевременно. |
| `data.result.last_frame_url` | URL PNG последнего кадра в хранилище APIMart. Возвращается только при успехе и `return_last_frame: true` в запросе. |
| `data.error.message` | Причина неудачи, только при статусе `failed`. |
| `data.error.code` | При неудаче — строка `task_failed`. |
| `data.cost` | Стоимость задачи; для неудачных задач 0 после возврата предоплаты. |

## Правила оплаты

Посекундная оплата зависит от разрешения и наличия референсных видео. Тарифы и скидки указаны на [странице цен](https://apimart.ai/pricing). `D` — длительность выхода в секундах, используемая при расчёте.

| Случай | Оплачиваемая длительность D |
| - | - |
| Обычная генерация: `duration: 4–30` или пропуск (по умолчанию 5) | Оплачиваются запрошенные секунды, без корректировки по длине готового видео. |
| `duration: -1` / редактирование видео `edit` | Резервируется 30 секунд, затем перерасчёт по фактической длительности, округлённой до ближайшей целой секунды (0.5 вверх). |
| Финальное видео | Длительность наследуется от черновика. Если у него было `duration: -1`, основой служит фактическая длительность готового черновика; по длине финального видео повторно не корректируется. |

* Суммарная длительность референсных видео `R`: измерить каждую при отправке, сложить и округлить сумму вниз до целых секунд. Далее не корректируется.
* Без референсных видео: оплачиваемые секунды = `D`. С ними: `D + max(R, ceil(D × 2/3))`. `ceil` округляет вверх до целого. Используется тариф с референсным видео.
* Пример: запрос 8 секунд даёт `D = 8`, даже если результат длится 8.2 секунды. Автоматическая длительность 8.5 секунды даёт `D = 9`. Референсы 2.8 и 3.8 секунды сначала суммируются до 6.6, затем округляются вниз: `R = 6`.
* Черновик (`480p`) и финальное видео (`1080p`) оплачиваются отдельно. Исходная длительность референсов черновика учитывается и для финального видео; загружать их повторно не нужно.
* Отклонённые запросы не оплачиваются. При неудаче задачи средства возвращаются автоматически.

## Частые ошибки

При ошибке отправки возвращается объект `error`: пояснение в `error.message`, строковый код в `error.code`, отдельно от HTTP-статуса. Плата не взимается.

| HTTP | `error.code` | Причина и решение |
| - | - | - |
| 400 | `invalid_request_error` | Проверьте длительность, разрешение, формат, количество/сочетание материалов, неподдерживаемые поля и ограничения черновика. Также: `draft_task_id` не найден, не является черновиком, ещё не завершён или создан более 24 часов назад. Также применяется к недопустимым размерам видео, точной длительности или частоте кадров и совместной передаче `image_urls` (включая псевдонимы) и `image_with_roles`. Ошибки видео содержат измеренные значения. Также проверьте длительность аудио, тип задачи и правила редактирования, `output_format`, совпадение аудиопсевдонимов и наличие запрещённых полей. |
| 400 | `nsfw_content_detected` | Отказ модерации. Категории указаны в `error.message`. Покажите отказ и предложите изменить содержимое перед повторной отправкой. Без оплаты. |
| 400 | `input_video_probe_failed` | Референсное видео недоступно или длительность не определяется. Проверьте адрес и содержимое. |
| 402 | `payment_required` | Недостаточно средств; автоматическая длительность резервирует 30 секунд. |
| 503 | `draft_channel_unavailable` / `draft_task_unavailable` | Канал черновика недоступен или временно не удалось запросить черновик. Повторите позже или создайте новый. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.