# 生成配音

> `POST /tts`　|　文档 5/7｜更新于 2026-09-26｜[返回索引](https://ai.aibobos.com/openapi/index.md)

文本转语音。**同步优先**：站点语音通道直接出音频就返回 `audio_url`；不可用则转异步任务返回 `id`，用 `/task` 轮询。

**为什么 Agent 需要它**：这是「一句话出音频」的落点。设计上前置校验通道可用性——**不可用当场拒绝且不扣费**，不做假交付。

## 调用

```bash
curl -s -X POST "https://ai.aibobos.com/api/openapi/v1/tts" \
  -H "Authorization: Bearer $AIBO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "艾波开放平台已支持 OpenAI 兼容调用。", "voice_id": "", "speed": "1.0"}'
```

## 参数

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `text` | string | 是 | 要合成的文本，上限由站点配置 `tts_max_chars` 决定（当前 1000 字）。 |
| `voice_id` | string | 否 | 留空则自动取 `/voices` 的第一个音色。 |
| `speed` | string | 否 | 语速，默认 `"1.0"`。 |

## 请求体

```json
{
  "text": "艾波开放平台已支持 OpenAI 兼容调用。",
  "voice_id": "",
  "speed": "1.0"
}
```

## 响应

**同步成功**

```json
{
  "ok": 1,
  "mode": "sync",
  "audio_url": "https://ai.aibobos.com/uploads/.../xxx.mp3",
  "chars": 20,
  "cost": 1
}
```

**转异步（站点通道不可用但本地算力节点在线）**

```json
{
  "ok": 1,
  "mode": "async",
  "id": 123,
  "tip": "站点通道暂不可用，已转本地算力节点，请用 /task?id=123 轮询到 status=2",
  "cost": 1
}
```

## 注意

- **`503` 表示通道全不可用，本次不扣算力**，可直接重试或提示用户去后台配置语音模型。
- 异步模式下 `cost` 在下单时已扣；任务失败会由站点侧退回。
- 音频文件落在站点 `/uploads/`，**长期有效但会随站点清理策略变动**，Agent 若需长期留存请自行转存。

---

- 鉴权：`Authorization: Bearer <API Key>`；需要 `tts` 能力域
- 计费：见[索引页的计费表](https://ai.aibobos.com/openapi/index.md#计费口径)，失败自动退回
- 机器可读描述：[openapi.json](https://ai.aibobos.com/openapi.json)