<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# TTS 语音合成

> 对接 alapi.cn 文本转语音（TTS）服务，输入文本返回 base64 编码的 MP3 音频。

• **5 种音色**：女声主播 / 男声主播 / 男声说唱 / 女声四川话 / 男声低沉
• **500 字以内**：单次请求最多 500 字符（中英文均按 1 字符计）
• **MP3 格式**：上游返回 audio/mpeg 编码，前端可直接 `<audio src="data:audio/mpeg;base64,...">` 播放
• **便利字段**：返回 audio_data_url（拼好的 data URL）+ audio_size_bytes（解码后字节数）+ audio_format / audio_mime
• **典型场景**：新闻播报 / 短视频配音 / 有声书 / 语音通知 / 客服 IVR
• **不缓存**：500 字音频约 1MB，重复合成概率低，避免 Redis 内存膨胀

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `tts` |
| 接口名称 | TTS 语音合成 |
| 接口地址 | `https://v1.apizero.cn/api/tts` |
| 请求方法 | `POST` |
| 分类 | ai |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 3 req/s |
| 每日免费额度 | 30 次（已认证用户） |
| 匿名每日额度 | 10 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 10 次、QPS 1；登录用户每日 30 次、QPS 3（全部免费）。本接口不缓存，每次请求都会调用上游。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `text` | `string` | 是 | 待合成文本，1-500 字符（中英文均按 1 字符计） | `欢迎使用语音合成服务` |
| `voice_type` | `string` | 否 | 音色代码。可选：female_zhubo（女声主播） / male_zhubo（男声主播） / male_rap（男声说唱） / female_sichuan（女声四川话） / male_db（男声低沉）。默认 female_zhubo | `female_zhubo` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 10 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |
| `Content-Type` | `string` | 否 | 支持 application/x-www-form-urlencoded 或 application/json | `application/json` |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/tts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "欢迎使用语音合成服务",
  "voice_type": "female_zhubo"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `text` | `string` | 回传待合成文本 | — |
| `text_length` | `number` | 文本字符长度 | — |
| `voice_type` | `string` | 音色代码（如 female_zhubo） | — |
| `voice_name` | `string` | 音色中文名（如 女声主播） | — |
| `voice_desc` | `string` | 音色描述（适用场景介绍） | — |
| `audio` | `string` | base64 编码的 MP3 音频（不含前缀）；典型 500 字音频约 1MB | — |
| `audio_format` | `string` | 音频格式，固定 mp3 | — |
| `audio_mime` | `string` | 音频 MIME 类型，固定 audio/mpeg | — |
| `audio_size_bytes` | `number` | 音频解码后字节数（用于估算大小） | — |
| `audio_data_url` | `string` | 拼好的 data URL：data:audio/mpeg;base64,xxx，可直接 <audio src> 播放 | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "text": "欢迎使用语音合成服务",
        "text_length": 10,
        "voice_type": "female_zhubo",
        "voice_name": "女声主播",
        "voice_desc": "标准普通话女声，主播风格，适合资讯播报",
        "audio": "SUQzAwAAAAAAAAAAAAAAA...（约 17000 字符 base64）",
        "audio_format": "mp3",
        "audio_mime": "audio\/mpeg",
        "audio_size_bytes": 12750,
        "audio_data_url": "data:audio\/mpeg;base64,SUQzAwAAAAA..."
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：text 为空 / 超 500 字 / voice_type 不在支持列表 |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常 / TTS 服务暂不可用 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，对接 alapi.cn /api/tts/free
  - 支持 5 种音色：女主播 / 男主播 / 男说唱 / 女四川话 / 男低沉
  - 修复源码 BUG：voice_type 不支持时不再默默回退（明确返回 4000 + 支持列表，避免歧义）
  - 新增便利字段：audio_data_url 拼好 data URL 直接 <audio src> 可播
  - 新增 audio_size_bytes 解码后字节数 + audio_format / audio_mime 元信息
  - 新增 voice_name / voice_desc，前端可直接展示音色描述
  - 不缓存：500 字音频约 1MB base64，存 Redis 代价过高且重复概率低
  - 支持 application/json 请求体
  - 说唱音色（male_rap）响应较慢（3-6 秒），timeout 设 30 秒

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/tts`

Source: `https://apizero.cn/aidocs/tts/raw.md`
Last updated: 2026-05-11T16:14:07+08:00