Перейти к основному содержанию
POST
Image-to-video: submit a generation task from a reference image
Интерактивная песочница справа поддерживает отладку в реальном времени. Укажите свой API-ключ в поле Authorization (формат Bearer sk-xxx), загрузите опорное изображение, введите prompt, выберите модель / секунды / разрешение, затем отправьте. Default группа работает — отдельный переключатель группы не нужен.
Область применения: Эта страница охватывает «генерацию видео по опорному изображению» — загрузите одно изображение как визуальную опору / стартовый кадр, чтобы анимировать статичный контент. Если вам не нужно опорное изображение, используйте эндпоинт генерации видео по тексту (тот же эндпоинт, JSON-тело).
⚠️ Ограничения image-to-video
  • Content-Type должен быть multipart/form-data (не JSON)
  • Поддерживается только 1 reference image; имя поля жестко задано как input_reference. При отправке нескольких изображений сохраняется только первое
  • Удаленные URLs не принимаются — нужна либо загрузка файла, либо Base64
  • Поддерживаемые форматы: image/jpeg / image/png / image/webp
  • Поле длины называется seconds (а не duration) и должно быть строкой "4" / "6" / "8". Если назвать его duration, это будет молча проигнорировано и вернется значение по умолчанию — 4 сек.; передача числа завершится ошибкой
  • При 1080p / 4k seconds должно быть "8"
Google upstream Veo 3.1 поддерживает multi-reference / first-last-frame / video extension; этот официальный канал пока не предоставляет их. Для first/last frame используйте VEO 3.1 (Reverse) -fl серии.

Примеры кода

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

Python (requests + multipart)

cURL (multipart upload)

Node.js (native fetch + FormData)

Browser JavaScript (file input upload)

Уже есть 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+).

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

Разница в именовании полей по сравнению с JSON mode:
  • В JSON mode они вложены под metadata.* (например, metadata.resolution)
  • Multipart mode делает их плоскими form fields (resolution / aspectRatio / seed напрямую)
  • Приведенные выше примеры кода уже используют соглашения multipart
Распространенные ошибки:
  • Отправка input_reference как строки Base64 внутри JSON body — нужно использовать multipart file field
  • Название поля image / reference / input_image — должно быть точно input_reference
  • Отправка 2 изображений — сервер сохраняет только первое, второе незаметно отбрасывается
  • Отправка удаленного URL (https://cdn.../img.png) — не принимается; должен быть файл или Base64

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

Структура ответа идентична Генерации видео по тексту: Шаг 1 возвращает task_id + status: "queued", опрос на Шаге 2 возвращает status + приблизительный progress, Шаг 3 скачивает бинарный файл MP4 из /content.
⚠️ Особенности полей ответа
  • Берите ID задачи из id (ответ на отправку может также содержать task_id с тем же значением; ответы при опросе содержат только id)
  • Скачивайте из GET /v1/videos/{task_id}/content как из первоисточника; завершенный ответ может содержать video_url, действительный около 24 часов, но это не гарантируется для каждой задачи
  • progress изменяется только между несколькими фиксированными шагами, нелинейно
  • /content иногда возвращает 400 сразу после того, как status переходит в completed; повторите попытку через 4 секунды
  • Задачи генерации видео по изображению обычно занимают на 10–30% больше времени, чем аналогичные задачи генерации видео по тексту (дополнительный шаг кодирования изображения)
Этот эндпоинт является точкой входа для асинхронных задач. Тарификация происходит, когда задача достигает completed; списание выполняется за запрос в зависимости от названия модели (независимо от того, указан ли input_reference; fast $0.3 / standard $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)

Тело

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

Model ID (per-request billing):

  • veo-3.1-fast-generate-preview — $0.3/request
  • veo-3.1-generate-preview — $1.2/request
Доступные опции:
veo-3.1-fast-generate-preview,
veo-3.1-generate-preview
prompt
string
обязательно

Video generation prompt. Focus on how the scene should animate: camera motion, object action, lighting, audio atmosphere. Do not pass generateAudio — audio intent goes in the prompt.

Пример:

"Camera slowly rises from the base of the lighthouse to the top, dusk lighting, waves lapping the rocks"

input_reference
file
обязательно

Reference image file. Field name is fixed as input_reference, only 1 image supported.

Accepted formats: image/jpeg / image/png / image/webp. Remote URLs not accepted — must be a file upload or Base64.

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

Video length. The field name is seconds (not duration), a string enum: "4" / "6" / "8". Sending duration is silently ignored and falls back to the default 4 sec. Must be "8" at 1080p / 4k.

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

Output pixel dimensions; lower precedence than resolution

Доступные опции:
1280x720,
720x1280,
1920x1080,
1080x1920,
3840x2160,
2160x3840
resolution
enum<string>
по умолчанию:720p

Resolution tier (multipart mode flattens this as a top-level form field; higher precedence than size)

Доступные опции:
720p,
1080p,
4k
aspectRatio
enum<string>
по умолчанию:16:9

Aspect ratio: 16:9 landscape (default) or 9:16 portrait

Доступные опции:
16:9,
9:16
seed
string

Random seed (multipart form field; string-encoded number is fine). Fixed seed clusters outputs in style but does not byte-reproduce.

Пример:

"20260521"

negativePrompt
string

Negative prompt; recommended "blurry, watermark, distorted, low quality"

Пример:

"blurry, watermark, distorted, low quality"

Ответ

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)

Пример:

0

created_at
integer

Task creation Unix timestamp (seconds)

Пример:

1775025000

completed_at
integer

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

Пример:

1775025090