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

# Генерация видео Oxygen

> Руководство по генерации видео с помощью AZ8 Oxygen (oxygen-1.0): совместимый с OpenAI Videos API, поддерживающий генерацию видео по тексту, первому кадру, первому и последнему кадрам, а также референсным изображениям/видео/аудио, 320p–768p, 4–15 с, с тарификацией $0.02 за секунду.

## Обзор

Oxygen — это модель генерации видео, предоставляемая AZ8, сингапурской платформой для создания ИИ-видео (ранее Videoinu). APIYI предоставляет её как `oxygen-1.0` через API, совместимый с **OpenAI Videos** (`POST /v1/videos` для отправки, `GET /v1/videos/{id}` для запроса статуса), с клипами продолжительностью от 4 до 15 секунд в разрешениях 320p / 480p / 768p, **с тарификацией \$0.02 за секунду независимо от разрешения**.

<Note>
  **Ключевые особенности**: одна модель охватывает генерацию видео по тексту (text-to-video), по первому кадру, по первому и последнему кадрам, а также генерацию по референсам (до 9 изображений, 3 видео и 3 аудиоклипов). Результат сопровождается звуковой дорожкой. **\$0.02 за секунду**: 5-секундный клип стоит \$0.10, а 15-секундный — \$0.30, при этом средства за неудачные задачи возвращаются автоматически. Создано для масштабной и недорогой генерации видео.
</Note>

<CardGroup cols={2}>
  <Card title="Справочник по API генерации видео" icon="video" href="/ru/api-capabilities/oxygen/video-generation">
    Отправка, опрос статуса и скачивание с примерами на Python / cURL / Node.js и интерактивным Playground
  </Card>

  <Card title="Бонусы за пополнение" icon="gift" href="/ru/faq/recharge-promotions">
    Бонусы за пополнение делают фактическую цену ещё ниже
  </Card>
</CardGroup>

## Пусть AI-агент выполнит интеграцию за вас

<Note>
  Если вы разрабатываете с помощью Codex / Claude Code / Cursor, скопируйте приведенный ниже prompt в него. Агент сначала получит текстовую версию этой страницы (добавьте `.md` к любому URL документации), а затем напишет код под ваш стек. Типичные ошибки уже учтены: всегда передавайте `size`, помещайте расширенные параметры в JSON-конверт `input_reference` и задавайте длительность только через `seconds`.
</Note>

<Prompt description="Поручите агенту написания кода интеграцию или отладку генерации видео с помощью Oxygen (oxygen-1.0). Скопируйте и вставьте это в Codex, Claude Code, Cursor и т. д." icon="bot" actions={["copy"]}>
  Интегрируйте или выполните отладку генерации видео Oxygen (oxygen-1.0) в этом проекте (text-to-video / первый кадр / первый и последний кадры / референсные медиа).

  Прочитайте документацию перед написанием кода: загрузите [https://docs.apiyi.com/en/api-capabilities/oxygen/overview.md](https://docs.apiyi.com/en/api-capabilities/oxygen/overview.md) для получения текстовой версии этой страницы; параметры и примеры кода доступны по адресу [https://docs.apiyi.com/en/api-capabilities/oxygen/video-generation.md](https://docs.apiyi.com/en/api-capabilities/oxygen/video-generation.md) .

  Требования:

  1. Эндпоинты: формат OpenAI Videos. Отправляйте запрос через `POST https://api.apiyi.com/v1/videos` (JSON), запрашивайте статус через `GET https://api.apiyi.com/v1/videos/{id}`. Отправка сразу возвращает `{"id": ..., "status": "queued"}`; опрашивайте статус для получения видео.

  2. Опрос и статус: отправляйте запросы каждые 5 секунд с общим таймаутом 15 минут. Статус: `queued` / `in_progress` / `completed` / `failed`; **успешное завершение — `completed`**.

  3. Получение файла: в случае успеха скачайте **`video_url`** напрямую из ответа (заголовок авторизации не требуется). **Не полагайтесь на `/v1/videos/{id}/content`**: сразу после завершения он все еще может возвращать 400. Ссылка истекает в `expires_at` (примерно через 24 часа), поэтому сразу скопируйте ее в собственное хранилище.

  4. Длительность: обязателен параметр верхнего уровня `seconds`, целое число от 4 до 15 (строка `"5"` также принимается), и **тарификация рассчитывается на его основе**.

  5. Разрешение и ориентация: **всегда явно передавайте `size`**. Без этого шлюз подставляет `720x1280`, и вы получите вертикальное видео. `1280x720` / `720x1280` = 480p, `1792x1024` / `1024x1792` = 768p.

  6. Image-to-video только с первым кадром: укажите в `input_reference` публичный https URL изображения или data URI. Соотношение сторон результата будет соответствовать первому кадру.

  7. Расширенные параметры (первый и последний кадры, референсные медиа, 320p, 1:1): **должны быть переданы внутри JSON-строки в `input_reference`** (начиная с `{`), например `"input_reference": "{\"images\":[\"https://...first.png\"],\"last_image\":\"https://...last.png\"}"`. Допустимые ключи: `images`, `last_image`, `reference_images` (до 9), `reference_videos` (до 3), `reference_audios` (до 3), `resolution` (`320p` / `480p` / `768p`), `aspect_ratio` (`16:9` / `9:16` / `1:1`), `prompt`. **Если поместить эти поля на верхний уровень, они будут проигнорированы без вывода ошибки**. `duration` не допускается внутри конверта (ошибка 400), а первый и последний кадры нельзя комбинировать с референсными медиа.

  8. Тарификация и повторные попытки: \$0.02 за секунду при любом разрешении; средства списываются при отправке, полностью возвращаются, если задача завершается со статусом `failed`, и не взимаются, если отправка возвращает 400. При редких ошибках `upstream_error` повторите отправку через несколько минут; при ошибках 400 исправьте параметры вместо повторной отправки.

  9. Token: группа `default` или `svip` с тарификацией **Pay-as-you-go Priority**. Считывайте ключ из переменной окружения `APIYI_API_KEY`; никогда не прописывайте его в коде и не коммитьте в git.

  10. После внесения изменений запустите одну 4-секундную генерацию text-to-video с `size: "1280x720"` и покажите мне `video_url` и стоимость вызова (она должна составить \$0.08). Весь процесс занимает 1–3 минуты; в изолированной среде установите таймаут команды на 600 секунд или более, либо запустите ее в фоновом режиме.
</Prompt>

<Accordion title="От чего защищает этот prompt">
  | Требование | Ошибка, которую оно предотвращает |
  | - | - |
  | Всегда передавать `size` | Без этого шлюз по умолчанию использует вертикальный размер, поэтому запрос на горизонтальное видео вернет вертикальный результат |
  | Расширенные параметры в конверте `input_reference` | `last_image`, `reference_images` или `resolution` на верхнем уровне молча отбрасываются без ошибок: последний кадр игнорируется, референсы игнорируются, а разрешение устанавливается неверно |
  | Длительность только через `seconds` | `duration` внутри конверта отклоняется; и тарификация, и длительность ролика зависят от `seconds` |
  | Скачивать `video_url` | Вызов `/content` сразу после того, как статус стал `completed`, может вернуть 400 и выглядеть как сбой |
  | Сразу копировать файл | Ссылка становится недействительной примерно через 24 часа |
</Accordion>

## Почему Oxygen от APIYI?

<CardGroup cols={2}>
  <Card title="Оптовые цены" icon="receipt">
    \$0.02 за секунду при любом разрешении; \$0.08 за 4 секунды — отлично подходит для пакетной генерации и A/B-черновиков
  </Card>

  <Card title="Автоматический возврат средств" icon="shield-check">
    За неудачные задачи средства возвращаются в полном объеме, а отклоненные запросы бесплатны, поэтому вы платите только за полученные видео
  </Card>

  <Card title="Совместимость с OpenAI Videos" icon="plug">
    Тот же паттерн отправки и опроса, что и в `/v1/videos`, поэтому существующий код в стиле Sora потребует минимум изменений
  </Card>

  <Card title="Суммирование бонусов за пополнение" icon="gift">
    Сочетайте с [бонусами за пополнение](/ru/faq/recharge-promotions) для снижения фактической стоимости
  </Card>

  <Card title="Полная линейка видеомоделей" icon="clapperboard">
    Один и тот же ключ позволяет вызывать [Seedance 2.0 / 2.5](/ru/api-capabilities/seedance2/overview), [MiniMax-H3](/ru/api-capabilities/minimax-h3/overview), [Wan2.7](/ru/api-capabilities/wan/overview) и другие
  </Card>

  <Card title="Глобальный доступ" icon="globe">
    Подключайтесь напрямую к `api.apiyi.com` с помощью одного API-ключа без необходимости зарубежного аккаунта
  </Card>
</CardGroup>

## Ключевые возможности

<CardGroup cols={2}>
  <Card title="Четыре режима генерации" icon="layers">
    Текст, первый кадр, первый и последний кадры, а также референсные изображение / видео / аудио — все в одном эндпоинте
  </Card>

  <Card title="Три разрешения" icon="monitor">
    320p / 480p / 768p по одной цене; выбирайте между скоростью и детализацией по необходимости
  </Card>

  <Card title="Любая целая длительность от 4 до 15 с" icon="timer">
    Тарификация за запрошенные секунды, поэтому короткие клипы стоят дешевле
  </Card>

  <Card title="Встроенное аудио" icon="music">
    Итоговый MP4 содержит аудиодорожку, отдельное озвучивание не требуется
  </Card>
</CardGroup>

## Тарифы

| Позиция | Цена |
| - | - |
| Выходное видео (320p / 480p / 768p, одинаковая цена) | **\$0.02 / секунда** |
| Первый кадр, последний кадр, референсное изображение / видео / аудио | Без дополнительной платы |
| Пример: 4-секундный ролик | \$0.08 |
| Пример: 15-секундный ролик | \$0.30 |

<Note>Цены могут меняться; таблица выше приведена только для справки, а вкладка **Тарифы моделей** в верхнем меню навигации является приоритетной: [Тарифы моделей](/en/models/index).</Note>

<Info>
  **Примечания по тарификации**:

  * Тарификация осуществляется по запрошенной `seconds`, средства списываются при принятии задачи; фактический ролик длится немного дольше (около 4,5 с при запросе на 4 с) без дополнительной платы
  * Разрешение, соотношение сторон и референсные медиафайлы не влияют на цену
  * Задачи с ошибками (сбой провайдера, таймаут и т. д.) **автоматически возвращаются в полном объеме**
  * Отправка запросов, вернувших статус 400, не тарифицируется; проверка статуса и скачивание бесплатны
</Info>

## Настройка группы

`oxygen-1.0` **работает в группе `default`**, также подходит группа `svip`. Установите режим тарификации token на **Pay-as-you-go Priority**. Если при вызове возвращается «no available channel in the current group», значит, в группе token нет этой модели либо имя `model` указано с ошибкой.

| Параметр | Требование |
| - | - |
| Группа | `default` или `svip` |
| Режим тарификации | Pay-as-you-go Priority |
| Название модели | `oxygen-1.0` (суффикс `-1.0` обязателен) |

## Технические характеристики

| Параметр | Спецификация |
| - | - |
| ID модели | `oxygen-1.0` |
| Длительность | Целое число от 4 до 15 секунд (на верхнем уровне `seconds`) |
| Разрешение | 320p / 480p (по умолчанию) / 768p |
| Соотношение сторон | Горизонтальное 16:9, вертикальное 9:16, квадратное 1:1; в режиме image-to-video наследуется от первого кадра |
| Выходной размер (фактический) | 320p: 576×320; 480p: 864×480 / 480×864 / 480×480; 768p: 1344×768 / 768×1344 / 768×768 |
| Аудио | Результат содержит аудиодорожку |
| Входное изображение | Публичный https URL или data URI изображения |
| Референсные медиафайлы | Изображения до 9, видео до 3, аудио до 3 (видео и аудио только в виде https URL) |
| Результат | MP4 через `video_url` в ответе на запрос, действует около 24 часов |
| Время генерации | Обычно 1–3 минуты; от 5 минут при высокой загрузке очереди |

## Эндпоинты API

| Назначение | Метод | Путь |
| - | - | - |
| Создание задачи | `POST` | `/v1/videos` |
| Запрос задачи | `GET` | `/v1/videos/{id}` |
| Скачивание (необязательно) | `GET` | `/v1/videos/{id}/content` |

<Tip>
  Основной домен — `https://api.apiyi.com`, резервный домен — `https://b.apiyi.com`, пути те же. Для скачивания используйте `video_url` напрямую из ответа на запрос.
</Tip>

## Режимы генерации

Действуют только пять полей верхнего уровня: `model`, `prompt`, `seconds`, `size` и `input_reference`. Первый и последний кадры, референсные медиафайлы, 320p и 1:1 — это **расширенные параметры, которые помещаются в JSON-оболочку `input_reference`** (строку JSON, начинающуюся с `{`):

| Режим | Способ указания | Разрешение / соотношение сторон |
| - | - | - |
| Видео по тексту | Опустите `input_reference` | Задается через `size` |
| Видео по первому кадру | `input_reference` = URL изображения или data URI | Разрешение из `size`, соотношение сторон наследуется от первого кадра |
| Видео по первому и последнему кадрам | Оболочка `{"images":["first"],"last_image":"last"}` | То же, что и выше |
| Видео по референсным медиафайлам | Оболочка `{"reference_images":[...],"reference_videos":[...],"reference_audios":[...]}` | Задается через `size`; `aspect_ratio` можно передать в оболочке |
| 320p или 1:1 | Оболочка `{"resolution":"320p","aspect_ratio":"1:1"}` (можно сочетать с любым режимом выше) | Оболочка имеет приоритет над `size` |

Как `size` сопоставляется с разрешением:

| `size` | Разрешение | Ориентация |
| - | - | - |
| `1280x720` | 480p | Альбомная 16:9 |
| `720x1280` | 480p | Портретная 9:16 |
| `1792x1024` | 768p | Альбомная 16:9 |
| `1024x1792` | 768p | Портретная 9:16 |

Пример оболочки (первый и последний кадр):

```json theme={null}
{
  "model": "oxygen-1.0",
  "prompt": "The glass sphere slowly dissolves into a deep blue abstract wave",
  "seconds": "5",
  "size": "1280x720",
  "input_reference": "{\"images\":[\"https://your-cdn.example.com/first.png\"],\"last_image\":\"https://your-cdn.example.com/last.png\"}"
}
```

<Warning>
  * `last_image`, `reference_images`, `resolution`, `aspect_ratio` и аналогичные поля **незаметно игнорируются при размещении на верхнем уровне**: ошибка не возникает, тарификация списывается в обычном режиме, но последний кадр и референсы игнорируются, а разрешение определяется полем `size`. Всегда передавайте их в оболочке `input_reference`
  * **Поле `duration` не допускается в оболочке**; используйте `seconds` на верхнем уровне. Некорректный JSON или ошибки в написании ключей возвращают код 400 (`param: input_reference`) без списания средств
  * Первый и последний кадры **нельзя** комбинировать с референсными медиафайлами
  * Поле `input_reference` должно быть **строкой**: сначала сериализуйте оболочку (`json.dumps` в Python, `JSON.stringify` в JS). Передача объекта или массива напрямую отклоняется
</Warning>

## Рекомендации

<Steps>
  <Step title="Сначала тестируйте на 4 секундах">
    Тарификация посекундная, поэтому сначала проверьте композицию и стиль на 4 секундах, прежде чем запускать рендеринг финальных версий на 10–15 секунд
  </Step>

  <Step title="Всегда указывайте size">
    Альбомная ориентация — `1280x720`, портретная — `720x1280`; для более высокой детализации используйте `1792x1024` / `1024x1792` (768p)
  </Step>

  <Step title="Используйте первый и последний кадры с близким соотношением сторон">
    Итоговое видео сохраняет соотношение сторон первого кадра; если последний кадр сильно отличается по пропорциям, он будет обрезан во время перехода
  </Step>

  <Step title="Размещайте медиафайлы в надежном публичном хранилище">
    Используйте прямые ссылки с собственных OSS / CDN, чтобы избежать сбоев при скачивании из-за защиты от хотлинкинга или истекшего срока действия подписей
  </Step>

  <Step title="Опрашивайте каждые 5 секунд с таймаутом 15 минут">
    Большинство видео генерируются за 1–3 минуты; в периоды пиковой нагрузки это может занять больше времени
  </Step>

  <Step title="Сразу сохраняйте video_url в собственное хранилище">
    Срок действия ссылки истекает примерно через 24 часа; скачайте файл и раздавайте его из своего хранилища
  </Step>
</Steps>

## Коды ошибок и повторные попытки

| Этап | Симптом | Причина | Решение |
| - | - | - | - |
| Отправка | 400, `invalid_params`, `param: input.duration` | `seconds` вне диапазона 4–15 | Измените длительность; средства не списаны |
| Отправка | 400, `invalid_params`, `param: input_reference` | Некорректный JSON envelope, неизвестный ключ или `duration` в envelope | Исправьте envelope согласно сообщению; средства не списаны |
| Отправка | 400, `cannot unmarshal array ... input_reference` | `input_reference` передан как массив или объект вместо строки | Сериализуйте его с помощью `json.dumps` / `JSON.stringify` |
| Отправка | 500, сбой загрузки референсного файла | URL изображения в `input_reference` недоступен | Используйте общедоступный URL по протоколу https |
| Отправка | 503, нет доступного канала | Группа token не включает данную модель или в названии модели допущена ошибка | Проверьте группу и `oxygen-1.0` |
| Выполнение | `failed`, `upstream_error` | Периодический сбой на стороне провайдера | Отправьте запрос повторно через несколько минут (средства уже возвращены) |
| Выполнение | `failed`, `upstream_timeout` | Слишком долгое нахождение в очереди на стороне upstream, превышен лимит времени | Отправьте запрос повторно позже (средства уже возвращены) |

<Info>
  Подробная информация об ошибке передается в виде строки JSON внутри поля `message` ответа, например `{"message":"{\"error\":{\"code\":\"invalid_params\",...}}","type":"task_error"}`, поэтому выполните парсинг повторно.
</Info>

## Часто задаваемые вопросы

<AccordionGroup>
  <Accordion title="Почему моё горизонтальное видео получилось вертикальным?">
    Параметр `size` не был передан. Без него шлюз по умолчанию использует `720x1280` (вертикальный формат). Для горизонтального видео явно укажите `1280x720` или `1792x1024`.
  </Accordion>

  <Accordion title="Почему last_image / reference_images не действуют?">
    Они были указаны на верхнем уровне запроса. Там действуют только `model`, `prompt`, `seconds`, `size` и `input_reference`; всё остальное отбрасывается без предупреждения. Поместите их в JSON-оболочку `input_reference`, см. раздел «Режимы генерации» выше.
  </Accordion>

  <Accordion title="Как получить 320p? Передача resolution ничего не даёт.">
    Параметр `resolution` на верхнем уровне отбрасывается. Поместите его в оболочку: `"input_reference": "{\"resolution\":\"320p\"}"`. Все три разрешения стоят одинаково.
  </Accordion>

  <Accordion title="Отличается ли стоимость для разных разрешений?">
    Нет, для всех действует тариф \$0.02 за секунду. 320p рендерится быстрее и даёт файлы меньшего размера; 768p обеспечивает более высокую чёткость.
  </Accordion>

  <Accordion title="Статус указывает completed, но /content возвращает 400?">
    Сразу после того как статус становится `completed`, для `/v1/videos/{id}/content` может потребоваться ещё несколько секунд. Вместо этого используйте `video_url` из ответа на запрос.
  </Accordion>

  <Accordion title="Сколько действует ссылка на видео?">
    Около 24 часов (см. `expires_at` в ответе на запрос). Своевременно скачайте и сохраните файл.
  </Accordion>

  <Accordion title="Списываются ли средства за неудачные задачи?">
    Нет. За задачу со статусом `failed` средства автоматически возвращаются в полном объёме, а за отправку запросов, возвращающих 400, плата не взимается.
  </Accordion>

  <Accordion title="Что делать при периодической ошибке upstream_error?">
    Это единичный сбой на стороне провайдера, средства за него уже возвращены. Повторная отправка через несколько минут обычно решает проблему.
  </Accordion>

  <Accordion title="Почему ролик немного длиннее, чем указано в секундах?">
    Итоговое видео длится чуть дольше (около 4.5 с для 4 с, 5.2 с для 5 с). Тарификация рассчитывается по запрошенному значению `seconds`, поэтому дополнительная плата не взимается.
  </Accordion>

  <Accordion title="Может ли первый кадр быть в base64?">
    Да. Параметры `input_reference` и `images` в оболочке принимают data URI изображений (например, `data:image/jpeg;base64,...`). Опорные видео и аудио принимают только https URL.
  </Accordion>

  <Accordion title="Можно ли задать соотношение сторон для генерации видео по изображению?">
    Нет. В режиме генерации видео по изображению сохраняется соотношение сторон первого кадра, а `aspect_ratio` игнорируется. Вы по-прежнему можете выбрать разрешение с помощью `size` или `resolution` в оболочке.
  </Accordion>
</AccordionGroup>

## Связанная документация

* [Справочник API генерации видео Oxygen](/ru/api-capabilities/oxygen/video-generation)
* [Генерация видео MiniMax-H3](/ru/api-capabilities/minimax-h3/overview)
* [Генерация видео Seedance 2.0 / 2.5](/ru/api-capabilities/seedance2/overview)
* [Генерация видео Wan2.7](/ru/api-capabilities/wan/overview)
* [Бонусы за пополнение](/ru/faq/recharge-promotions)


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