Перейти к основному содержанию
POST
Text-to-video: submit a generation task from text prompt
Интерактивный Playground справа поддерживает отладку в реальном времени. Укажите свой ключ API в Authorization (формат Bearer sk-xxx), введите prompt, выберите модель / секунды / metadata.resolution, затем отправьте. Default группа работает — отдельный переключатель группы не нужен.
Область применения: Эта страница охватывает «генерацию видео только по тексту» — без тела input_reference, application/json. Для генерации по референсному изображению используйте эндпоинт Image-to-Video (тот же эндпоинт + загрузка input_reference).
⚠️ Три наиболее распространенные ошибки
  1. Поле длины называется seconds (а не duration) и должно быть строкой "4" / "6" / "8". Если назвать его duration, это будет молча проигнорировано → length откатится к значению по умолчанию 4 сек. (ловушка «отправили 8s, получили 4s»); передача числа завершается parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string
  2. Не передавайте generateAudio — upstream возвращает INVALID_ARGUMENT. Описывайте аудиосценарий (ambient, dialogue, BGM) в prompt вместо этого
  3. При 1080p / 4k seconds должно быть "8" — "4" / "6" будут отклонены upstream
Трехшаговый асинхронный процесс — на этой странице описан только шаг 1 (отправка)
  • Шаг 1 (эта страница): POST /v1/videos → возвращает task_id + status: "queued"
  • Шаг 2: GET /v1/videos/{task_id} опрашивайте до status: "completed"
  • Шаг 3: GET /v1/videos/{task_id}/content для скачивания MP4
POST submit сам по себе выполняется менее чем за секунду и не ждет генерацию. Полный процесс показан в примере Python ниже.

Примеры кода

Python (OpenAI SDK · low-level client.post)

Python (requests)

cURL

Node.js (native fetch)

Browser JavaScript

Уже есть task_id? Две готовые cURL-команды

Если у вас уже есть task_id (полученный при отправке задачи или отображаемый в логах вашей консоли), просто замените два плейсхолдера ниже и выполните:
  • sk-your-api-key → ваш ключ APIYI
  • task_xxxxxxxxxxxxxxxx → ваш ID задачи

1. Проверьте статус задачи

Когда в JSON-ответе отображается status: "completed", вы можете скачать результат; если отображается in_progress, подождите несколько секунд и проверьте снова.

2. Скачайте видео (сохраняется как output.mp4)

Для эндпоинта /content требуется заголовок Authorization — прямое открытие URL в адресной строке браузера вернет 401. -f --retry 7 --retry-delay 4 --retry-all-errors обрабатывает ошибку 400 сразу после переключения status на completed (примерно до 20 секунд). Без -f curl посчитает 400 успешным ответом и запишет JSON с ошибкой в output.mp4; без --retry-all-errors параметр --retry вообще не будет повторять попытку при 400 (требуется curl 7.71+).

Справка по параметрам

Не передавайте поле generateAudio! Veo 3.1 изначально поддерживает аудио; передача этого параметра возвращает INVALID_ARGUMENT. Чтобы управлять аудио, впишите намерение в prompt: "waves, distant seabirds, low wind sounds".
Приоритет параметров:
  • Длительность: metadata.durationSeconds > seconds > 8 (отправляйте seconds; duration не распознается)
  • Разрешение: metadata.resolution > size > 720p
  • Соотношение сторон: явное metadata.aspectRatio > определяемое по размеру > 16:9

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

Шаг 1 — сразу после отправки

Шаг 2 — ответ при опросе (в процессе)

Шаг 2 — ответ при опросе (завершено)

⚠️ Подводные камни полей ответа
  • Берите ID задачи из id: ответ на отправку также может содержать task_id (то же значение), но ответы при опросе содержат только id; безопасный шаблон — resp.get("task_id") or resp["id"] (в примерах выше это уже учтено)
  • Используйте скачивание через /content как надежный источник данных: GET /v1/videos/{task_id}/content возвращает бинарный поток MP4 (требуется заголовок авторизации) и работает для каждой задачи. Завершенный ответ может также содержать video_url (прямая ссылка, без авторизации) и expires_at (примерно через 24 часа); это не гарантируется для каждой задачи и подходит только для временного предварительного просмотра. Фронтенд не может обращаться к /content напрямую — скачивайте на стороне сервера и повторно размещайте в собственном OSS / CDN
  • progress имеет низкую детализацию — переключается только между несколькими фиксированными шагами, не используйте его для индикаторов выполнения в процентах
  • status: "failed" обычно содержит error.message с указанием причины (проверка контента, ошибки в параметрах или невозможность получить сгенерированный файл). Неудачные задачи не тарифицируются, а списанные средства возвращаются автоматически; скорректируйте prompt и повторите попытку
  • /content иногда возвращает 400 сразу после того, как status меняется на completed; повторите попытку через 4 секунды (это уже заложено во всех примерах кода выше)
Этот эндпоинт представляет собой точку входа для асинхронных задач. Тарификация происходит, когда задача достигает completed, с оплатой за запрос в зависимости от названия модели (быстрая $0.3 / стандартная $1.2, см. Тарифы). Сами отправка POST-запроса, опрос и скачивание не тарифицируются; неудачные задачи также не тарифицируются.

Авторизации

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

API Key from APIYI console (Default group + Pay-per-request or Pay-as-you-go Priority Token; pure Pay-as-you-go not supported)

Тело

application/json
model
enum<string>
по умолчанию:veo-3.1-fast-generate-preview
обязательно

Model ID (per-request billing, duration / resolution do not affect price):

  • veo-3.1-fast-generate-preview — $0.3/request, top pick for iteration / batch generation
  • veo-3.1-generate-preview — $1.2/request, for final delivery / 4K scenarios
Доступные опции:
veo-3.1-fast-generate-preview,
veo-3.1-generate-preview
prompt
string
обязательно

Video generation prompt; describe in detail: scene + subject + action + camera + lighting + style.

Audio intent also goes in the prompt (e.g. "waves, distant seabirds, low wind sounds"). Do not pass generateAudio — upstream rejects with INVALID_ARGUMENT.

Пример:

"A coastal lighthouse at dusk, slow push-in, waves lapping the rocks, distant seabirds, cinematic lighting, steady camera"

seconds
enum<string>
по умолчанию:8

Video length. The field name is seconds (not duration), a string enum (not number):

  • "4" — 4 sec, 720p only
  • "6" — 6 sec, 720p only
  • "8" — 8 sec (default), required at 1080p / 4k

Sending duration instead is silently ignored → length falls back to the default 4 sec (720p returns no error but only outputs 4 sec; 1080p/4k errors with ... but got 4). Passing a number (8) returns parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string.

Доступные опции:
4,
6,
8
size
enum<string>
по умолчанию:1280x720

Output pixel dimensions; lower precedence than metadata.resolution:

  • 1280x720 / 720x1280 — 720p (default)
  • 1920x1080 / 1080x1920 — 1080p (seconds must be "8")
  • 3840x2160 / 2160x3840 — 4k (seconds must be "8", 4–6× slower render)
Доступные опции:
1280x720,
720x1280,
1920x1080,
1080x1920,
3840x2160,
2160x3840
metadata
object

Wrapper for fine-grained generation parameters. Higher precedence than the top-level size etc.:

  • Duration resolution order: metadata.durationSeconds > seconds > 8 (send seconds; duration is not recognized)
  • Resolution resolution order: metadata.resolution > size > 720p

Ответ

Task submitted; returns task_id and queued status

id
string

Task ID (matches task_id; downstream should standardize on task_id)

Пример:

"task_xxxxxxxxxxxxxxxx"

task_id
string

Task ID for subsequent polling and download

Пример:

"task_xxxxxxxxxxxxxxxx"

object
string

Object type, fixed to video

Пример:

"video"

model
string

Model ID used for this task

Пример:

"veo-3.1-fast-generate-preview"

status
enum<string>

Task status:

  • queued — submitted, awaiting processing
  • in_progress — generating
  • completed — done, downloadable (/v1/videos/{task_id}/content)
  • failed — failed (not billed), retry possible
Доступные опции:
queued,
in_progress,
completed,
failed
Пример:

"queued"

progress
integer

Generation progress (coarse-grained, jumps only between 0 / 50 / 100, do not use for percentage bars)

Пример:

0

created_at
integer

Task creation Unix timestamp (seconds)

Пример:

1775025000

completed_at
integer

Task completion Unix timestamp (seconds); only present for completed status

Пример:

1775025090