# Gemini Omni Character 角色生成 API 对接文档

## 概述

Gemini Omni Character 角色生成接口，基于一张参考图片创建一个可在视频生成中复用的角色。本接口为**同步接口**，调用成功后立即返回 `characterId`，可直接传入 Gemini Omni Video 生视频接口的 `characterIds` 参数。

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

> 当前接口为公测能力，**暂不计费**。

---

## 认证方式

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

---

## 快速开始

### cURL 示例

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-character" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色，冷静、敏捷，具有赛博朋克气质。",
    "imageUrls": ["https://example.com/character-reference.png"],
    "characterName": "珍妮"
  }'
```

**附带语音 ID 创建（让角色拥有指定音色）**
```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-character" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色",
    "imageUrls": ["https://example.com/character-reference.png"],
    "audioIds": ["a8f1c2d3e4f5..."],
    "characterName": "珍妮"
  }'
```

---

## 接口列表

### 1. 创建角色

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

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| descriptions | string | 是 | 角色描述，用于说明角色的外观、身份、风格、服饰或性格设定 |
| imageUrls | string[] | 是 | 角色参考图片 URL，**仅支持 1 张**，单张图片大小 ≤ 20MB，需为可公开访问的 URL |
| audioIds | string[] | 否 | 由生语音接口生成的语音 ID 数组，用于为角色补充声音特征/语气/人设参考 |
| characterName | string | 否 | 角色名称 |

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.characterId | string | 角色 ID，可用于生视频接口的 `characterIds` 参数 |
| data.characterName | string | 角色名称 |
| data.imageUrl | string | 角色封面图 URL |

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "characterId": "b09dbf56...",
    "characterName": "珍妮",
    "imageUrl": "https://xx.com/a.png"
  }
}
```

**参数错误**
```json
{
  "code": 10002,
  "msg": "imageUrls 必须传 1 张图片",
  "data": null
}
```

> 创建成功后，该角色会自动保存到你的**角色素材库**，可通过下方素材管理接口查询和删除。

---

### 2. 查询角色素材列表

**GET** `/api/v2/open/omni/character/list`

查询当前账号已创建的角色素材（按创建时间倒序）。

#### 请求参数（Query）

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| page | int | 是 | 页码，从 1 开始 |
| pageSize | int | 是 | 每页数量，1-100 |
| keyword | string | 否 | 按角色名称模糊搜索 |

#### cURL 示例

```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/omni/character/list?page=1&pageSize=20" \
  -H "Authorization: Bearer your_auth_token_here"
```

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| data.list | object[] | 角色素材列表 |
| data.list[].characterId | string | 角色 ID，可用于生视频接口的 `characterIds` 参数 |
| data.list[].characterName | string | 角色名称 |
| data.list[].descriptions | string | 角色描述 |
| data.list[].imageUrl | string | 角色封面图 URL |
| data.list[].audioIds | string[] | 创建时关联的语音 ID |
| data.list[].createdTime | string | 创建时间 |
| data.total | int | 总数 |
| data.page | int | 当前页 |
| data.pageSize | int | 每页数量 |

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "characterId": "b09dbf56...",
        "characterName": "珍妮",
        "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色",
        "imageUrl": "https://xx.com/a.png",
        "audioIds": ["a8f1c2d3e4f5..."],
        "createdTime": "2026-06-10T15:00:00+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
```

---

### 3. 删除角色素材

**POST** `/api/v2/open/omni/character/delete`

从素材库中删除指定角色（仅删除素材库记录，不影响已创建的视频任务）。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| characterId | string | 是 | 要删除的角色 ID |

#### cURL 示例

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/omni/character/delete" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "characterId": "b09dbf56..." }'
```

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

**素材不存在**
```json
{
  "code": 90003,
  "msg": "角色素材不存在或无权限",
  "data": null
}
```

---

## 错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 30002 | 上游服务调用失败 |
| 90003 | 服务器内部错误 |

---

## 最佳实践

1. **图片质量**：选择面部清晰、光照均匀、构图简洁的参考图，能显著提升角色一致性。
2. **复用 characterId**：创建一次角色后保存返回的 `characterId`，可多次用于不同视频生成任务，保持人设统一；忘记 ID 时可通过素材列表接口找回。
3. **配合生语音接口**：先调用生语音接口获取 `audioId`，再在创建角色时通过 `audioIds` 关联，可让该角色具备指定音色。
4. **在生视频接口中使用**：把返回的 `characterId` 加入生视频接口的 `characterIds` 数组；注意配额规则——基础最多 7 个，含源视频时最多 3 个，且需满足 `imageUrls + videoList×2 + characterIds ≤ 7`。