# TTS 文字转语音
> 把文本合成为语音
> 6 种音色可选，4 档语速可调
> 单次输入上限 4096 字符
`POST /v1/audio/speech`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
请求体为 JSON。成功时响应体是二进制音频流，不是 JSON。
- `model` (string / 必填) — 语音合成模型。当前取值 `gpt-4o-mini-tts`。
- `input` (string / 必填) — 待朗读的文本。长度上限 4096 字符，超过返回 413。
- `voice` (string / 必填) — 朗读音色。 - `alloy` 中性、均衡 - `echo` 男声，低沉稳重 - `fable` 英式口音，偏叙述风格 - `onyx` 男声，浑厚 - `nova` 女声，明快有活力 - `shimmer` 女声，柔和
- `response_format` (string / 必填) — 输出音频封装格式，默认 `wav`。 - `wav` 未压缩 - `opus` 面向网络流媒体 - `aac` AAC 编码 - `flac` 无损压缩 - `pcm` 裸音频数据
- `speed` (number / 可选) — 朗读速率倍数，取值 0.25 至 4.0，默认 1.0。
## 响应
成功时返回二进制音频流：
| 响应头 | 值 |
|---|---|
| Content-Type | 随 `response_format` 变化，如 `audio/wav` |
| Content-Length | 音频字节数 |
失败时返回 JSON 错误体，结构为 `{ error: { code, message, type } }`。
## 音色怎么选
| 场景 | 建议音色 |
|---|---|
| 客服、助手 | `alloy` 或 `nova` |
| 有声书、旁白 | `fable` 或 `onyx` |
| 儿童内容 | `nova` 或 `shimmer` |
| 广告、宣传 | `onyx` 或 `echo` |
先用一段代表性文本把六个音色都合成一遍对比，比看文字描述准得多。
## 长文本处理
单次 4096 字符的上限决定了长文必须分段。按句子边界切分比按字数切分自然，能避免句子中间断开。
```python
import re
def split_text(text, limit=3800):
    # 先按句号、问号、叹号切，再按长度贪心合并
    sentences = re.split(r"(?<=[。！？.!?])", text)
    chunks, cur = [], ""
    for s in sentences:
        if len(cur) + len(s) > limit:
            chunks.append(cur)
            cur = s
        else:
            cur += s
    if cur:
        chunks.append(cur)
    return chunks
```
为什么用 3800 而不是 4096：中文字符在部分实现里按字节计，留 10% 余量更稳妥。
## 格式怎么选
| 格式 | 适合 |
|---|---|
| wav | 需要后期编辑，无损 |
| opus | 网络传输，体积最小 |
| flac | 归档，无损且比 wav 小 |
| pcm | 送进实时音频管线 |
| aac | 移动端播放兼容性好 |
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效 |
| 401 | authentication_error | 身份验证失败，需检查 API 密钥 |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
> **Note:** 
> 合成按输入字符计费。同样的文本合成多次会重复计费，批量场景建议把结果按内容哈希缓存起来。
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
以下语音合成模型均可通过本接口调用，实际可用范围以你的账号分组为准：
:::models audio
## 使用示例
### 基础合成
传文本、音色与输出格式，直接拿回音频二进制。默认 24kHz 采样率。
### 音质优先
`tts-1-hd` 音质更好但延迟更高，适合预生成的有声内容，不适合实时对话。
### 调整语速
`speed` 取 0.25 到 4.0，1.0 是原速。教学类内容常降到 0.9 左右，方便跟读。
### 流式合成
需要边生成边播放时用流式格式，客户端收到首块就能开始播，不必等整段合成完。
**基础合成{Basic synthesis}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/audio/speech' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "tts-1",
    "input": "欢迎使用 OAIRoute，一个端点接入多家模型。",
    "voice": "alloy",
    "response_format": "mp3"
  }'
```
**基础合成{Basic synthesis}::Python**
```
import requests
url = "https://api.oairoute.com/v1/audio/speech"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "tts-1",
    "input": "欢迎使用 OAIRoute，一个端点接入多家模型。",
    "voice": "alloy",
    "response_format": "mp3"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**基础合成{Basic synthesis}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "tts-1",
    "input": "欢迎使用 OAIRoute，一个端点接入多家模型。",
    "voice": "alloy",
    "response_format": "mp3"
  }),
});
console.log(await res.json());
```
**音质优先{Quality first}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/audio/speech' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "tts-1-hd",
    "input": "本章讲述分布式系统的一致性模型。",
    "voice": "nova",
    "response_format": "wav"
  }'
```
**音质优先{Quality first}::Python**
```
import requests
url = "https://api.oairoute.com/v1/audio/speech"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "tts-1-hd",
    "input": "本章讲述分布式系统的一致性模型。",
    "voice": "nova",
    "response_format": "wav"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**音质优先{Quality first}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "tts-1-hd",
    "input": "本章讲述分布式系统的一致性模型。",
    "voice": "nova",
    "response_format": "wav"
  }),
});
console.log(await res.json());
```
**调整语速{Adjust speed}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/audio/speech' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "tts-1",
    "input": "第一个音节请跟我读：妈、麻、马、骂。",
    "voice": "shimmer",
    "response_format": "mp3",
    "speed": 0.9
  }'
```
**调整语速{Adjust speed}::Python**
```
import requests
url = "https://api.oairoute.com/v1/audio/speech"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "tts-1",
    "input": "第一个音节请跟我读：妈、麻、马、骂。",
    "voice": "shimmer",
    "response_format": "mp3",
    "speed": 0.9
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**调整语速{Adjust speed}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "tts-1",
    "input": "第一个音节请跟我读：妈、麻、马、骂。",
    "voice": "shimmer",
    "response_format": "mp3",
    "speed": 0.9
  }),
});
console.log(await res.json());
```
**流式合成{Streaming synthesis}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/audio/speech' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "tts-1",
    "input": "这是一段较长的朗读文本，用于演示流式合成。",
    "voice": "echo",
    "response_format": "pcm"
  }'
```
**流式合成{Streaming synthesis}::Python**
```
import requests
url = "https://api.oairoute.com/v1/audio/speech"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "tts-1",
    "input": "这是一段较长的朗读文本，用于演示流式合成。",
    "voice": "echo",
    "response_format": "pcm"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**流式合成{Streaming synthesis}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "tts-1",
    "input": "这是一段较长的朗读文本，用于演示流式合成。",
    "voice": "echo",
    "response_format": "pcm"
  }),
});
console.log(await res.json());
```
**200 基础合成{Basic synthesis}**
```
HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Length: 61440
<二进制音频数据>
```
**200 音质优先{Quality first}**
```
HTTP/1.1 200 OK
Content-Type: audio/wav
Content-Length: 393216
<二进制音频数据>
```
**200 调整语速{Adjust speed}**
```
HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Length: 52224
<二进制音频数据>
```
**200 流式合成{Streaming synthesis}**
```
HTTP/1.1 200 OK
Content-Type: audio/pcm
Content-Length: 268800
<二进制音频数据>
```