跳转到主要内容
POST
Image-to-video: submit a generation task from a reference image
⛔ This model was retired by Google (2026-10-22): Google stopped serving Veo 3.1, and APIYI’s VEO 3.1 Official relay channel stopped with it. This page is kept for historical reference only — do not integrate against it. See Video Generation Models for alternatives and the retirement notice for details.
The interactive Playground on the right supports live debugging. Fill in your API Key under Authorization (format Bearer sk-xxx), upload a reference image, enter prompt, pick model / seconds / resolution, then send. Default group works — no dedicated group switch needed.
Scope: This page covers “generate video from a reference image” — upload one image as the visual anchor / starting frame to animate static content. If you don’t need a reference image, use the Text-to-Video endpoint (same endpoint, JSON body).
⚠️ Image-to-video constraints
  • Content-Type must be multipart/form-data (not JSON)
  • Only 1 reference image supported; field name is fixed as input_reference. Multi-image submissions only keep the first
  • Remote URLs not accepted — must be a file upload or Base64
  • Accepted formats: image/jpeg / image/png / image/webp
  • The length field is named seconds (not duration) and must be a string "4" / "6" / "8". Naming it duration is silently ignored and falls back to the default 4 sec; passing a number fails
  • At 1080p / 4k, seconds must be "8"
Google upstream Veo 3.1 supports multi-reference / first-last-frame / video extension; this Official channel does not yet expose them. For first/last frame, use the VEO 3.1 (Reverse) -fl series.

Code Samples

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

Python (requests + multipart)

cURL (multipart upload)

Node.js (native fetch + FormData)

Browser JavaScript (file input upload)

Already have a task_id? Two copy-paste cURL commands

If you already have a task_id (returned when you submitted the task, or visible in your console logs), just replace two placeholders below and run:
  • sk-your-api-key → your APIYI key
  • task_xxxxxxxxxxxxxxxx → your task ID

1. Check task status

When the JSON response shows status: "completed", you can download; if it shows in_progress, wait a few seconds and check again.

2. Download the video (saved as output.mp4)

The /content endpoint requires the Authorization header — opening the URL directly in a browser address bar returns 401. -f --retry 7 --retry-delay 4 --retry-all-errors covers the 400 right after status flips to completed (up to about 20 seconds). Without -f, curl treats the 400 as success and writes the error JSON into output.mp4; without --retry-all-errors, --retry does not retry a 400 at all (requires curl 7.71+).

Parameter Reference

Field naming difference vs JSON mode:
  • JSON mode nests under metadata.* (e.g. metadata.resolution)
  • Multipart mode flattens them as form fields (resolution / aspectRatio / seed directly)
  • The code samples above already use multipart conventions
Common mistakes:
  • Sending input_reference as a Base64 string inside a JSON body — must use multipart file field
  • Naming the field image / reference / input_image — must be exactly input_reference
  • Sending 2 images — server only keeps the first, the second is silently dropped
  • Sending a remote URL (https://cdn.../img.png) — not accepted; must be file or Base64

Response Format

The response structure is identical to Text-to-Video: Step 1 returns task_id + status: "queued", Step 2 polling returns status + coarse progress, Step 3 downloads MP4 binary from /content.
⚠️ Response field gotchas
  • Take the task ID from id (the submit response may also carry a task_id with the same value; polling responses only have id)
  • Download from GET /v1/videos/{task_id}/content as the source of truth; the completed response may carry a video_url valid for about 24 hours, not guaranteed on every task
  • progress jumps between a few fixed steps only, not linear
  • /content returns 400 occasionally right after status flips to completed; retry after 4 sec
  • Image-to-video tasks typically take 10–30% longer than equivalent text-to-video tasks (extra image encoding step)
This endpoint is an async task entry. Billing happens when the task reaches completed, charged per request by model name (independent of whether input_reference is provided; fast $0.3 / standard $1.2). POST submission, polling, and download themselves are not billed; failed tasks are also not billed.

授权

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