Gemini-TTS 语音合成 API文档 - 数字先锋API文档

# Gemini-3.1-Flash-TTS 语音合成 API 对接文档

> **用途**：第三方软件 / 自有应用对接「Gemini 3.1 Flash 文字转语音（TTS）」能力
> **平台**：云灵API（api.cxsee.com）
> **适用对象**：平台注册会员（需有可用令牌与余额）
> **协议**：**Gemini 原生协议** `/v1beta/models/{model}:generateContent`（同步返回，一句约 4~27 秒）
> **模型**：`gemini-3.1-flash-tts-preview`（另有 `gemini-3.8-flash-tts`）

---

## ⚠️ 三个必须先知道的点

1. **本模型不是 OpenAI 兼容接口！** 使用 `/v1/chat/completions` 或 `/v1/audio/speech` 调用会返回 **400 / 500**，必须使用下方的 **Gemini 原生端点** `/v1beta/models/{model}:generateContent`。
2. **必须指定音色（voice）**。不传 `speechConfig.voiceConfig` 会返回 **400**。支持的 30 个音色见 [第 5 节](#5-支持音色清单)。
3. **返回的是裸 PCM 音频**（`audio/l16; rate=24000; channels=1`），不是 mp3。需要 WAV/MP3 请自行加头转换（见 [第 7 节](#7-音频解码与播放)）。

---

## 1. 快速开始

### 1.1 合成一段语音（同步返回音频）

```bash
curl -X POST "https://api.cxsee.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [ { "text": "今天天气不错，欢迎使用云灵AI语音合成服务。" } ] }
    ],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {
          "prebuiltVoiceConfig": { "voiceName": "Kore" }
        }
      }
    }
  }'
```

返回（音频数据已截断）：

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "audio/l16; rate=24000; channels=1",
              "data": "AAAAAAAAAAAAAAAA...（Base64 编码的 PCM 音频）"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 96,
    "totalTokenCount": 106,
    "promptTokensDetails": [ { "modality": "TEXT", "tokenCount": 10 } ],
    "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 96 } ],
    "serviceTier": "standard"
  },
  "modelVersion": "gemini-3.1-flash-tts-preview",
  "responseId": "..."
}
```

**拿到 `data` 后**：Base64 解码 → 得到 24kHz / 16bit / 单声道 PCM → 加 44 字节 WAV 头即可播放（见第 7 节 Python/JS 示例）。

### 1.2 指定不同音色

只需改 `prebuiltVoiceConfig.voiceName`：

```json
"speechConfig": {
  "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } }
}
```

---

## 2. 鉴权方式

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 令牌获取 | 登录控制台 →「令牌」页面创建；或注册 / OAuth / 微信登录后自动生成的默认密钥 |
| 内容类型 | `Content-Type: application/json` |

> 令牌以 `sk-` 开头。未认证或令牌失效返回 `401`。

**Base URL：`https://api.cxsee.com`**

---

## 3. 接口总览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/v1beta/models/{model}:generateContent` | 语音合成（**同步**，一次性返回完整音频） |
| POST | `/v1beta/models/{model}:streamGenerateContent` | 语音合成（流式返回，加 `?alt=sse` 返回 SSE 格式） |

**可用模型名**：

| 模型名 | 说明 |
|---|---|
| `gemini-3.1-flash-tts-preview` | 主推，本文档实测基准 |
| `gemini-3.8-flash-tts` | 同一上游的更新变体，调用方式完全一致 |

---

## 4. 请求体参数（JSON）

### 4.1 `contents`（必填）

对话内容数组。TTS 场景下把**要朗读的文本**放在 `parts[].text`：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `contents[].role` | string | 是 | 固定 `"user"` |
| `contents[].parts` | array | 是 | `[ { "text": "要朗读的文本" } ]` |

> 💡 **多说话人**：在 `text` 里用 `Speaker1:` / `Speaker2:` 标注，并配合 `multiSpeakerVoiceConfig`（见 4.4）。

### 4.2 `generationConfig.responseModalities`（可选）

| 值 | 实测行为 |
|---|---|
| `["AUDIO"]` | ✅ 返回音频（推荐显式声明） |
| 不传 | ✅ **默认也会返回音频** |

> ⚠️ 传 `["TEXT"]` 返回 **400** —— 本模型是**纯语音模型**，不具备文本对话能力。

### 4.3 `generationConfig.speechConfig.voiceConfig`（**必填**）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName` | string | **是** | 预置音色名，取值见 [第 5 节](#5-支持音色清单)。**不传整个 `speechConfig` 返回 400** |
| `speechConfig.languageCode` | string | 否 | 如 `"zh-CN"`、`"en-US"`，实测可正常合成 |

### 4.4 `generationConfig.speechConfig.multiSpeakerVoiceConfig`（可选，多说话人）

```json
"speechConfig": {
  "multiSpeakerVoiceConfig": {
    "speakerVoiceConfigs": [
      { "speaker": "Speaker1", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } },
      { "speaker": "Speaker2", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } } }
    ]
  }
}
```

配合 `parts[].text`（如 `"Speaker1: 你好。Speaker2: 你好。"`）可合成对话式语音。**实测返回 200 且带音频。**

---

## 5. 支持音色清单

**实测 30 个预置音色全部可用**（官方全清单，返回 0 个不可用）：

| 分类 | 音色名（`voiceName` 取值） |
|---|---|
| 主推 / 常用 | `Kore`（女声，稳定）、`Puck`（男声，活泼）、`Charon`（男声，低沉）、`Aoede`（女声）、`Fenrir` |
| 完整清单 | `Zephyr` `Puck` `Charon` `Kore` `Fenrir` `Leda` `Orus` `Aoede` `Callirrhoe` `Autonoe` `Enceladus` `Iapetus` `Umbriel` `Algieba` `Despina` `Erinome` `Algenib` `Rasalgethi` `Laomedeia` `Achernar` `Alnilam` `Schedar` `Gacrux` `Pulcherrima` `Achird` `Zubenelgenubi` `Vindemiatrix` `Sadachbia` `Sadaltager` `Sulafat` |

> 传入不存在的音色会返回明确错误：
> `400 No matching speaker voice found for name: <你传的名字>`

---

## 6. 返回字段说明

| 字段 | 说明 |
|---|---|
| `candidates[0].content.parts[0].inlineData.mimeType` | 音频格式，实测恒为 `audio/l16; rate=24000; channels=1`（PCM 16bit 单声道 24kHz） |
| `candidates[0].content.parts[0].inlineData.data` | **Base64 编码的音频数据**（主内容） |
| `candidates[0].finishReason` | 正常为 `STOP` |
| `usageMetadata.promptTokenCount` | 输入文本 token 数 |
| `usageMetadata.candidatesTokenCount` | **输出（音频）token 数**，计费按此字段 |
| `usageMetadata.candidatesTokensDetails[].modality` | 为 `AUDIO` 表示输出是音频 |
| `modelVersion` | 实际执行的模型版本 |
| `responseId` | 本次请求唯一 ID（排查用） |

> **音频 token 与时长关系（实测）**：约 **1 秒音频 ≈ 24 tokens**。一句 5 秒语音约 120 输出 tokens。

---

## 7. 音频解码与播放

返回的 `data` 是 Base64 的**裸 PCM**（无文件头），必须自行处理：

### Python

```python
import base64, requests, wave

KEY = "<你的API令牌>"
r = requests.post(
    "https://api.cxsee.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent",
    headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
    json={
        "contents": [{"role": "user", "parts": [{"text": "你好，欢迎使用云灵AI。"}]}],
        "generationConfig": {
            "responseModalities": ["AUDIO"],
            "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}},
        },
    },
    timeout=120,
).json()

raw = base64.b64decode(r["candidates"][0]["content"]["parts"][0]["inlineData"]["data"])

# 裸 PCM -> WAV
with wave.open("output.wav", "wb") as w:
    w.setnchannels(1)      # 单声道
    w.setsampwidth(2)      # 16bit
    w.setframerate(24000)  # 24kHz
    w.writeframes(raw)
print("已保存 output.wav")
```

### Node.js（保存为 WAV）

```js
const fs = require("fs");

// 手写 44 字节 WAV 头
const header = Buffer.alloc(44);
header.write("RIFF", 0);          header.writeUInt32LE(36 + pcm.length, 4);
header.write("WAVE", 8);          header.write("fmt ", 12);
header.writeUInt32LE(16, 16);     header.writeUInt16LE(1, 20);   // PCM
header.writeUInt16LE(1, 22);      header.writeUInt32LE(24000, 24);
header.writeUInt32LE(24000 * 2, 28); header.writeUInt16LE(2, 32);
header.writeUInt16LE(16, 34);     header.write("data", 36);
header.writeUInt32LE(pcm.length, 40);
fs.writeFileSync("output.wav", Buffer.concat([header, pcm]));
```

> 想得到 MP3：本地用 `ffmpeg -i output.wav -codec:a libmp3lame out.mp3` 转即可。

---

## 8. 错误码

| HTTP | 场景 | 返回示例 |
|---|---|---|
| `400` | 未指定音色（缺 `speechConfig`） | `Request contains an invalid argument.` |
| `400` | 音色名不存在 | `No matching speaker voice found for name: NotAVoice` |
| `400` | 用 `["TEXT"]` 调本模型 | `Request contains an invalid argument.` |
| `400` | 用 `/v1/chat/completions` 或 `/v1/audio/speech` 调用 | `Request contains an invalid argument.` / `not implemented` |
| `401` | 未带 / 令牌无效 | `无效的令牌` |
| `405` | 路径缺少 `/v1beta` 前缀 | `405 Not Allowed` |
| `429` | 渠道负载饱和 / 模型级熔断 | `当前分组上游负载已饱和，请稍后再试` |

> **失败请求不扣费**（实测 400 请求 `quota=0`）。

---

## 9. 计费说明

| 项 | 单价 |
|---|---|
| 输入（文本） | **$0.50 / 1M tokens** |
| 输出（音频） | **$120.6 / 1M tokens** |

- 计费按 `usageMetadata`：`promptTokenCount`（输入）+ `candidatesTokenCount`（输出）。
- **约 1 秒音频 ≈ 24 输出 tokens** → 折算**每秒语音约 $0.0029**。
- 平台余额单位换算：`$1 = 500000 算力值（quota）`。
- **实测样例**：一句 5 秒语音（输入 13 tokens + 输出 130 tokens）→ 实扣 **$0.0157**。

> 计费与实际音频时长正相关：文本越长，生成的音频越长，输出 token 越多，费用越高。

---

## 10. 常见问题

**Q1：为什么用 `/v1/chat/completions` 报 400？**
A：本模型只支持 **Gemini 原生协议**，请改用 `/v1beta/models/{model}:generateContent`。

**Q2：为什么返回的音频不能直接播放？**
A：返回的是**裸 PCM**（`audio/l16`），需要按第 7 节加 WAV 头或用 ffmpeg 转换后才能播放。

**Q3：怎么设置语速 / 情绪？**
A：本模型通过**音色**控制风格，暂无独立 `speed` 参数。可换不同 `voiceName` 获得不同风格（如 `Puck` 活泼、`Charon` 低沉）。文本里加入「用缓慢的语气说……」等指令可能影响语气，但**不保证生效**（模型未暴露该参数）。

**Q4：支持流式吗？**
A：支持，把路径换成 `:streamGenerateContent`，加 `?alt=sse` 返回 SSE 格式（每帧含一段 Base64 音频分片，需按顺序拼接）。

**Q5：支持多语言吗？**
A：支持。中英文实测均正常（中文 `语言识别 zh 1.00`，英文合成正常），可用 `speechConfig.languageCode` 显式指定如 `zh-CN` / `en-US`。

---

## 11. 完整可运行示例（生成并保存 mp3）

```bash
# 1. 请求音频 -> 保存 base64 到文件
curl -s -X POST "https://api.cxsee.com/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents":[{"role":"user","parts":[{"text":"今天天气不错，欢迎使用云灵AI语音合成服务。"}]}],
    "generationConfig":{"responseModalities":["AUDIO"],
      "speechConfig":{"voiceConfig":{"prebuiltVoiceConfig":{"voiceName":"Kore"}}}}
  }' | python3 -c "
import sys, json, base64, wave
d = json.load(sys.stdin)
raw = base64.b64decode(d['candidates'][0]['content']['parts'][0]['inlineData']['data'])
w = wave.open('out.wav','wb'); w.setnchannels(1); w.setsampwidth(2); w.setframerate(24000)
w.writeframes(raw); w.close()
print('已保存 out.wav')
"

# 2. 转 mp3（可选）
ffmpeg -y -i out.wav -codec:a libmp3lame -b:a 128k out.mp3
```

---

*文档基于 2026-10-12 平台实测校准。*

上一篇：WorkBuddy 桌面版API接入下一篇：Gemini Embeddings接口（向量嵌入）