> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本转语音(TTS)

> POST /v1/audio/speech —— 把文本合成为语音

把文本合成为自然语音。

## 请求

```bash theme={null}
curl https://openp.ai/v1/audio/speech \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from OpenPAI",
    "voice": "alloy",
    "response_format": "mp3"
  }' --output speech.mp3
```

### 参数

| 字段                | 类型     |  必填 | 说明                                                                                |
| ----------------- | ------ | :-: | --------------------------------------------------------------------------------- |
| `model`           | string |  ✅  | `tts-1` / `tts-1-hd` / `gpt-4o-mini-tts`                                          |
| `input`           | string |  ✅  | 待合成文本(最长 4096 字符)                                                                 |
| `voice`           | string |  ✅  | 音色:`alloy` / `echo` / `fable` / `onyx` / `nova` / `shimmer` / `coral` / `verse` 等 |
| `response_format` | string |     | `mp3`(默认) / `opus` / `aac` / `flac` / `wav` / `pcm`                               |
| `speed`           | number |     | 0.25 - 4.0(默认 1.0)                                                                |
| `instructions`    | string |     | `gpt-4o-mini-tts` 专属,可对语气 / 风格描述                                                  |

## 响应

直接返回 **二进制音频流**,`Content-Type` 与所选 `response_format` 对应:

| response\_format | Content-Type |
| ---------------- | ------------ |
| `mp3`            | `audio/mpeg` |
| `opus`           | `audio/ogg`  |
| `aac`            | `audio/aac`  |
| `flac`           | `audio/flac` |
| `wav`            | `audio/wav`  |
| `pcm`            | `audio/pcm`  |

## Python 示例

```python theme={null}
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://openp.ai/v1")

with client.audio.speech.with_streaming_response.create(
    model="tts-1-hd",
    voice="nova",
    input="OpenPAI 让大模型接入更简单。",
) as resp:
    resp.stream_to_file("output.mp3")
```

## gpt-4o-mini-tts 进阶

新一代 TTS 支持通过 `instructions` 控制语气:

```json theme={null}
{
  "model": "gpt-4o-mini-tts",
  "voice": "coral",
  "input": "今天的会议结果非常好。",
  "instructions": "用兴奋、上扬的语气朗读,语速稍快。"
}
```

## 流式播放

合成时间可能 ≥ 1 秒,在浏览器或客户端可使用流式接收:

```python theme={null}
with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alloy",
    input="...",
    response_format="opus",
) as resp:
    for chunk in resp.iter_bytes():
        # 边收边播
        play(chunk)
```

## 计费

按 **输入字符数** 计费,与所选模型和格式无关。