# Gemini Omni Video 视频生成 API 对接文档

## 概述

Gemini Omni Video 视频生成接口，支持文本生成视频、参考图引导生成、源视频片段重制、角色保形、配音对白等多模态使用方式。

**Base URL**: `https://api.apiverse.ai`

> **配套接口**：
> - 生角色：`POST /api/v2/open/aigc/gemini-omni-character`，同步返回 `characterId`，可在本接口的 `characterIds` 中引用。
> - 生语音：`POST /api/v2/open/aigc/gemini-omni-audio`，同步返回 `audioId`，可在本接口的 `audioIds` 中引用。
> - 详见对应接口文档。

---

## 认证方式

所有接口均需要在请求头中携带 Token 进行认证：

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

## 快速开始

### cURL 示例

**1. 纯文生视频**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-video" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at sunset, cinematic, slow camera push-in",
    "resolution": "1080p",
    "duration": 6
  }'
```

**2. 参考图引导生成（最多 7 张参考图）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-video" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character walks out from the neon-lit alley, slow motion",
    "imageUrls": [
      "https://example.com/scene-1.png",
      "https://example.com/scene-2.png"
    ],
    "resolution": "720p",
    "duration": 8
  }'
```

**3. 基于源视频片段重制（提供源视频后 duration 不再生效）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-video" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Restyle the scene with cyberpunk lighting",
    "videoList": [
      { "url": "https://example.com/source.mp4", "start": 0, "ends": 8 }
    ],
    "resolution": "1080p"
  }'
```

**4. 配合源视频与参考图组合使用**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-video" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Restyle the source clip with cyberpunk lighting, keep the character",
    "imageUrls": ["https://example.com/character-ref.png"],
    "videoList": [
      { "url": "https://example.com/source.mp4", "start": 0, "ends": 6 }
    ],
    "resolution": "1080p"
  }'
```

**5. 使用角色 ID + 语音 ID + 指定宽高比和种子**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-video" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character walks into a neon-lit street and starts narrating",
    "characterIds": ["char_xxx"],
    "audioIds": ["audio_xxx"],
    "resolution": "1080p",
    "duration": 8,
    "aspectRatio": "9:16",
    "seed": 12345
  }'
```

**查询任务状态**
```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"
```

---

## 接口列表

### 1. 创建 Gemini Omni Video 任务

**POST** `/api/v2/open/aigc/gemini-omni-video`

**Content-Type**: `application/json`

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 视频内容描述（建议描述目标内容、风格、镜头语言） |
| imageUrls | string[] | 否 | 参考图片 URL 列表，最多 7 张，每张不超过 20MB |
| audioIds | string[] | 否 | 语音 ID 列表（来自生语音接口），最多 3 个 |
| videoList | object[] | 否 | 源视频片段，最多 1 个，结构见下方 |
| characterIds | string[] | 否 | 角色 ID 列表（来自生角色接口），最多 7 个；当同时传入 `videoList` 时最多 3 个 |
| resolution | string | 否 | 输出分辨率：`720p`(默认) / `1080p` / `4k` |
| duration | int | 否 | 时长（秒）：`4` / `6`(默认) / `8` / `10`；提供 `videoList` 时此项不生效 |
| aspectRatio | string | 否 | 画面宽高比：`16:9`(横屏) / `9:16`(竖屏) |
| seed | int | 否 | 随机种子，取值范围 `[0, 2147483647]`，固定 seed 可提高结果可复现性 |
| callbackUrl | string | 否 | 任务完成后的回调通知 URL |

**videoList 元素结构**

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| url | string | 是 | 源视频地址，单文件不超过 100MB，时长不超过 30 秒 |
| start | int | 是 | 起始时间（秒），`start >= 0` |
| ends | int | 是 | 结束时间（秒），`ends > start` 且 `ends - start` 不超过 10 |

> **配额规则**：
> 系统对参考素材采用配额制管理，总可用配额为 **7**：
> - 每张 `imageUrls` 占用 1 个配额
> - 每个 `videoList`（含视频输入时）占用 2 个配额，最多 1 个
> - 每个 `characterIds` 占用 1 个配额
>
> 计算公式：`imageUrls 数 + videoList 数 × 2 + characterIds 数 ≤ 7`
>
> 示例：
> - 上传 1 个视频（占 2）+ 3 个角色（占 3），还能再上传 2 张图片
> - 不上传视频和角色，最多可上传 7 张图片

> **说明**：
> - 当 `videoList` 不为空时，视为"含视频输入"模式，按对应价表计费，`duration` 不再生效。
> - `imageUrls` / `videoList` / `characterIds` / `audioIds` 可单独或组合使用。
> - 创建任务时会按价表预扣费，余额不足将返回错误。

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID |
| data.status | string | 任务状态，创建时固定为 `processing` |
| data.createdAt | string | 创建时间 |

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260521150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-21 15:00:00"
  }
}
```

**余额不足**
```json
{
  "code": 40001,
  "msg": "余额不足: 当前余额 0.0100, 需要 0.4500",
  "data": null
}
```

**参数错误**
```json
{
  "code": 10002,
  "msg": "duration 仅支持 4/6/8/10 秒",
  "data": null
}
```

---

### 2. 查询任务状态

**GET** `/api/v2/open/aigc/{taskId}`

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260521150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/21/output_001.mp4"
    ],
    "createdAt": "2026-05-21 15:00:00",
    "updatedAt": "2026-05-21 15:02:30"
  }
}
```

---

### 3. 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

批量查询多个任务的执行状态（最多 100 个）。

---

### 4. 查询账户余额

**GET** `/api/v2/open/balance`

---

## 回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。

### 回调请求

**Headers**
```
Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}
```

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260521150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-21T15:02:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

---

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 30003 | 任务不存在 |
| 40001 | 余额不足 |
| 90003 | 服务器内部错误 |

---

## 价格

价格单位：USD / 个视频

**含视频输入**（请求中含 `videoList`，与时长无关）

| 分辨率 | 价格 |
|--------|------|
| 720p   | 1.20 |
| 1080p  | 1.20 |
| 4k     | 1.80 |

**无视频输入**

| 分辨率 \ 时长 | 4s | 6s | 8s | 10s |
|------|------|------|------|------|
| 720p   | 0.45 | 0.60 | 0.75 | 0.90 |
| 1080p  | 0.45 | 0.60 | 0.75 | 0.90 |
| 4k     | 1.05 | 1.20 | 1.35 | 1.50 |

---

## 最佳实践

### 1. 轮询策略

建议的轮询间隔：
- 前 60 秒：每 5 秒查询一次
- 60 秒后：每 10 秒查询一次

### 2. 使用回调

生产环境建议使用回调通知而非轮询。

### 3. 提示词建议

- 详细描述动作、场景、风格、镜头语言
- 使用 `imageUrls` 时，提示词可描述参考图如何被组织进画面
- 使用 `videoList` 时，提示词描述对源视频做怎样的重制/风格化
- 使用 `characterIds` 时，可在提示词中提及角色名/动作/对白，模型会保持角色外观一致
- 使用 `audioIds` 时，可描述对白、旁白或配乐情绪，模型会按所选语音生成发声

### 4. 资产准备

| 资产 | 限制 |
|------|------|
| 参考图片 | 单张 ≤ 20MB，最多 7 张 |
| 源视频 | 单文件 ≤ 100MB，时长 ≤ 30 秒，截取片段长度 ≤ 10 秒 |
| 角色 ID | 通过生角色接口获取，配额制下基础最多 7 个，含源视频时最多 3 个 |
| 语音 ID | 通过生语音接口获取，最多 3 个 |

### 5. 余额管理

- 创建任务前建议先查询余额
- 任务成功后会从冻结余额中扣费
- 任务失败后冻结金额会自动退还到可用余额