> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ominiapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 视频生成

# veo视频生成omini-api异步任务

本文面向开发者，说明如何通过 `omini-api` 调用 Google Veo 视频生成模型。下游接入时，渠道类型使用 `openai` 即可。

## 基础信息

| 项目        | 内容                                    |
| --------- | ------------------------------------- |
| 默认服务地址    | `https://www.ominiapi.com`            |
| 鉴权方式      | Bearer Token                          |
| 创建任务      | `POST /v1/videos`                     |
| 查询状态      | `GET /v1/videos/{task_id}`            |
| 下载结果      | `GET /v1/videos/{task_id}/content`    |
| 查询状态和结果地址 | `GET /v1/video/generations/{task_id}` |
| 文生视频请求格式  | `application/json`                    |
| 图片任务推荐格式  | `multipart/form-data`                 |

## 官方能力与本站开放口径

| 模型                              | 支持秒数          | 支持分辨率                 | 支持画面比例         | 音频    | 说明                                                  |
| ------------------------------- | ------------- | --------------------- | -------------- | ----- | --------------------------------------------------- |
| `veo-3.0-generate-001`          | `8`           | `720p`, `1080p`       | `16:9`, `9:16` | 原生带音频 | 官方模型能力表标注为 8 秒视频，分辨率为 720p / 1080p；本站不对外承诺 4K。      |
| `veo-3.0-fast-generate-001`     | `8`           | `720p`, `1080p`       | `16:9`, `9:16` | 原生带音频 | 官方模型能力表标注为 8 秒视频，分辨率为 720p / 1080p；本站不对外承诺 4K。      |
| `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 官方文档中的参数表和模型能力表对 Veo 3 / Veo 3 Fast 的部分描述存在差异。为了避免下游误用，本站文档按更保守的模型能力表口径描述：Veo 3 / Veo 3 Fast 仅对外承诺 `8` 秒、`720p / 1080p`。

参考文档：

* Google Gemini API Veo 视频生成文档：[https://ai.google.dev/gemini-api/docs/video](https://ai.google.dev/gemini-api/docs/video)
* Google Gemini API Veo 参考图说明：[https://ai.google.dev/gemini-api/docs/video#reference\_images](https://ai.google.dev/gemini-api/docs/video#reference_images)
* Google Gemini API Veo 首尾帧说明：[https://ai.google.dev/gemini-api/docs/video#first\_and\_last\_frame](https://ai.google.dev/gemini-api/docs/video#first_and_last_frame)
* Google Gemini API Veo 画面比例说明：[https://ai.google.dev/gemini-api/docs/video#aspect\_ratio](https://ai.google.dev/gemini-api/docs/video#aspect_ratio)

## 画面比例

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

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

```json theme={null}
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

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

## 音频说明

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

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

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

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

## 图片输入能力

| 能力         | Google 官方 Veo 能力                     | 当前本站接口支持情况 | 说明                                                                                                   |
| ---------- | ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
| 单张初始图生成视频  | 支持                                   | 支持         | 使用 `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 / Veo 3.1 Fast 支持扩展已有 Veo 视频 | 暂不支持       | 当前本站接口没有开放官方 `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`。`omini-api` 会把 multipart 上传的图片转换成上游需要的格式。

## 参数识别规则

请使用模型支持的视频秒数，不建议传任意秒数。如果请求未指定视频时长，系统默认按 `8` 秒处理。

| 项目  | 识别优先级                                                          |
| --- | -------------------------------------------------------------- |
| 秒数  | `metadata.durationSeconds` > `duration` > `seconds` > 默认 `8` 秒 |
| 分辨率 | `metadata.resolution` > `size` > 默认 `720p`                     |

补充说明：

* `aspectRatio` 只控制横屏或竖屏。
* `4K` 仅 `veo-3.1-generate-preview` 和 `veo-3.1-fast-generate-preview` 对外开放，且只支持 `8` 秒。

## 接口说明

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

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

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

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

## 鉴权

```bash theme={null}
export BASE_URL="https://www.ominiapi.com"
export API_TOKEN="sk-xxxxxx"
```

所有请求都带：

```bash theme={null}
-H "Authorization: Bearer $API_TOKEN"
```

## 创建文生视频任务

`POST /v1/videos`

请求格式：`application/json`

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

典型返回：

```json theme={null}
{
  "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 theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_TOKEN" \
  -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 theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_TOKEN" \
  -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 theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_TOKEN" \
  -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 也支持：

```json theme={null}
{
  "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 theme={null}
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

然后查询状态：

```bash theme={null}
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_TOKEN"
```

处理中时，典型返回：

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

完成后，典型返回：

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

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

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

```bash theme={null}
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $API_TOKEN"
```

典型返回：

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://your-omini-api.example.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

## 下载视频结果

任务完成后，直接下载：

```bash theme={null}
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_TOKEN" \
  -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` 秒。
* Veo 3.0 系列本站对外建议只使用 `8` 秒、`720p / 1080p`。
* 横屏使用 `aspectRatio=16:9`，竖屏使用 `aspectRatio=9:16`；如果不传，默认按 `16:9` 处理。
* 不要传 `generateAudio` 参数。Veo 3 / Veo 3.1 系列是原生带音频的视频模型，但当前 Gemini API 不支持通过 `generateAudio` 参数开关音频；传入该字段可能会被上游返回 `INVALID_ARGUMENT`。
* 如需控制音频内容，请在 `prompt` 中描述对白、环境音、音效或音乐风格。
* 官方 Veo 3.1 支持视频扩展，但当前本站接口暂未开放官方 `video` 输入。