# 语音合成

> 通过 BigModel.io 的 POST /v1/audio/speech 把文字转成语音，从 /v1/audio/voices 选择音色，按音频秒数或按万字符计费。

网页版: https://bigmodel.io/zh-cn/docs/text-to-speech · 更新于 2026-10-18

`POST /v1/audio/speech` 与 OpenAI 语音接口一致：发送文字，返回音频文件。语音模型见[模型目录 → 音频](https://bigmodel.io/zh-cn/models?type=Audio)，部分按音频秒数计费，部分按每万字符输入计费。

## 查询音色

```bash
curl https://bigmodel.io/v1/audio/voices \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

```json
{"object": "list", "data": [{"id": "...", "name": "...", "language": "zh", "tags": ["female", "calm"]}]}
```

把音色的 `id` 作为 `voice` 传入。不传 `voice` 时使用模型默认音色。

## 生成语音

```bash [cURL]
curl https://bigmodel.io/v1/audio/speech \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "minimax-speech-2.8-turbo", "input": "欢迎使用 BigModel.io，一个 Key 调用所有模型。", "voice": "VOICE_ID"}' \
  --output speech.mp3
```

```python [Python]
import os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

with client.audio.speech.with_streaming_response.create(
    model="minimax-speech-2.8-turbo",
    voice="VOICE_ID",
    input="欢迎使用 BigModel.io，一个 Key 调用所有模型。",
) as response:
    response.stream_to_file("speech.mp3")
```

响应体就是音频文件，类型见 `Content-Type`（通常为 `audio/mpeg`），任务 ID 在 `X-Task-Id` 响应头中。

| 字段 | 说明 |
|---|---|
| `model` | 必填，语音模型 ID。 |
| `input` | 必填，最多 4000 个字符。 |
| `voice` | `/v1/audio/voices` 返回的音色 `id`。 |
| `speed` | 0.5 到 2。 |
| `emotion` | 情绪提示，仅支持的模型有效。 |

### 长文本

请求最多等待 2 分钟。若届时音频还没生成好，会返回 `202`、一个任务（`object: "audio.generation"`）和 `Location` 响应头，而不是音频。之后用 `GET /v1/audio/generations/{id}` 查询，用 `GET /v1/audio/generations/{id}/content` 下载，见[音乐、音效与音频工具](https://bigmodel.io/zh-cn/docs/audio-generation)。如需始终异步处理，把同样的请求体发到 `POST /v1/audio/generations`。

## 计费方式

按万字符计费的模型按 `input` 的字符数计费；按秒计费的模型按生成音频的时长计费。在请求体中加 `"dry_run": true` 可获得 `{"object": "quote", "estimated_cost_usd": ...}` 报价，不会生成。失败的请求不收费。扣费记录在[用量](https://bigmodel.io/usage)中。

## 验证配置

先调用 `/v1/audio/voices`，再用其中一个 ID 运行生成示例。得到可播放的 `speech.mp3` 即说明 Key 可用。

## 常见问题排查

**400 “input is required” 或 “input must be at most 4000 characters”。** 在 `input` 中传入文字，长文本请拆成多次请求。

**400 “speed must be between 0.5 and 2”。** 把语速设在这个范围内。

**404 `model_not_available`。** 该模型不对这个 Key 开放，或不是语音模型。用 `GET /v1/models` 查看。

**402 `insufficient_balance`。** 请到[充值](https://bigmodel.io/purchase)页面充值。

**502 `upstream_error`。** 语音未能生成，换个音色或文本再试。不收费。

**`/v1/audio/voices` 的 `data` 为空。** Key 所在分组没有语音模型。

## 相关文档

- [视频生成](https://bigmodel.io/zh-cn/docs/video-generation)：数字人模型用配音作为 `input_audio`。
- [音乐、音效与音频工具](https://bigmodel.io/zh-cn/docs/audio-generation)。
- [定价](https://bigmodel.io/zh-cn/pricing)：语音模型价格。