Перейти к основному содержанию
POST
Интерактивный Playground справа позволяет тестировать вызовы в реальном времени. Введите ваш API-ключ в поле Authorization (формат Bearer sk-xxx), заполните prompt, seconds и size и отправьте запрос. В ответе возвращается id задачи; получите видео с помощью эндпоинта запроса ниже.
Один эндпоинт, четыре режима: только prompt = генерация видео из текста; одно изображение в input_reference = видео по первому кадру; JSON-оболочка в input_reference = видео по первому и последнему кадру или видео на основе референсных медиа, при этом оболочка также позволяет выбрать 768p, 1:1 или уровень качества. Полную информацию см. в Oxygen Overview.
⚠️ Четыре самые распространенные ошибки
  1. Всегда передавайте size: без этого шлюз по умолчанию использует 720x1280, и вы получите результат в портретной ориентации
  2. Помещайте расширенные параметры в оболочку input_reference: на верхнем уровне действуют только model, prompt, seconds, size и input_reference; параметры last_image, reference_images, resolution и aspect_ratio, размещенные там, молча отбрасываются без вывода ошибки
  3. input_reference должен быть строкой: сначала сериализуйте оболочку с помощью json.dumps / JSON.stringify; передача объекта или массива отклоняется
  4. Задавайте длительность только с помощью seconds на верхнем уровне (4–15); передача duration внутри оболочки возвращает 400

Примеры кода

Python (requests · отправка + опрос + скачивание)

Python (видео по первому кадру · тело запроса)

Python (первый и последний кадры / референсные медиа · JSON-оболочка)

cURL

Первый и последний кадры (обратите внимание, что значение input_reference представляет собой экранированную JSON-строку):

Node.js (нативный fetch)

Есть id? Один запрос cURL для получения результата

Когда status имеет значение completed, video_url является адресом MP4 и может быть скачан напрямую:

Справочник параметров

Поля верхнего уровня (действуют только эти пять)

Ключи конверта input_reference

Конверт не может содержать duration (используйте seconds верхнего уровня) или любой ключ, не указанный в таблице, а первый/последний кадры (images / last_image) нельзя комбинировать с reference_*. Любое из этих нарушений возвращает 400 (param: input_reference) без списания средств.

Разрешение и размер на выходе (фактические)

В режиме image-to-video сохраняется соотношение сторон первого кадра; например, квадратный первый кадр дает 480×480 при 480p.

Формат ответа

Создание задачи

Запрос задачи (успех)

Запрос задачи (ошибка)

Ошибка отправки (400)

⚠️ Примечания к ответу
  • Статус меняется по цепочке: queued → in_progress → completed / failed
  • Видео находится по адресу video_url и доступно для скачивания без заголовка авторизации; срок действия ссылки истекает в expires_at (примерно через 24 часа), поэтому сохраните его своевременно
  • Сразу после completed для /v1/videos/{id}/content может потребоваться ещё несколько секунд (сначала возвращается 400); рекомендуем использовать video_url
  • usage.unit_price_usd — это ориентировочная цена для каждого разрешения; фактическая тарификация рассчитывается по вашему счету: фиксированные $0.02 за секунду
  • При ошибках отправки подробная информация передается в виде строки JSON внутри message, и её необходимо распарсить повторно
Тарификация: списание seconds × \$0.02 происходит в момент принятия задачи; разрешение и референсные медиафайлы не влияют на стоимость, а за неудавшиеся задачи средства автоматически возвращаются в полном объеме. За отправку запросов, возвращающих ошибку 400, плата не взимается, а запросы статуса и скачивание бесплатны. См. раздел Тарифы в обзоре.

Авторизации

Authorization
string
header
обязательно

API key from the APIYI console

Тело

application/json
model
enum<string>
по умолчанию:oxygen-1.0
обязательно

Always oxygen-1.0

Доступные опции:
oxygen-1.0
prompt
string
обязательно

Video description

Пример:

"A paper boat drifting on a calm pond, soft morning light"

seconds
enum<string>
по умолчанию:4
обязательно

Output length in seconds, integer 4–15, as a string or number. Used for billing; the clip usually runs slightly longer

Доступные опции:
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
size
enum<string>
по умолчанию:1280x720

Sets the resolution and orientation. Pass it every time; it defaults to 720x1280 (portrait) when omitted. 1280x720 = 480p landscape, 720x1280 = 480p portrait, 1792x1024 = 768p landscape, 1024x1792 = 768p portrait. For 1:1, use aspect_ratio in the input_reference envelope.

Доступные опции:
1280x720,
720x1280,
1792x1024,
1024x1792
input_reference
string

Two forms:

  • Image URL or data URI → first-frame video; aspect ratio follows the first frame
  • JSON string starting with { (envelope) → allowed keys: images (first frame, max 1), last_image (last frame), reference_images (up to 9), reference_videos (up to 3, https only), reference_audios (up to 3, https only), resolution (480p / 768p, wins over size), aspect_ratio (16:9 / 9:16 / 1:1, ignored for image-to-video), quality (high default / normal), prompt_enhance (refine default / format / none), prompt

Must be a string, so serialize the envelope first. No duration and no unknown keys in the envelope; first/last frames cannot be mixed with reference media.

Пример:

"https://your-cdn.example.com/first.png"

Ответ

Task accepted

id
string

Task id, used with GET /v1/videos/{id}

object
enum<string>
Доступные опции:
video
model
string
status
enum<string>
Доступные опции:
queued,
in_progress,
completed,
failed
progress
integer

0–100

seconds
string
size
string
created_at
integer
completed_at
integer
expires_at
integer

When video_url expires (Unix seconds), about 24 hours after completion

video_url
string

Output MP4 URL, downloadable without an auth header; store it promptly

usage
object

Reference billing info; actual billing is a flat $0.02 per second, see your bill

error
object