VEO 3.1 Official 文生影片 API 參考

{/* OpenAI 官方 SDK 沒有 videos.create 方法，/v1/videos 是自定義路徑，需用底層 client.post() */}
from openai import OpenAI
import time

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

# 第 1 步：提交生成任務
resp = client.post(
    "/videos",
    body={
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "黃昏海邊的燈塔，鏡頭緩慢推進，海浪輕拍礁石，海鳥叫聲，電影級光影，穩定運鏡",
        "seconds": "8",  # 必須字串
        "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']}")

# 第 2 步：輪詢狀態（最長等 3 分鐘）
deadline = time.time() + 180
while time.time() < deadline:
    status_resp = client.get(f"/videos/{task_id}", cast_to=dict)
    print(f"Status: {status_resp['status']}, progress: {status_resp.get('progress', 0)}%")
    if status_resp["status"] == "completed":
        break
    if status_resp["status"] == "failed":
        raise RuntimeError(f"Generation failed: {status_resp}")
    time.sleep(8)

# 第 3 步：下載影片（status 剛翻 completed 偶發 400，等幾秒重試）
import urllib.request, urllib.error
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 剛翻 completed 的同步視窗（實測最長約 20 秒），多等幾輪；502 等其它錯誤最多再試 1 次
        if i == 7 or (e.code != 400 and i >= 1):
            raise
        time.sleep(4)
print("Saved: output.mp4")

import requests
import time

API_KEY = "sk-your-api-key"
BASE_URL = "https://api.apiyi.com/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 第 1 步：提交（JSON 請求體）
resp = requests.post(
    f"{BASE_URL}/videos",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "傍晚海邊的燈塔，鏡頭緩慢推進，穩定運鏡，海浪聲、遠處海鳥叫聲",
        "seconds": "8",  # ⚠️ 必須字串
        "size": "1280x720",
        "metadata": {
            "resolution": "720p",
            "aspectRatio": "16:9"
        }
    },
    timeout=30  # POST 提交本身只是入隊，30 秒足夠
).json()
task_id = resp.get("task_id") or resp["id"]
print(f"Task ID: {task_id}, status: {resp['status']}")

# 第 2 步：輪詢（最長等 3 分鐘，4K 用 10 分鐘）
deadline = time.time() + 180
while time.time() < deadline:
    status_resp = requests.get(f"{BASE_URL}/videos/{task_id}", headers=HEADERS).json()
    print(f"Status: {status_resp['status']}, progress: {status_resp.get('progress', 0)}%")
    if status_resp["status"] == "completed":
        break
    if status_resp["status"] == "failed":
        raise RuntimeError(f"Generation failed: {status_resp}")
    time.sleep(8)

# 第 3 步：下載（重試兜底 status 剛翻 completed 後的 400）
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 剛翻 completed 的同步視窗（實測最長約 20 秒），多等幾輪；502 等其它錯誤最多再試 1 次
        if i == 7 or (e.response.status_code != 400 and i >= 1):
            raise
        time.sleep(4)
print("Saved: output.mp4")

{/* 只想用已有 task_id 查詢/下載？見下方「已有 task_id？兩條 cURL 直接查狀態 / 下載」章節 */}
{/* 第 1 步：提交任務（注意時長欄位是 seconds，字串 "8"，不是數字 8，也不是 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": "黃昏海邊的燈塔，鏡頭緩慢推進，海浪聲，電影級光影",
    "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"

{/* 第 2 步：輪詢狀態（每 8 秒）*/}
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 8
done

{/* 第 3 步：下載影片檔案（--retry 兜底 status 剛翻 completed 後的偶發 400）*/}
sleep 4
curl -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.mp4
ls -lh output.mp4

import fs from 'node:fs';

const API_KEY = 'sk-your-api-key';
const BASE_URL = 'https://api.apiyi.com/v1';

// 第 1 步：提交
const 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: '一隻柯基犬在金色沙灘上奔跑，慢動作，黃昏時分，電影質感',
        seconds: '8',  // ⚠️ 必須字串
        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}`);

// 第 2 步：輪詢
let status = 'queued';
while (status !== 'completed' && status !== 'failed') {
    await new Promise(r => setTimeout(r, 8000));
    const statusResp = await fetch(`${BASE_URL}/videos/${task_id}`, {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    const data = await statusResp.json();
    status = data.status;
    console.log(`Status: ${status}, progress: ${data.progress ?? 0}%`);
}

if (status === 'failed') throw new Error('Generation failed');

// 第 3 步：下載（400 每 4 秒重試，最多約 30 秒）
await new Promise(r => setTimeout(r, 4000));
let buffer;
for (let i = 0; i < 8; i++) {
    try {
        const contentResp = await fetch(`${BASE_URL}/videos/${task_id}/content`, {
            headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        if (!contentResp.ok) throw Object.assign(new Error(`HTTP ${contentResp.status}`), { status: contentResp.status });
        buffer = Buffer.from(await contentResp.arrayBuffer());
        break;
    } catch (e) {
        if (i === 7 || (e.status !== 400 && i >= 1)) throw e;  // 400 多等幾輪；502 等其它錯誤最多再試 1 次
        await new Promise(r => setTimeout(r, 4000));
    }
}
fs.writeFileSync('output.mp4', buffer);
console.log('Saved: output.mp4');

{/* 僅作演示，生產請走後端代理避免 Key 洩露；影片檔案較大也不適合直接在瀏覽器下載 */}
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: '水彩風格的極光在雪山上空緩緩流動，柔和鏡頭',
        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);

{/* 輪詢完成後，把 /content 端點交給後端代理下載，再回流給前端展示 */}

curl "https://api.apiyi.com/v1/videos/task_xxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-your-api-key"

curl -fL --retry 7 --retry-delay 4 --retry-all-errors \
  "https://api.apiyi.com/v1/videos/task_xxxxxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer sk-your-api-key" \
  -o output.mp4

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025090,
  "expires_at": 1775111490,
  "video_url": "https://…/task_xxxxxxxxxxxxxxxx_0.mp4"
}