VEO 3.1 Official 影片生成 - API易文档中心

概述

VEO 3.1 Official 是 API易接入 Google Veo 3.1 系列的 官轉通道（透傳 Google AI Studio），直連 Google veo-3.1-generate-preview / veo-3.1-fast-generate-preview 非同步端點，模型 ID、響應欄位、約束條件與 Google 官方完全一致。按次計費、預設分組即可呼叫，是目前接入門檻最低的 Veo 3.1 官方品質通道。

🎬 核心亮點：透傳 Google AI Studio 官方端點 + 同步音影片原生輸出 + 4 / 6 / 8 秒靈活時長 + 720p / 1080p / 4k 三檔解析度 + 按次計費 $0.3 起 + 預設分組 + 按次計費 / 按量優先令牌即可呼叫（無需切換專屬分組）。適合廣告短片、電商影片素材、社交媒體內容、產品演示 等追求官方畫質 + 簡單接入的生產場景。

⚠️ 暫不返回 CDN URL，需要自行拉取 MP4 落地：本通道目前不輸出任何可分發的公網 / CDN URL——拿到 status: "completed" 後，通過 GET /v1/videos/{task_id}/content 拉取 MP4 二進位制流並儲存到你自己的 OSS / CDN，再分發給終端使用者。前端不能直連 /content 端點（需鑑權頭）。詳見下方端點一覽段落。

文生影片 API

POST /v1/videos，純文本提示詞生成影片，JSON 請求體，最簡單的入口。

圖生影片 API

POST /v1/videos + multipart 上傳 input_reference，讓靜態圖片動起來。

官轉 vs 官逆

與既有 VEO 3.1（官逆）的選型對照表。

視覺化介面測試

在 iCover 視覺化測試工具裡直接除錯本介面，無需寫程式碼。

非同步任務查詢 / 下載

在 API易後臺檢視已提交的影片任務、下載影片連結（API 之外的查詢入口）。

為什麼選 API易的 VEO 3.1 Official

對標 Google 官方 / Vertex AI 通道，針對企業生產場景在 接入門檻、穩定性、成本三方面做了深度最佳化：

官轉直連 · 模型 ID 一致

透傳到 Google AI Studio 的 Veo 3.1 非同步端點，模型 ID（veo-3.1-generate-preview / veo-3.1-fast-generate-preview）與官方完全一致，請求/響應欄位、約束條件一比一對齊。

開箱即用 · 無需切分組

走 Default 預設分組、按次計費或按量優先令牌均可呼叫（按量計費暫不支援），無需切換專屬分組。老使用者現有 Key 不改配置就能直接跑，是最低接入門檻的官方品質通道。

不限併發 · 企業可放量

賬號池聚合透傳，批量出片 / 短影片矩陣 / 廣告生產等高併發場景下可線性擴容，不受 Google 單賬號 Tier 限制。

按次定價 · 對比 Google 立省 60%+

veo-3.1-fast-generate-preview $0.3/次、veo-3.1-generate-preview $1.2/次，按次計費、4/6/8 秒 + 720p/1080p/4k 同價。對比 Google 官方 8 秒 1080p 立省 62-68%，疊加充值加贈活動進一步下降；失敗任務不計費。

全球零門檻接入

無需海外伺服器或代理，國內機房、家寬網路、海外節點均可直連 api.apiyi.com，省去為 Google AI Studio / Vertex AI 配置出海鏈路的麻煩。

專業服務 · 企業陪跑

團隊深耕影片生成場景，在 prompt 工程、解析度選型、批次生產、影片後處理等場景具備豐富經驗，可為企業客戶提供從 PoC 到生產上線的完整技術支援。

核心特性

同步音影片原生輸出

Veo 3.1 系列原生輸出帶同步音軌的影片（環境音、對話、配樂），無需後期單獨配音。音訊效果通過 prompt 描述即可。

4 / 6 / 8 秒靈活時長

seconds 字串列舉 "4" / "6" / "8"，按次計費、時長不影響單價。1080p / 4k 解析度僅支援 "8"。

三檔解析度分級

720p / 1080p / 4k 三檔，單價均一。橫屏（16:9）、豎屏（9:16）靈活切換。

精準指令遵循

Veo 3.1 在鏡頭運動、物體物理、人物表情等細節上的指令遵循能力領先同檔模型，支援豐富的鏡頭語言關鍵詞（推/拉/搖/跟、俯/仰拍等）。

圖生影片（input_reference）

上傳一張圖片作為影片起始幀，讓靜態畫面”動起來”。詳見圖生影片。

非同步任務化

提交後返回 task_id，輪詢狀態、獨立下載影片，便於批次管理和斷點續傳。

OpenAI 相容協議

base_url=https://api.apiyi.com/v1 + Bearer 鑑權，HTTP / OpenAI SDK 底層 client.post() 均可呼叫。

失敗不計費

非同步模式下，生成失敗、內容稽核攔截、引數錯誤等情況均不計費，僅 status=completed 的任務才扣費。

模型定價

API易使用 Pay-per-request 計費，在支援的時長和解析度組合內統一價格，不按時長或解析度額外加價。按 ai.google.dev/gemini-api/docs/pricing 公開價格測算，Google 官方 Veo 3.1 以秒計費；以下折扣按 8 秒影片 計算。

模型	API易價格	Google 官方 8 秒 1080p	Google 官方 8 秒 4K
`veo-3.1-fast-generate-preview`	$0.3 / 次	$0.96 便宜 68.8%	$2.40 便宜 87.5%
`veo-3.1-generate-preview`	$1.2 / 次	$3.20 便宜 62.5%	$4.80 便宜 75.0%

計費說明：

按 模型名 按次結算，與時長（4/6/8 秒）、解析度（720p/1080p/4k）、是否傳 input_reference 無關——選 4K 不加價
非同步模式下生成失敗 / 內容稽核攔截 / 服務過載錯誤均不計費
充值加贈政策見充值加贈活動，疊加後實際成本進一步下降
4K 同價但渲染慢 4–6 倍、檔案大 ~10 倍，日常用 1080p 價效比更優
Google 官方 4K 單價 fast $0.30/秒、standard $0.60/秒，8 秒約 $2.40 / $4.80（資料來源 ai.google.dev/gemini-api/docs/pricing）

分組介紹

VEO 3.1 Official 在 Default 預設分組即可呼叫（1x），無需切換專屬分組。令牌計費模式需為 按次計費 或 按量優先——按量計費暫不支援（請在控制台把令牌切到按次或按量優先）。

接入門檻對比：和 Sora 2 官轉（要求專屬 Sora2Official 分組 + 必須按量優先）相比，VEO 3.1 Official 走預設分組 + 按次或按量優先都行，適合追求”現有按次令牌一行 base_url 就接入” 的團隊。

維度	VEO 3.1 Official	備註
分組	`Default`（1x）	無需切換
計費模式	按次計費 ✅ / 按量優先 ✅ / 按量計費 ❌	按量計費不支援，必須切換
令牌要求	按次或按量優先 + Default 分組	不需要專屬令牌
倍率	1.0x	直接按定價表結算

技術規格

維度	`veo-3.1-fast-generate-preview`	`veo-3.1-generate-preview`
價格	$0.3 / 次	$1.2 / 次
支援時長（seconds，字串）	`"4"` / `"6"` / `"8"`	`"4"` / `"6"` / `"8"`
支援解析度（metadata.resolution）	`720p` / `1080p` / `4k`	`720p` / `1080p` / `4k`
支援比例（metadata.aspectRatio）	`16:9` / `9:16`	`16:9` / `9:16`
音軌	✅ 同步音影片	✅ 同步音影片
圖生影片（input_reference）	✅（僅 1 張參考圖）	✅（僅 1 張參考圖）
典型生成耗時	720p 60–90s · 1080p 80–120s · 4K 5–6 分鐘	同
影片留存	官方未明確，建議生成後立即下載落地	同
響應欄位	`id` / `task_id` / `status` / `progress` / `created_at`	同

1080p / 4k 解析度時 seconds 必須傳 "8"，傳 "4" 或 "6" 會被上游拒絕。720p 三檔時長都支援。

端點一覽

端點	方法	用途	Content-Type
`/v1/videos`	POST	提交影片生成任務（文生影片 / 圖生影片統一端點）	`application/json` 或 `multipart/form-data`
`/v1/videos/{task_id}`	GET	查詢任務狀態與進度	—
`/v1/videos/{task_id}/content`	GET	下載已生成的影片檔案（MP4 二進位制）	—

⚠️ 僅支援 MP4 二進位制流下載，暫不返回 CDN URL本通道目前不會在響應中輸出任何 CDN / 公網 URL——影片檔案只能通過 GET /v1/videos/{task_id}/content 拉取 MP4 二進位制流，需要帶 Authorization: Bearer 頭。這意味著：

響應欄位裡沒有 video_url / data.url / 任何可直接分發的連結
前端不能直接把端點 URL 貼到 <video> 標籤——瀏覽器請求不帶鑑權頭會 401
拿到 status: "completed" 後立即下載 MP4，落地到自己的 OSS / CDN，再把你自家的 URL 分發給終端使用者
影片留存期官方未明確，不要長期依賴遠端 task_id 拿影片

域名選擇：主域名 api.apiyi.com，也可使用 vip.apiyi.com / b.apiyi.com 等其它閘道域名，響應行為一致。

關鍵引數詳解

⚡ 完整引數速查表：跳轉到文生影片 - 引數說明速查一表看全 model / prompt / seconds / size / metadata.* 的型別、必填、預設值、取值約束。本節只展開最容易踩坑的 3 個引數。

`seconds`（影片時長）

控制時長的欄位名是 seconds（不是 duration），必須傳字串（"4" / "6" / "8"），傳數字會被服務端拒絕並報：

parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string

值	720p	1080p	4k
`"4"`	✅	❌	❌
`"6"`	✅	❌	❌
`"8"`	✅（預設）	✅（必填）	✅（必填）

常見踩坑：欄位名寫成 duration 會被靜默忽略。duration 不是本通道識別的欄位 → 被丟棄 → 時長回落到預設 4 秒：

720p 等允許 4 秒的解析度：不報錯，但只出 4 秒（“傳了 8s 卻只出 4s” 就是這麼來的）
1080p / 4k：因 4 秒非法直接報錯 Resolution 1080p requires duration seconds to be 8 seconds, but got 4

正確寫法：請求欄位用 seconds，值 "8"（字串）。

引數識別優先順序：metadata.durationSeconds > seconds > 8

`metadata.resolution`（解析度）

值	畫素（橫）	畫素（豎）	備註
`720p`（預設）	`1280x720`	`720x1280`	三檔時長都可用
`1080p`	`1920x1080`	`1080x1920`	僅支援 `seconds="8"`
`4k`	`3840x2160`	`2160x3840`	僅支援 `seconds="8"`，渲染慢 4–6 倍

引數識別優先順序：metadata.resolution > size > 720p

⚠️ 不要傳 `generateAudio`

Veo 3 / 3.1 原生帶音訊，但 generateAudio 引數不要傳，上游會回 INVALID_ARGUMENT。要控制音訊效果，把意圖寫進 prompt：

“黃昏海邊的燈塔，海浪聲、遠處海鳥叫聲，低沉的風聲，電影級氛圍”

最佳實踐

按需選模型

試水 / 批次預覽 → veo-3.1-fast-generate-preview（$0.3/次）
最終交付 / 4K 高畫質 → veo-3.1-generate-preview（$1.2/次）
同 prompt + 同 seed 下兩個模型各跑一次，人工挑成片

先調通 4 秒再放大時長

每個 prompt 先用 seconds: "4" 快速驗證鏡頭方向、風格是否符合預期（耗時 60–90 秒、單價 $0.3），定型後再放大到 8 秒或換 1080p。

走非同步輪詢而不是同步等待

官轉通道僅支援非同步：POST 提交拿 task_id → 每 8–10 秒輪詢 GET /v1/videos/{task_id} 直到 status: "completed" → 從 /content 下載 MP4。沒有 webhook，只能輪詢。

客戶端超時分檔配置

720p / 1080p：3 分鐘硬超時
4K：10 分鐘硬超時
POST 提交（multipart）：30 秒起步

完成後立即下載落地

生成完成後立即下載到自己的 OSS / CDN，不要長期依賴遠端 task_id 拿影片。status 剛翻 completed 後調 /content 偶發 400，等 4 秒重試一次即可（參考客戶端已內建重試）。

音訊效果寫進 prompt

不要傳 generateAudio 引數（會被 INVALID_ARGUMENT 拒）。要環境音 / 對白 / BGM 直接寫到 prompt 裡：“海浪聲、遠處海鳥叫聲、低沉的風聲”。

生產側自己限流

併發上限官方未明示，實測同時 10 個任務全部成功入隊。生產側建議 in-flight ≤ 10，對 429 / 5xx 加指數退避重試。

錯誤碼與重試

狀態碼 / 現象	含義	處理建議
`400` + `parse_request_failed`	`seconds` 傳成數字了	改成字串 `"4"` / `"6"` / `"8"`
只出 4 秒 / `... but got 4`	欄位名寫成了 `duration`（被靜默忽略，回落預設 4 秒）	改用 `seconds`，值 `"8"`（字串）
`INVALID_ARGUMENT`	傳了 `generateAudio` 或 1080p/4k 配了非 8 秒	刪掉 `generateAudio`；解析度高檔時 `seconds="8"`
`401`	令牌無效	檢查 `Authorization: Bearer <key>` 無空格、key 未過期
`429`	限流 / 餘額不足	指數退避重試；充值後立即可用
`5xx` / `INTERNAL`	上游瞬時錯誤	保持同 seed 重試 1–2 次（不計費）
`GET /content` 偶發 400	`status` 剛翻 completed	等 4 秒重試一次（建議客戶端做 3–5 次重試）
任務 `failed`	影片生成失敗（多為內容稽核或上游容量）	調整 prompt 重試；該任務不計費

建議客戶端：

POST 提交超時 30 秒（multipart 上傳可能更慢）
GET 輪詢間隔 8–10 秒，最長等待 720p/1080p 3 分鐘、4K 10 分鐘
對 5xx 與任務 failed 做 指數退避重試（建議 1–2 次）
下載 /content 做 3–5 次重試，每次間隔 4 秒

常見問題

官轉和官逆有什麼區別？現在還能用官逆嗎？

官轉（本頁）：透傳到 Google AI Studio 官方端點，模型 ID 與 Google 官方一致（veo-3.1-generate-preview / veo-3.1-fast-generate-preview），按次 $0.3 / $1.2，僅支援非同步端點。官逆（既有 VEO 3.1）：通過逆向工程接入 Google Flow，模型 ID 是 veo-3.1-fast / veo-3.1 / -fl 系列，按次 $0.15 起，價格更便宜，同時支援 同步流式 與非同步兩種呼叫，且支援首尾幀。詳細對比見官轉 vs 官逆選型表。兩個通道並存，按業務需求選。

時長欄位到底是 seconds 還是 duration？為什麼要傳字串？

請求欄位名是 seconds（字串 "4" / "6" / "8"）。寫成 duration 不會被識別，會被靜默丟棄，時長回落到預設 4 秒——這是”傳了 8s 卻只出 4s”的根因。至於為什麼必須傳字串：後端的 Go struct 把這個欄位（內部名 duration）宣告為 string 型別，傳數字直接被解碼層拒掉，報 parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string（錯誤資訊裡出現的 duration 是後端內部欄位名，請求裡仍然要寫 seconds）。寫程式碼時記得：欄位名用 seconds、值加引號 "4" / "6" / "8"。

想要帶對白 / 環境音 / BGM 怎麼辦？generateAudio 能傳嗎？

Veo 3 / 3.1 是 原生帶音訊 的影片模型，但 generateAudio 這個引數 不要傳（傳了會被上游回 INVALID_ARGUMENT）。要控制聲音，把音訊意圖寫進 prompt：

“黃昏海邊的燈塔，海浪聲、遠處海鳥叫聲，低沉的風聲，電影級氛圍”

fast 和 standard 到底怎麼選？fast 是更快還是更便宜？

同等引數下 渲染時長基本相同（實測 720p 8 秒：fast 83s、standard 78s），fast 不是更快，而是更便宜（$0.3 vs $1.2）
預設用 veo-3.1-fast-generate-preview
最終交付、對畫面細膩度 / 物理一致性敏感時切 veo-3.1-generate-preview
建議線上 AB：同 prompt + 同 seed 下兩個模型各跑一次，人工挑

4K 值得用嗎？什麼時候用 4K？

絕大多數場景不推薦：

同價格按次，聽起來划算
但渲染慢 4–6 倍（720p 80s → 4K 350s）
檔案大 ~10 倍（720p 4MB → 4K 40MB），頻寬 / 儲存成本翻倍
視覺上 1080p 已經夠用，大部分播放場景看不出差別

確實需要 4K 時：模型用 veo-3.1-generate-preview、seconds 必須 "8"、客戶端超時 ≥ 10 分鐘、非同步任務做好後臺處理。

任務什麼時候才算完成？要不要 webhook？

目前 沒有 webhook，只能輪詢 GET /v1/videos/{task_id}
推薦輪詢間隔：8 秒（實測夠用，不觸發限流）
實測耗時：720p / 1080p 60–115 秒，4K 5–6 分鐘
客戶端超時建議 720p/1080p 設 3 分鐘，4K 設 10 分鐘

GET /content 返回 400 是什麼原因？

status 剛翻 completed 後立即調 /v1/videos/{task_id}/content 偶發 400，是上游 CDN 同步延遲。等 4 秒重試一次通常就好（參考客戶端內建 3–5 次重試，間隔 4 秒）。

響應裡能直接拿到影片的 CDN URL 嗎？前端能直連嗎？

暫時不可以。本通道目前不返回任何 CDN / 公網 URL——響應欄位裡沒有 video_url / data.url 之類的可直接分發連結。唯一拿影片的方式：拿到 status: "completed" 後調 GET /v1/videos/{task_id}/content，返回 MP4 二進位制流（需要帶 Authorization: Bearer 頭）。生產側標準做法：

後端任務完成後立即下載 MP4 → 推到自己的 OSS / CDN
把自家 CDN URL 分發給終端使用者
前端 <video> 標籤不要直接指向 /content 端點——瀏覽器請求不帶鑑權頭會 401

後續如官方上線 CDN URL 輸出能力，本頁會同步更新。

影片在遠端儲存多久？需要立刻下載嗎？

官方文件未明確給出留存期。強烈建議生成完成後立即下載落本地儲存，不要長期依賴遠端 task_id 拿影片——/content 端點過期後會 404。

progress 欄位為什麼一直是 50%？

這個欄位是粗粒度，只在 0 / 50 / 100 三檔之間跳，不要拿來做百分比進度條。要展示進度，要麼用旋轉 loading，要麼按”已等待秒數 / 預期秒數”自己算。

影片生成失敗會扣費嗎？

不會。只對 status=completed 的任務計費，failed / 取消 / 內容稽核攔截 / 引數錯誤都免費。只要任務沒真正出片就不扣費。

seed 能復現一模一樣的影片嗎？

不能位元組級復現。實測同 prompt + 同 seed（88888）+ 同參數，fast 跑兩次：檔案大小 9.81 MB vs 9.25 MB、md5 完全不同、渲染耗時也不同。但 seed 不是裝飾品：同 seed 多次結果互相聚集（5 次實測組內檔案大小跨度僅 6%），不同 seed 系統性偏移（組間差距 +36.8%）。所以：

想要”穩定風格” → 固定 seed
想要”探索變體” → 換 seed 比換 prompt 局部詞更直觀
想要”精確重放” → 別想了，把 mp4 存下來

能傳多張參考圖嗎？能傳首尾幀嗎？

當前都不支援。圖生影片只能 1 張圖，欄位名固定 input_reference，且只接受檔案或 Base64，不接受遠端 URL。Google 官方 Veo 3.1 有多參考圖 / 首尾幀 / 影片擴充套件能力，但本站官轉通道暫未開放。首尾幀需求請用 VEO 3.1（官逆） 的 -fl 系列模型。

一次能併發多少任務？有 QPS 限制嗎？

實測一口氣提交 10 個任務全部成功入隊，未觸發拒絕。具體上限官方未明示，建議生產側自己限流（in-flight ≤ 10），對 429 / 5xx 加指數退避重試。

影片帶水印 / 溯源資訊嗎？

沒有可視水印
但帶 Google C2PA Content Credentials 簽名（urn:c2pa:...，Google C2PA Media Services 頒發），藏在 MP4 後設資料裡。終端使用者肉眼看不到，用 C2PA 工具（如 Adobe Content Authenticity）可以驗出”由 Veo 生成”
二創再分發知情即可，一般不影響播放

可以用 OpenAI 官方 SDK 直連嗎？

部分可以。介面是 OpenAI 風格的（Bearer 鑑權 + /v1/...），但 OpenAI 官方 SDK 沒有 videos.create 這個方法（/v1/videos 是自定義路徑），多半要用 OpenAI SDK 的底層 client.post() 或直接 HTTP 呼叫。直接 HTTP 最省事，詳見文生影片 Playground 頁的程式碼示例。

​概述

文生影片 API

圖生影片 API

官轉 vs 官逆

視覺化介面測試

非同步任務查詢 / 下載

​為什麼選 API易 的 VEO 3.1 Official

官轉直連 · 模型 ID 一致

開箱即用 · 無需切分組

不限併發 · 企業可放量

按次定價 · 對比 Google 立省 60%+

全球零門檻接入

專業服務 · 企業陪跑

​核心特性

同步音影片原生輸出

4 / 6 / 8 秒靈活時長

三檔解析度分級

精準指令遵循

圖生影片（input_reference）

非同步任務化

OpenAI 相容協議

失敗不計費

​模型定價

​分組介紹

​技術規格

​端點一覽

​關鍵引數詳解

​seconds（影片時長）

​metadata.resolution（解析度）

​⚠️ 不要傳 generateAudio

​最佳實踐

​錯誤碼與重試

​常見問題

​相關文件

概述

為什麼選 API易的 VEO 3.1 Official

核心特性

模型定價

分組介紹

技術規格

端點一覽

關鍵引數詳解

`seconds`（影片時長）

`metadata.resolution`（解析度）

⚠️ 不要傳 `generateAudio`

最佳實踐

錯誤碼與重試

常見問題

相關文件