跳转到主要内容
POST
Text-to-video: submit a generation task from text prompt
⛔ 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), enter prompt, pick model / seconds / metadata.resolution, then send. Default group works — no dedicated group switch needed.
Scope: This page covers “generate video from text only” — no input_reference, application/json body. To generate from a reference image, use the Image-to-Video endpoint (same endpoint + input_reference upload).
⚠️ Three most common pitfalls
  1. The length field is named seconds (not duration) and must be a string "4" / "6" / "8". Naming it duration is silently ignored → length falls back to the default 4 sec (the “sent 8s, got 4s” trap); passing a number fails with parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string
  2. Do not pass generateAudio — upstream returns INVALID_ARGUMENT. Encode audio intent (ambient, dialogue, BGM) in the prompt instead
  3. At 1080p / 4k, seconds must be "8" — "4" / "6" will be rejected upstream
Three-step async flow — this page covers only Step 1 (submit)
  • Step 1 (this page): POST /v1/videos → returns task_id + status: "queued"
  • Step 2: GET /v1/videos/{task_id} poll until status: "completed"
  • Step 3: GET /v1/videos/{task_id}/content to download MP4
POST submit itself is sub-second and does not wait for generation. Full flow shown in the Python sample below.

Code Samples

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

Python (requests)

cURL

Node.js (native fetch)

Browser JavaScript

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

Do not pass the generateAudio field! Veo 3.1 is natively audio-enabled; passing this parameter returns INVALID_ARGUMENT. To control audio, write the intent into your prompt: "waves, distant seabirds, low wind sounds".
Parameter precedence:
  • Duration: metadata.durationSeconds > seconds > 8 (send seconds; duration is not recognized)
  • Resolution: metadata.resolution > size > 720p
  • Aspect: explicit metadata.aspectRatio > inferred from size > 16:9

Response Format

Step 1 - immediately after submission

Step 2 - polling response (in progress)

Step 2 - polling response (completed)

⚠️ Response field gotchas
  • Take the task ID from id: the submit response may also carry task_id (same value), but polling responses only have id; the safe pattern is resp.get("task_id") or resp["id"] (the samples above already do this)
  • Download via /content as the source of truth: GET /v1/videos/{task_id}/content returns the MP4 binary stream (requires auth header) and works for every task. The completed response may also carry video_url (a direct link, no auth) and expires_at (about 24 hours later); it is not guaranteed on every task and is only suitable for temporary previews. Frontends cannot hit /content directly — download server-side and re-host on your own OSS / CDN
  • progress is coarse-grained — jumps between a few fixed steps only, do not use for percentage bars
  • status: "failed" usually carries error.message with the reason (content review, parameter errors, or the generated file could not be retrieved). Failed tasks are not billed and any charge is refunded automatically; adjust the prompt and retry
  • /content returns 400 occasionally right after status flips to completed; retry after 4 seconds (all code samples above have this baked in)
This endpoint is an async task entry. Billing happens when the task reaches completed, charged per request by model name (fast $0.3 / standard $1.2, see Pricing). 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)

请求体

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