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

Python (requests + multipart)

cURL (multipart-загрузка)

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

JavaScript в браузере (загрузка через input file)

У вас уже есть 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. --retry 3 покрывает редкие 400 сразу после того, как status переключается на completed (задержка синхронизации CDN).

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

Разница в именовании полей по сравнению с 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

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

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

Тело

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