---
name: yixo-tts
description: 调用毕力可（Yixo）语音合成 API 把文本合成为语音（维吾尔语与中文，支持实时 PCM 流式返回）。当用户需要文字转语音、批量生成配音、查询可用音色时使用本技能。
---

# Yixo 语音合成（TTS）API 技能

本技能教 AI 助手直接调用毕力可语音合成开放 API。接口为 OpenAI 兼容的 HTTP 协议。

## 何时使用

- 用户要求把一段文字转成语音 / 配音 / 朗读音频。
- 用户需要批量合成音频文件（如有 API Key，可循环调用）。
- 用户询问有哪些可用音色（维吾尔语 / 中文）。

## 接入信息

| 项目 | 值 |
| --- | --- |
| Base URL | `https://baydadam.com/v1` |
| 鉴权 | 请求头 `Authorization: Bearer <API Key>` |
| 模型 | 固定 `yixotts` |

## 合成语音：POST /v1/audio/speech

JSON 请求体：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定 `yixotts` |
| `input` | string | 是 | 待合成文本，单次上限 2000 字符 |
| `voice` | string | 是 | 音色 ID（见下方音色列表） |
| `response_format` | string | 否 | `pcm`（默认，实时流）或 `wav`（完整文件） |

两种返回格式：

- `pcm`：分块实时流，原始 PCM 数据为 **48kHz、16-bit、单声道、s16le（小端）**，收到即可边收边播，首包延迟低。
- `wav`：生成结束后一次性返回完整 WAV 文件（`audio/wav`），适合直接保存。

curl 示例：

```bash
curl https://baydadam.com/v1/audio/speech \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yixotts",
    "input": "你好，世界。",
    "voice": "zh_female_02_SSB0342",
    "response_format": "wav"
  }' \
  --output speech.wav
```

## 音色列表：GET /v1/voices

```bash
curl https://baydadam.com/v1/voices \
  -H "Authorization: Bearer <API Key>"
```

返回 `{ "default": "default", "data": [{ "id", "name", "language", "gender", "speaker_id" }] }`。

当前共 18 个预置音色（以接口实时返回为准）：

- 维吾尔语：`default`（维语默认音色）
- 中文女声：`zh_female_02_SSB0342`、`zh_female_03_SSB1555`、`zh_female_13_SSB0614`、`zh_female_18_SSB0594`、`zh_female_19_SSB0415`
- 中文男声：`zh_male_10_SSB1624`、`zh_male_12_SSB0603`、`zh_male_13_SSB0139`、`zh_male_14_SSB0073`、`zh_male_15_SSB0434`、`zh_male_16_SSB0966`、`zh_male_17_SSB0784`、`zh_male_19_SSB0623`、`zh_male_20_SSB1935`、`zh_male_22_SSB0273`、`zh_male_24_SSB0394`、`zh_male_25_SSB1020`

## 边收边播（PCM 实时流）要点

1. `response_format` 设为 `pcm`，用流式方式读取响应体（Python `requests` 用 `stream=True` + `iter_content`；浏览器/Node 用 `response.body.getReader()`）。
2. 每个分块是原始 s16le 字节：每 2 字节一个小端有符号采样，除以 32768 归一化到 [-1, 1]。
3. 浏览器播放用 Web Audio API：`new AudioContext({ sampleRate: 48000 })`，把分块转成 `Float32Array` 写入 `AudioBuffer`，按时间顺序 `source.start(at)` 排队播放。
4. 注意跨分块的奇数字节边界：缓存最后 1 个字节与下一分块拼接，避免采样错位。
5. 只想落盘就直接把分块按顺序写入 `.pcm` 文件，或改用 `response_format: "wav"` 一次拿完整文件。

完整可运行示例见同目录 `examples/tts_stream.py`（Python requests）与 `examples/tts_stream.js`（Node 18+ fetch）。

## 错误处理

| 状态码 | 含义 | 处理建议 |
| --- | --- | --- |
| 400 | 请求内容无效（文本为空、超过 2000 字符、参数错误） | 检查 `input` 与参数，截断长文本分段合成 |
| 401 | API Key 缺失或无效 | 检查 `Authorization` 头与 Key |
| 429 | 触发限流（响应带 `Retry-After` 秒数） | 按 `Retry-After` 等待后重试，勿并发猛刷 |
| 503 | 合成服务暂时不可用 | 稍后重试，连续失败请联系客服 |

错误响应体为 JSON：`{ "error": "错误描述" }`。

## 限流与额度

- 官网匿名体验页按 IP 限流（仅影响体验页，不影响正式 Key）。
- 正式 API Key 审核发放，额度按所选会员套餐（100 / 300 / 1000 音频分钟每月）计算。

## 获取 API Key

正式自助发 Key 随会员系统上线；当前在官网 `https://baydadam.com/keys` 页面提交申请（称呼、邮箱、用途说明），管理员审核后通过邮件发放（通常 1 个工作日内）。拿到 Key 前，可先用 `GET /v1/voices` 联调音色选择逻辑。