# Gemini Omni Audio 语音生成 API 对接文档

## 概述

Gemini Omni Audio 语音生成接口，用于创建一个可在视频生成中使用的语音角色（音色）。本接口为**同步接口**，调用成功后立即返回 `audioId`，可直接传入 Gemini Omni Video 生视频接口的 `audioIds` 参数。

**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-audio" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "audioId": "achernar",
    "name": "Adam Narrator",
    "voiceDescription": "一个沉稳、清晰、富有亲和力的男性声音，适合科技产品讲解与日常对话。",
    "exampleDialogue": "你好，我是 Adam"
  }'
```

---

## 接口列表

### 1. 创建语音

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

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| audioId | string | 是 | 预设语音编号，详见下方"预设语音列表" |
| name | string | 是 | 语音名称（≤ 210 字符） |
| voiceDescription | string | 否 | 语音特征描述，用于定义音色、风格、语速、情绪等（≤ 20000 字符） |
| exampleDialogue | string | 否 | 对话示例（≤ 120 字符） |

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.audioId | string | 语音 ID，可用于生视频接口的 `audioIds` 参数 |
| data.name | string | 语音名称 |

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "audioId": "a8f1c2d3e4f5...",
    "name": "Adam Narrator"
  }
}
```

**参数错误**
```json
{
  "code": 10002,
  "msg": "name 不能超过 210 字符",
  "data": null
}
```

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

---

### 2. 查询语音素材列表

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

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

#### 请求参数（Query）

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

#### cURL 示例

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

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| data.list | object[] | 语音素材列表 |
| data.list[].audioId | string | 语音 ID，可用于生视频接口的 `audioIds` 参数 |
| data.list[].name | string | 语音名称 |
| data.list[].presetId | string | 创建时使用的预设语音编号 |
| data.list[].voiceDescription | string | 语音特征描述 |
| data.list[].exampleDialogue | string | 对话示例 |
| data.list[].createdTime | string | 创建时间 |
| data.total | int | 总数 |
| data.page | int | 当前页 |
| data.pageSize | int | 每页数量 |

#### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "audioId": "a8f1c2d3e4f5...",
        "name": "Adam Narrator",
        "presetId": "achernar",
        "voiceDescription": "一个沉稳、清晰、富有亲和力的男性声音",
        "exampleDialogue": "你好，我是 Adam",
        "createdTime": "2026-06-10T15:00:00+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
```

---

### 3. 删除语音素材

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

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| audioId | string | 是 | 要删除的语音 ID |

#### cURL 示例

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

#### 响应示例

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

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

---

## 预设语音列表

`audioId` 参数仅支持以下预设语音编号：

| audioId | 音色描述 |
|---------|----------|
| achernar | 女声，柔和，高音调 |
| achird | 男声，友好，中音调 |
| algenib | 男声，沙哑，低音调 |
| algieba | 男声，随和，中低音调 |
| alnilam | 男声，沉稳，中低音调 |
| aoede | 女声，轻快，中音调 |
| autonoe | 女声，明亮，中音调 |
| callirrhoe | 女声，随和，中音调 |
| charon | 男声，知性，低音调 |
| despina | 女声，流畅，中音调 |
| enceladus | 男声，气声，低音调 |
| erinome | 女声，清晰，中音调 |
| fenrir | 男声，活泼，偏年轻音调 |
| gacrux | 女声，成熟，中音调 |
| iapetus | 男声，清晰，中低音调 |
| kore | 女声，干练，中音调 |
| laomedeia | 女声，欢快，中高音调 |
| leda | 女声，年轻，中高音调 |
| orus | 男声，沉稳，中低音调 |
| puck | 男声，欢快，中音调 |
| pulcherrima | 无性别，前置感，中高音调 |
| rasalgethi | 男声，知性，中音调 |
| sadachbia | 男声，生动，低音调 |
| sadaltager | 男声，博学，中音调 |
| schedar | 男声，平稳，中低音调 |
| sulafat | 女声，温暖，中音调 |
| umbriel | 男声，流畅，低音调 |
| vindemiatrix | 女声，温柔，中音调 |
| zephyr | 女声，明亮，中高音调 |
| zubenelgenubi | 男声，随性，中低音调 |

---

## 错误码

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

---

## 最佳实践

1. **复用 audioId**：创建一次语音后保存返回的 `audioId`，可多次用于不同视频生成任务；忘记 ID 时可通过素材列表接口找回。
2. **结合 voiceDescription**：在 `voiceDescription` 中描述使用场景（如"沉稳的科技产品讲解"、"活泼的儿童故事"），有助于在生视频时获得更贴合的发声效果。
3. **配合生角色接口**：可在生角色接口的 `audioIds` 中传入本接口返回的 `audioId`，让该角色具备指定音色。
4. **素材库管理**：定期通过删除接口清理不再使用的语音素材，保持列表整洁。