> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/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`

<Info>
  使用扁平的 `metadata`，不要再套 `metadata.instances` 或 `metadata.parameters`。Veo 3 系列原生生成音频，不传 `generateAudio`。Vertex 专用的输出存储、Pub/Sub、遮罩等企业端配置不属于此请求格式。
</Info>

## 模型与版本

| 模型 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`，并将媒体占位值替换为可访问的素材。请求被接受后会创建计费任务；提交超时后不要自动重复提交。

<Tabs>
  <Tab title="文生视频">
    ```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
      }
    }'
    ```
  </Tab>
</Tabs>

### 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，并调用 [查询视频任务](/zh-hans/api-reference/endpoint/query-video-task)。提交成功表示任务已创建；任务完成后再读取生成结果。不同路由的响应封装和结果位置可能不同。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.