⛔ 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
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
Do not pass generateAudio — upstream returns INVALID_ARGUMENT. Encode audio intent (ambient, dialogue, BGM) in the prompt instead
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 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)
{/* OpenAI SDK has no videos.create method; /v1/videos is a custom path, use low-level client.post() */}from openai import OpenAIimport timeclient = OpenAI( api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")# Step 1: submitresp = client.post( "/videos", body={ "model": "veo-3.1-fast-generate-preview", "prompt": "A coastal lighthouse at dusk, slow push-in, waves lapping the rocks, distant seabirds, cinematic lighting, steady camera", "seconds": "8", # string, not number "size": "1280x720", "metadata": { "resolution": "720p", "aspectRatio": "16:9", "seed": 20260521, "negativePrompt": "blurry, watermark, distorted, low quality" } }, cast_to=dict)task_id = resp.get("task_id") or resp["id"]print(f"Task ID: {task_id}, status: {resp['status']}")# Step 2: poll (up to 3 minutes for 720p/1080p)deadline = time.time() + 180while time.time() < deadline: s = client.get(f"/videos/{task_id}", cast_to=dict) print(f"Status: {s['status']}, progress: {s.get('progress', 0)}%") if s["status"] == "completed": break if s["status"] == "failed": raise RuntimeError(f"Generation failed: {s}") time.sleep(8)# Step 3: download (retry to handle CDN sync delay right after completed)import urllib.request, urllib.errortime.sleep(4)for i in range(8): try: req = urllib.request.Request( f"https://api.apiyi.com/v1/videos/{task_id}/content", headers={"Authorization": "Bearer sk-your-api-key"} ) with urllib.request.urlopen(req, timeout=180) as r, open("output.mp4", "wb") as f: while chunk := r.read(1 << 16): f.write(chunk) break except urllib.error.HTTPError as e: # 400 = status just flipped to completed (window up to ~20 s): keep waiting; 502 etc.: one more try at most if i == 7 or (e.code != 400 and i >= 1): raise time.sleep(4)print("Saved: output.mp4")
Python (requests)
import requestsimport timeAPI_KEY = "sk-your-api-key"BASE_URL = "https://api.apiyi.com/v1"HEADERS = {"Authorization": f"Bearer {API_KEY}"}# Step 1: submit (JSON body)resp = requests.post( f"{BASE_URL}/videos", headers={**HEADERS, "Content-Type": "application/json"}, json={ "model": "veo-3.1-fast-generate-preview", "prompt": "A coastal lighthouse at dusk, slow push-in, steady camera, ocean ambience and distant seabirds", "seconds": "8", # must be a string "size": "1280x720", "metadata": { "resolution": "720p", "aspectRatio": "16:9" } }, timeout=30 # POST is just an enqueue; 30 sec is enough).json()task_id = resp.get("task_id") or resp["id"]print(f"Task ID: {task_id}, status: {resp['status']}")# Step 2: poll (3 min for 720p/1080p, 10 min for 4K)deadline = time.time() + 180while time.time() < deadline: s = requests.get(f"{BASE_URL}/videos/{task_id}", headers=HEADERS).json() print(f"Status: {s['status']}, progress: {s.get('progress', 0)}%") if s["status"] == "completed": break if s["status"] == "failed": raise RuntimeError(f"Generation failed: {s}") time.sleep(8)# Step 3: download with retrytime.sleep(4)for i in range(8): try: with requests.get( f"{BASE_URL}/videos/{task_id}/content", headers=HEADERS, stream=True, timeout=180 ) as r: r.raise_for_status() with open("output.mp4", "wb") as f: for chunk in r.iter_content(chunk_size=8192): f.write(chunk) break except requests.HTTPError as e: # 400 = status just flipped to completed (window up to ~20 s): keep waiting; 502 etc.: one more try at most if i == 7 or (e.response.status_code != 400 and i >= 1): raise time.sleep(4)print("Saved: output.mp4")
cURL
{/* Just want to check/download with an existing task_id? See the "Already have a task_id?" section below */}{/* Step 1: submit (the length field is seconds, the string "8", not number 8, and not duration) */}RESP=$(curl -sS -X POST "https://api.apiyi.com/v1/videos" \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast-generate-preview", "prompt": "A coastal lighthouse at dusk, slow push-in, ocean ambience, cinematic lighting", "seconds": "8", "size": "1280x720", "metadata": {"resolution": "720p", "aspectRatio": "16:9"} }')TASK_ID=$(echo "$RESP" | python3 -c 'import sys,json;print((lambda d: d.get("task_id") or d["id"])(json.load(sys.stdin)))')echo "task_id=$TASK_ID"{/* Step 2: poll every 8 sec */}while :; do S=$(curl -sS -H "Authorization: Bearer sk-your-api-key" "https://api.apiyi.com/v1/videos/$TASK_ID") ST=$(echo "$S" | python3 -c 'import sys,json;print(json.load(sys.stdin)["status"])') echo "status=$ST" [ "$ST" = "completed" ] && break [ "$ST" = "failed" ] && { echo "$S"; exit 1; } sleep 8done{/* Step 3: download (--retry covers occasional 400 right after status=completed) */}sleep 4curl -fsSL --retry 7 --retry-delay 4 --retry-all-errors \ -H "Authorization: Bearer sk-your-api-key" \ "https://api.apiyi.com/v1/videos/$TASK_ID/content" \ -o output.mp4ls -lh output.mp4
Node.js (native fetch)
import fs from 'node:fs';const API_KEY = 'sk-your-api-key';const BASE_URL = 'https://api.apiyi.com/v1';// Step 1: submitconst submitResp = await fetch(`${BASE_URL}/videos`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${API_KEY}` }, body: JSON.stringify({ model: 'veo-3.1-fast-generate-preview', prompt: 'A golden retriever running on a sandy beach, slow motion, golden hour, cinematic quality', seconds: '8', // must be string size: '1280x720', metadata: { resolution: '720p', aspectRatio: '16:9' } })});const submitData = await submitResp.json();const task_id = submitData.task_id || submitData.id;console.log(`Task ID: ${task_id}`);// Step 2: polllet status = 'queued';while (status !== 'completed' && status !== 'failed') { await new Promise(r => setTimeout(r, 8000)); const s = await (await fetch(`${BASE_URL}/videos/${task_id}`, { headers: { 'Authorization': `Bearer ${API_KEY}` } })).json(); status = s.status; console.log(`Status: ${status}, progress: ${s.progress ?? 0}%`);}if (status === 'failed') throw new Error('Generation failed');// Step 3: download (retry 400 every 4 s, up to about 30 s)await new Promise(r => setTimeout(r, 4000));let buffer;for (let i = 0; i < 8; i++) { try { const resp = await fetch(`${BASE_URL}/videos/${task_id}/content`, { headers: { 'Authorization': `Bearer ${API_KEY}` } }); if (!resp.ok) throw Object.assign(new Error(`HTTP ${resp.status}`), { status: resp.status }); buffer = Buffer.from(await resp.arrayBuffer()); break; } catch (e) { if (i === 7 || (e.status !== 400 && i >= 1)) throw e; // 400: keep waiting; 502 etc.: one more try at most await new Promise(r => setTimeout(r, 4000)); }}fs.writeFileSync('output.mp4', buffer);console.log('Saved: output.mp4');
Browser JavaScript
{/* Demo only; route through a backend proxy in production to avoid Key leakage; large video downloads are also unsuitable for direct browser handling */}const submitResp = await fetch('https://api.apiyi.com/v1/videos', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer sk-your-api-key' }, body: JSON.stringify({ model: 'veo-3.1-fast-generate-preview', prompt: 'Watercolor northern lights over snowy mountains, gentle motion', seconds: '4', size: '720x1280', metadata: { resolution: '720p', aspectRatio: '9:16' } })});const submitData = await submitResp.json();const task_id = submitData.task_id || submitData.id;console.log('Task ID:', task_id);{/* After polling completes, route the /content endpoint through your backend proxy for download */}
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:
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
Param
Type
Required
Default
Description
model
string
Yes
—
veo-3.1-fast-generate-preview ($0.3/req) or veo-3.1-generate-preview ($1.2/req)
prompt
string
Yes
—
Video description; describe scene, action, camera, lighting, audio intent (do not pass generateAudio)
seconds
string
No
"8"
Video length, string enum: "4" / "6" / "8". The field is seconds, not duration (naming it duration is silently ignored, falls back to 4 sec). 1080p/4k must be "8"
size
string
No
1280x720
Output pixels, e.g. 1280x720 / 1920x1080 / 3840x2160; lower precedence than metadata.resolution
metadata.resolution
string
No
720p
720p / 1080p / 4k; higher precedence than size
metadata.aspectRatio
string
No
16:9
16:9 (landscape) or 9:16 (portrait)
metadata.seed
int
No
—
Random seed. Fixed seed clusters outputs in style (but cannot byte-reproduce)
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
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)