> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Veo
> Veo 影片生成參數、媒體物件與 MixRoute metadata 請求示例。
Veo 生成包含原生音訊的影片。本頁按 Gemini Developer API 的欄位定義說明；MixRoute 將 `model`、`prompt` 保留在頂層，媒體輸入和生成設定直接放入 `metadata`。
`POST https://api.mixroute.ai/v1/video/generations`
使用扁平的 `metadata`，不要再套 `metadata.instances` 或 `metadata.parameters`。Veo 3 系列原生生成音訊，不傳 `generateAudio`。Vertex 專用的輸出儲存、Pub/Sub、遮罩等企業端配置不屬於此請求格式。
## 模型與版本
| 模型 ID | 版本 |
| - | - |
| `veo-3.1-generate-preview` | Veo 3.1 |
| `veo-3.1-fast-generate-preview` | Veo 3.1 Fast |
| `veo-3.0-generate-001` | Veo 3 |
| `veo-3.0-fast-generate-001` | Veo 3 Fast |
具體路由可用性以 [模型廣場](https://console.mixroute.ai/models) 為準。
## 請求參數
| 欄位 | 型別 | 必填 | 說明 |
| - | - | - | - |
| `model` | string | 是 | 完整 MixRoute 路由 ID。 |
| `prompt` | string | 是 | MixRoute 影片提示詞，用於描述場景和運動，也可包含對白、音效和音樂指令。 |
| `metadata` | object | 按場景 | 提供下列媒體輸入或生成設定時使用的容器。 |
| `metadata.image` | object | 否 | 首幀 Image 物件。`bytesBase64Encoded` 為原始 Base64 字串，`mimeType` 為 MIME 型別，例如 `image/png`、`image/jpeg`。 |
| `metadata.lastFrame` | object | 按場景 | 首尾幀過渡的尾幀 Image 物件，結構與 `image` 相同，須與 `metadata.image` 同時使用。 |
| `metadata.referenceImages` | object\[] | 否 | Veo 3.1 參考輸入，最多三個物件。每項包含 `image`（Image 物件）和 `referenceType: "asset"`，時長鬚為 8 秒。 |
| `metadata.video` | object | 否 | Veo 3.1 延長輸入，須來自此前的 Veo 生成結果。提供 `uri`，或在 `encodedVideo` 中提供 Base64 影片、在 `encoding` 中提供 MIME 型別；不要使用 Vertex 影片物件的 `gcsUri`、`bytesBase64Encoded` 欄位。 |
| `metadata.durationSeconds` | integer | 否 | Veo 3.1 為 4、6 或 8 秒；參考圖、延長、1080p 或 4k 場景須為 8。Veo 3/3 Fast 生成 8 秒影片。 |
| `metadata.aspectRatio` | string | 否 | 取值為 `16:9`（預設）或 `9:16`；舊版 Veo 3 的 1080p 輸出須為 `16:9`。 |
| `metadata.resolution` | string | 否 | Veo 3.1 支援 `720p`（預設）、`1080p`、`4k`；1080p/4k 須為 8 秒，延長僅支援 720p。Veo 3/3 Fast 使用 720p 或 1080p。 |
| `metadata.sampleCount` | integer | 否 | 生成影片數量。Gemini Developer API 每次請求生成一個影片，使用 `1`。 |
| `metadata.negativePrompt` | string | 否 | 描述希望從影片中排除的內容或視覺特徵。 |
| `metadata.personGeneration` | string | 否 | Veo 3.1 文生影片/延長使用 `allow_all`，圖生影片/首尾幀過渡/參考圖使用 `allow_adult`；地區政策可能將可用取值限制為 `allow_adult`。 |
| `metadata.enhancePrompt` | boolean | 否 | Veo 3/3.1 不支援關閉提示詞改寫。呼叫時省略此欄位，不通過 false 關閉此功能。 |
## 場景約束
* Image 物件使用原始 Base64 內容，不包含 `data:image/...;base64,` 字首，也不是任意 URL 字串。
* 參考圖和影片延長屬於 Veo 3.1 能力，不套用到舊版 Veo 3 路由。
* 延長輸入須為仍在保留期內的 Veo 產物：720p、16:9 或 9:16，且不超過 141 秒。每次延長增加 7 秒，最多延長 20 次、合計 148 秒；延長請求中的 `durationSeconds` 仍須為 8。
* 輸出幀率為 24 fps，音訊原生生成。產物保留時間有限，任務完成後應及時獲取結果。
## 呼叫示例
呼叫前設定環境變數 `MIXROUTE_API_KEY`，並將媒體佔位值替換為可訪問的素材。請求被接受後會建立計費任務；提交超時後不要自動重複提交。
```bash theme={null}
curl --location "https://api.mixroute.ai/v1/video/generations" \
--header "Authorization: Bearer $MIXROUTE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "veo-3.1-fast-generate-preview",
"prompt": "A blue circle gently pulses on a clean white background.",
"metadata": {
"durationSeconds": 4,
"aspectRatio": "9:16",
"resolution": "720p",
"sampleCount": 1
}
}'
```
### Python
```python theme={null}
import json
import os
import requests
payload = json.loads(r'''
{
"model": "veo-3.1-fast-generate-preview",
"prompt": "A blue circle gently pulses on a clean white background.",
"metadata": {
"durationSeconds": 4,
"aspectRatio": "9:16",
"resolution": "720p",
"sampleCount": 1
}
}
''')
response = requests.post(
"https://api.mixroute.ai/v1/video/generations",
headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
json=payload,
timeout=60,
)
response.raise_for_status()
print(response.json())
```
## 任務結果
儲存提交響應中的 MixRoute 任務 ID，並呼叫 [查詢影片任務](/docs/zh-hant/api-reference/endpoint/query-video-task)。提交成功表示任務已建立；任務完成後再讀取生成結果。不同路由的響應封裝和結果位置可能不同。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.