# Gemini TTS API：语音合成的音色、语气控制与音频格式

Source: https://ofox.ai/zh/docs/develop/models/gemini-tts

Google 的 Gemini 语音合成模型，通过 OpenAI 兼容的 `POST /v1/audio/speech` 调用，可用自然语言描述语气与风格。

**常用模型 ID（调用时原样复制）**

- Gemini 3.8 Flash TTS: `google/gemini-3.8-flash-tts`
- Gemini 3.8 Flash-Lite TTS: `google/gemini-3.8-flash-lite-tts` — 更低单价

全部 TTS 模型见[模型页](https://ofox.ai/zh/models?provider=google)。接口的通用参数见 [Audio Speech API](https://ofox.ai/zh/docs/api/openai/audio-speech)。

## 调用示例

**Python**

```python filename="gemini_tts.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

with client.audio.speech.with_streaming_response.create(
    model="google/gemini-3.8-flash-tts",
    voice="Kore",
    input="今天的会议改到下午三点，请大家准时参加。",
    instructions="用沉稳、清晰的语气朗读，像新闻播报。",
    response_format="wav",
) as resp:
    resp.stream_to_file("speech.wav")
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/audio/speech \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.8-flash-tts",
    "voice": "Kore",
    "input": "今天的会议改到下午三点，请大家准时参加。",
    "instructions": "用沉稳、清晰的语气朗读，像新闻播报。",
    "response_format": "wav"
  }' \
  --output speech.wav
```

## 参数取值

**要点**:voice 必填，取值为 Google 的音色名；输出格式仅支持 wav 与 pcm。

| 参数 | 说明 |
|---|---|
| `voice` | **必填**，Google 的音色名，如 `Kore`、`Puck`、`Zephyr`。完整列表见 [Gemini 官方文档 · 音色](https://ai.google.dev/gemini-api/docs/speech-generation#voices)。OpenAI 的音色名（如 `alloy`）不可用 |
| `response_format` | `wav`（默认）或 `pcm`，均为 24 kHz、16 位、单声道。`mp3`、`opus`、`aac`、`flac` 不支持 |
| `instructions` | 用自然语言描述语气、语速与风格，如「用欢快的语气」「放慢语速」 |
| `language_code` | 语言代码，如 `cmn-CN`、`en-US`，不传时根据文字自动判断 |
| `stream_format` | 传 `sse` 时以流式返回音频分片，适合边生成边播放 |

需要 mp3 时，可先获取 wav，再用 ffmpeg 等工具转换：`ffmpeg -i speech.wav speech.mp3`。

## 耗时与长文本
实测一句约 20 字的中文约 3 秒返回。约 6000 个字符的英文生成了约 9 分钟的音频，耗时约 105 秒，wav 文件约 26 MB；长文本请将客户端超时设置为 300 秒以上，或使用 `stream_format: "sse"` 流式获取。

## 常见报错
| HTTP | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 | `voice is required for speech completion` | 未传 `voice` | 传入音色名，如 `Kore` |
| 400 | `Request contains an invalid argument.` | 音色名不存在，例如传入了 `alloy` | 改用 Google 的音色名 |
| 400 | `unsupported Gemini response_format: mp3` | 格式不受支持 | 改用 `wav` 或 `pcm` |

更多报错见 [Audio Speech API](https://ofox.ai/zh/docs/api/openai/audio-speech#errors)。

## 官方文档
- [Gemini API · 语音生成](https://ai.google.dev/gemini-api/docs/speech-generation)

## 常见问题

**Gemini TTS 的 voice 填什么？**

填 Google 的音色名，如 Kore、Puck、Zephyr，完整列表见 Gemini 官方文档。voice 为必填，OpenAI 的 alloy 等音色不可用。

**Gemini TTS 能输出 mp3 吗？**

不能，仅支持 wav 与 pcm（24 kHz、16 位、单声道）。需要 mp3 时请自行转换，如 ffmpeg -i speech.wav speech.mp3。

**Gemini TTS 怎么控制语气？**

通过 instructions 参数用自然语言描述，例如「用欢快的语气朗读」「像新闻播报一样沉稳」。

**Gemini TTS 报错 voice is required？**

Gemini TTS 必须传入 voice，例如 "voice": "Kore"。