Skip to main content
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 · низкоуровневый client.post)

Python (requests)

cURL

Node.js (встроенный fetch)

JavaScript в браузере

Уже есть task_id? Два cURL-команды для копирования и вставки

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

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

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

2. Скачать video (сохранится как output.mp4)

Эндпоинт /content требует заголовок Authorization — при прямом открытии URL в адресной строке браузера возвращается 401. --retry 3 описывает редкий 400 сразу после того, как status переключается на completed (задержка синхронизации CDN).

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

Не передавайте поле 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 и task_id возвращаются со значением одинаково; downstream должен стандартизировать на task_id (совместимо с существующим обратным каналом)
  • CDN / публичный URL не возвращается — в ответе нет video_url / data.url; видео можно получить только как MP4 binary stream через GET /v1/videos/{task_id}/content (требуется auth header). Frontend не может вызывать этот эндпоинт напрямую — загружайте на стороне сервера и размещайте у себя в OSS / CDN
  • progress является грубым показателем — перескакивает только между 0 / 50 / 100, не используйте его для индикаторов прогресса
  • status: "failed" может не содержать подробное поле error; обычно это связано с проверкой контента или ошибками параметров. Просто повторите попытку или скорректируйте prompt
  • /content иногда возвращает 400 сразу после того, как status переключается на completed; повторите попытку через 4 секунды (во всех примерах кода выше это уже учтено)
Этот эндпоинт является точкой входа для асинхронной задачи. Тарификация происходит, когда задача достигает completed, и взимается за каждый запрос по имени модели (fast $0.3 / standard $1.2, см. Pricing). Само 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