# Veo 视频生成

来源: https://docs.aicentos.com/veo-video

Language: zh-CN

> 通过 aicentos 调用 Google Veo 视频生成模型 —— 文生视频、图生视频、首尾帧、参考图

本文面向开发者，说明如何通过 aicentos 调用 Google Veo 视频生成模型。接口为 OpenAI 视频 API 兼容格式（OpenAI Videos API），下游接入时渠道类型使用 `openai` 即可。

## 模型能力说明

按视频生成时长（秒）计费。具体单价以 aicentos 控制台为准，最终扣费以系统实际扣费记录为准。

### 官方能力与 aicentos 开放口径

| 模型                              | 支持秒数  | 支持分辨率         | 画面比例      | 音频    | 说明                                       |
| ------------------------------- | ----- | ------------- | --------- | ----- | ---------------------------------------- |
| `veo-3.1-generate-preview`      | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生带音频 | 1080p 和 4k 仅支持 8 秒；用参考图、首尾帧等图片能力时建议 8 秒。 |
| `veo-3.1-fast-generate-preview` | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生带音频 | 1080p 和 4k 仅支持 8 秒；用参考图、首尾帧等图片能力时建议 8 秒。 |

参考文档：

* [Google Gemini API Veo 视频生成](https://ai.google.dev/gemini-api/video)
* [Veo 参考图说明](https://ai.google.dev/gemini-api/video#reference_images)
* [Veo 首尾帧说明](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Veo 画面比例说明](https://ai.google.dev/gemini-api/video#aspect_ratio)

### 画面比例

| 模型                              | 16:9 横屏 | 9:16 竖屏 | 默认比例 | 建议                   |
| ------------------------------- | ------- | ------- | ---- | -------------------- |
| `veo-3.1-generate-preview`      | 支持      | 支持      | 16:9 | 4K 必须用 8 秒；视频扩展暂不开放。 |
| `veo-3.1-fast-generate-preview` | 支持      | 支持      | 16:9 | 4K 必须用 8 秒；视频扩展暂不开放。 |

请求中可以通过 `metadata.aspectRatio` 或表单字段 `aspectRatio` 指定比例：

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

如果没有显式传 `aspectRatio`，系统会优先根据 `size` 推导比例，例如 `1280x720` 推导为 16:9、`720x1280` 推导为 9:16。如果 `size` 也未传，上游默认使用 16:9。

### 音频说明

| 模型                              | 官方音频能力 | 支持 generateAudio | 建议                                    |
| ------------------------------- | ------ | ---------------- | ------------------------------------- |
| `veo-3.1-generate-preview`      | 原生带音频  | 不支持              | 不要传 `generateAudio`，需要声音效果请写进 prompt。 |
| `veo-3.1-fast-generate-preview` | 原生带音频  | 不支持              | 不要传 `generateAudio`，需要声音效果请写进 prompt。 |

Veo 3.1 系列是原生带音频的视频模型，但当前 Gemini API 的 Veo 参数表没有开放 `generateAudio` 作为可控参数。传入该字段可能会被上游返回 `INVALID_ARGUMENT`。

如果希望控制音频内容，可以在 prompt 中描述对白、环境音、音效或音乐风格，例如：

```bash
黄昏海边的灯塔，海浪轻拍礁石，远处有低沉的风声和海鸟声，电影级光影，稳定运镜
```

## 图片输入能力

| 能力         | Google 官方 Veo 能力                   | aicentos 接口支持 | 说明                                                                                                |
| ---------- | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| 单张初始图生成视频  | 支持                                 | 支持            | 使用 `input_reference` 上传 1 张图片，作为视频起始画面。                                                           |
| 首尾帧生成 / 插帧 | Veo 3.1 系列支持 image + lastFrame     | 支持            | 首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。建议 Veo 3.1 系列、8 秒。                           |
| 多张参考图      | Veo 3.1 系列支持最多 3 张 referenceImages | 支持            | 用 `reference_image`、`reference_images` 或 `referenceImages` 上传，`referenceType` 仅支持 `asset`。建议 8 秒。 |
| 视频扩展       | Veo 3.1 / Fast 支持扩展已有 Veo 视频       | 暂不支持          | 当前 aicentos 接口没有开放官方 video 输入。                                                                    |

* 图片 MIME 类型支持 `image/jpeg`、`image/png`、`image/webp`。推荐传文件或 Base64，不建议直接传远程图片 URL。
* 参考图模式注意：当前上游在参考图场景不支持 `negativePrompt`，传入后可能返回 `Negative prompt is not supported in your use case`。参考图请求请不要传 `negativePrompt`。
* 实现说明：Gemini API 的 Veo `predictLongRunning` 图片入参使用 `bytesBase64Encoded` + `mimeType`，不是普通 `generateContent` 的 `inlineData`。aicentos 会把 multipart 上传的图片转换成上游需要的格式。

## 计费规则

* 按视频生成时长计费，单位为秒。请使用上表中模型支持的秒数，不建议传任意秒数。
* 如果请求未指定视频时长，系统默认按 8 秒计费。
* 秒数识别优先级：`metadata.durationSeconds` > `duration` > `seconds` > 默认 8 秒。
* 分辨率识别优先级：`metadata.resolution` > `size` > 默认 720p。
* 720p / 1080p / 4K 按相同规则计费，不因分辨率单独加价。
* `aspectRatio` 只控制横屏或竖屏，不单独加价。
* 4K 只支持 8 秒。
* 具体单价以 aicentos 控制台为准。

## 接口说明

当前推荐使用这 3 个接口：

| 用途   | 方法   | 路径                             |
| ---- | ---- | ------------------------------ |
| 创建任务 | POST | `/v1/videos`                   |
| 查询状态 | GET  | `/v1/videos/{task_id}`         |
| 下载结果 | GET  | `/v1/videos/{task_id}/content` |

如果希望查询时直接拿到结果地址，也可以使用：

| 用途        | 方法  | 路径                                |
| --------- | --- | --------------------------------- |
| 查询状态和结果地址 | GET | `/v1/video/generations/{task_id}` |

### 鉴权

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

所有请求都带：

```bash
-H "Authorization: Bearer $AICENTOS_API_KEY"
```

### 创建文生视频任务

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，电影级光影，稳定运镜",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

典型返回：

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

### 创建首帧图生视频任务

当前图生视频推荐使用 `multipart/form-data`，首帧图片字段名必须是 `input_reference`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=让画面中的女孩转头看向镜头，微风吹动头发，背景城市灯光轻微虚化，镜头平稳推进" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### 创建首尾帧任务

首尾帧需要同时提供首帧和尾帧。首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=从第一张女孩画面自然过渡到最后一张男孩画面，镜头平稳推进，城市灯光虚化，发丝和衣服有轻微风动，过渡自然真实" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### 创建参考图任务

参考图任务只支持 Veo 3.1 系列，最多 3 张，且 `referenceType` 仅支持 `asset`。字段名可用 `reference_image`、`reference_images` 或 `referenceImages`。参考图任务不要传 `negativePrompt`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=参考两张图片中的人物外观和城市夜景氛围，生成一段电影感双人街头镜头，镜头平稳推进，背景灯光轻微虚化，人物自然看向镜头" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 也支持：

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "使用参考图中的产品外观生成广告镜头",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### 查询任务状态

先把创建接口返回的 `id` 或 `task_id` 保存下来：

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

然后查询状态：

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

处理中时，典型返回：

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

完成后，典型返回：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### 查询任务状态和结果地址

如果想在查询时直接拿到可下载地址，可以调用：

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

典型返回：

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### 下载视频结果

任务完成后，直接下载：

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## 状态说明

`GET /v1/videos/{task_id}` 返回的状态主要有：

| 状态            | 说明  |
| ------------- | --- |
| `queued`      | 已排队 |
| `in_progress` | 生成中 |
| `completed`   | 已完成 |
| `failed`      | 失败  |

`GET /v1/video/generations/{task_id}` 返回的状态主要有：

| 状态           | 说明  |
| ------------ | --- |
| `queued`     | 已排队 |
| `processing` | 生成中 |
| `succeeded`  | 已成功 |
| `failed`     | 失败  |

## 接入注意事项

* `prompt` 必填。
* 图生视频时，图片字段名必须是 `input_reference`。
* 首尾帧任务必须同时提供首帧和尾帧，首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。
* 参考图任务只支持 Veo 3.1 系列，最多 3 张，且必须 8 秒。
* 参考图任务不要传 `negativePrompt`。
* 当前 Gemini 图生视频不建议直接传远程图片 URL，推荐传文件或 Base64。
* 建议轮询 `GET /v1/videos/{task_id}`，等 `status=completed` 后再下载。
* Veo 3.1 系列可以传 4、6、8 秒；当使用 1080p 或 4k 时必须传 8 秒。- 横屏使用 `aspectRatio=16:9`，竖屏使用 `aspectRatio=9:16`；如果不传，默认按 16:9 处理。
* 不要传 `generateAudio` 参数。Veo 3.1 系列是原生带音频的视频模型，但当前 Gemini API 不支持通过 `generateAudio` 参数开关音频；传入该字段可能会被上游返回 `INVALID_ARGUMENT`。
* 如需控制音频内容，请在 prompt 中描述对白、环境音、音效或音乐风格。
* 官方 Veo 3.1 支持视频扩展，但当前 aicentos 接口暂未开放官方 video 输入。