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

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

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

## 何时使用

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

## 接入信息

| 项目 | 值 |
| --- | --- |
| Base URL | `https://yixoaka.com/v1` |
| 鉴权 | 请求头 `Authorization: Bearer <API Key>`（Key 以 `/keys` 页面显示为准，原样使用；自行加 `sk-` 前缀也兼容） |
| 模型 | 固定 `yixotts` |

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

JSON 请求体：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定 `yixotts` |
| `input` | string | 是 | 待合成文本，单次上限 2000 字符，更长文本请分段合成 |
| `voice` | string | 是 | 音色 ID（见下方音色列表） |
| `accent` | string | 否 | 维吾尔语口音：`kashgar`（喀什）或 `hotan`（和田）。省略为标准口音；仅支持 `supported_accents` 包含该值的音色 |
| `response_format` | string | 否 | `pcm`（默认，实时流）或 `wav`（完整文件） |

两种返回格式：

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

curl 示例：

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

合成和田口音时，先在音色列表中选择 `supported_accents` 包含 `hotan` 的音色，再传 `accent`：

```bash
curl https://yixoaka.com/v1/audio/speech \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yixotts",
    "input": "ياخشىمۇسىز",
    "voice": "ug_voicebook",
    "accent": "hotan",
    "response_format": "wav"
  }' \
  --output speech-hotan.wav
```

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

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

返回 `{ "default": "default", "data": [{ "id", "name", "language", "gender", "speaker_id", "native_language", "supported_accents" }] }`。`supported_accents` 为空数组表示标准口音；包含 `kashgar` / `hotan` 时，合成请求可传对应 `accent`。

音色持续扩充（数百个，含维吾尔语、中文及带情感演绎的音色），**一律以该接口实时返回为准**，不要硬编码音色清单。常用示例：`yixo_aoede`（维吾尔语默认音色）、`gg_mandarin_chinese_wavenet_1`（中文音色）。

## 边收边播（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）。

## 音乐生成：POST /v1/music/generations

输入歌词与风格描述生成歌曲，按首计费（失败不扣费）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `yixomusic-1.0`（完整长歌 2-4 分钟、44.1kHz 高音质 MP3，2500 token/首）。`yixomusic-2.0`（快速短歌，1000 token/首，48kHz WAV）即将上线，当前调用返回 503 model_unavailable |
| `input` | string | 是 | 歌词，支持 `[Verse]`/`[Chorus]` 等段落标签，上限 3000 字符 |
| `style` | string | 否 | 风格描述（流派、乐器、人声、BPM），上限 1000 字符 |

生成耗时约 1-2 分钟，客户端超时建议 ≥180 秒。示例：

```bash
curl https://yixoaka.com/v1/music/generations \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yixomusic-1.0",
    "input": "[Verse]\n清晨的阳光洒在窗台\n[Chorus]\n让我们一起歌唱",
    "style": "中文流行，钢琴与弦乐，温柔女声，75 BPM"
  }' \
  --output song.mp3
```

音乐端点错误码（与上方错误表同格式）：`400` 参数错误（model 不支持、歌词为空或超长）、`401` Key 无效、`403` 额度不足（按首预检）、`502` 计费服务暂不可用、`503` 生成服务暂不可用（稍后重试，连续失败请联系客服）。

## 错误处理

| 状态码 | 含义 | 处理建议 |
| --- | --- | --- |
| 400 | 请求内容无效（文本为空、超过 2000 字符、音色不存在、口音不支持、参数错误） | 检查 `input`、`accent` 与音色的 `supported_accents`，长文本请分段合成 |
| 401 | API Key 缺失或无效 | 检查 `Authorization` 头与 Key |
| 403 | 账户额度不足 | 到官网充值后再试 |
| 429 | 引擎排队满员，或触发网关频率限制（每 IP 约 120 次/分钟） | 等待数秒后指数退避重试，勿并发猛刷；批量任务控制在每秒 1-2 次 |
| 502 | 计费服务暂时不可用 | 稍后重试，连续失败请联系客服 |
| 503 | 合成服务暂时不可用 | 稍后重试，连续失败请联系客服 |

错误响应体为 OpenAI 兼容 JSON：`{ "error": { "message": "错误描述", "type": "错误类型", "code": "错误码" } }`。
例外：网关层频率限制返回的 429 可能不是 JSON 体（nginx 默认错误页），收到 429 一律退避重试即可，不要解析响应体。

## 限流与额度

- 官网体验页需微信登录（新用户送免费额度），体验页限流不影响正式 API Key。
- API 调用按字符计费（1 字符 = 1 token），额度来自账户充值套餐（20 元 20,000 token，50 元 60,000 token，100 元及以上 250,000 token/100 元）。

## 用量与余额：GET /v1/usage

自助对账，返回实时余额、累计已扣字符数、总调用次数与近 30 天按天用量：

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

返回 `{ "quota", "used_chars", "request_count", "unit": "char", "daily": [{ "date", "chars", "requests" }], "trial" }`。逐条流水用 `GET /v1/usage/records?limit=100&before=<unix秒>`（倒序，`next_before` 做翻页游标）。

## 获取 API Key

微信登录官网，累计充值满 99 元后即可在 `https://yixoaka.com/keys` 页面自助创建 API Key（首次进入会自动签发一把 default Key）。完整 Key 只在创建时显示一次，请立即妥善保存。