---
name: shengyu-voice
description: 用声屿 Shengyu（AI 语音平台）把文本变成音频：文字转语音、长文/整本书朗读、多人对话配音、播客对谈、用克隆音色配音。只要用户要「配音、朗读、生成语音、做有声书、把文章/文档/字幕变成音频、多人对话念稿、用自己的声音念」，就用这个技能。也用于管理声屿音色（列出可用音色、上传样本克隆新音色）。
version: 1.0.0
---

# 声屿语音技能（shengyu-voice）

把文本变成可交付的音频文件。核心能力由声屿的开放 API 提供，本技能的价值在于**工作流**：长文怎么切、对话怎么分配音色、几十个分段怎么拼成一条干净的音频。

## 什么时候用

- 「把这段文字/这篇文章/这份文档念出来」→ 短文本用 `tts`，长文用 `long`
- 「做一集有声书 / 播客 / 多人对话配音」→ `dialogue`
- 「用我的声音念」→ 先在声屿克隆音色（`clone` 或网页端），再用 `tts`
- 「看看有哪些音色」→ `voices`
- 用户提到声屿、Shengyu、Index-TTS，或提供了 `sk-` 开头的声屿密钥

## 前置条件（先做这一步，不要跳过）

1. **API Key**：用户在声屿「用户中心 → API 管理」生成，形如 `sk-xxxx`，通过环境变量提供：

   ```bash
   export SHENGYU_API_KEY=sk-xxxx      # macOS / Linux
   $env:SHENGYU_API_KEY='sk-xxxx'      # Windows PowerShell
   ```

2. **自检**。在开始任何合成前先跑一次，确认密钥、地址、音色都通：

   ```bash
   python scripts/shengyu.py check
   ```

   失败会给出明确原因（密钥无效 / 网络不通 / 音色为空）。**不要**在自检失败的情况下继续调用，那只会浪费用户额度。

3. 如用户是自建部署，把地址给它：`export SHENGYU_BASE_URL=https://自己的域名`（默认 `https://tts.sowa.chat`）。

## 硬性约束（违反会直接报错，别试）

| 约束 | 值 | 说明 |
| --- | --- | --- |
| 单次合成文本 | **≤ 500 字** | 超过返回 HTTP 400；长文必须走 `long` 分段 |
| 音量 | `0.0 ~ 2.0` | 参数名 `volume`，默认 1.0 |
| 语速 | **不支持** | 平台 API 目前不透传 `speed`，传了会被忽略，不要向用户承诺变速 |
| 音色可见性 | 官方音色 + **本人**克隆音色 | 用别人的克隆音色会返回 403 |
| 每日额度 | 按账号等级 | 超限返回 429，与网页端共用同一份额度 |
| 克隆素材 | 单个 5 秒 ~ 2 分钟、≤ 20MB、一次最多 10 个 | 见 `reference.md` |

## 工作流

### 1. 短文本：一次调用搞定

```bash
python scripts/shengyu.py tts --text "你好，欢迎收听。" --voice <音色名> -o out.wav
```

音色名从 `voices` 里取。**不要凭空猜音色名**——先列出来再选。

### 2. 长文：必须先分段再合并

```
读取原文 → split_text 按标点切分（≤400 字/段）→ 逐段 POST /api/v1/tts
        → 每段存成临时 WAV → 按顺序合并成一条 WAV → 交付
```

一条命令完成：

```bash
python scripts/shengyu.py long --file article.txt --voice <音色名> -o out.wav --keep-dir ./segs
```

要点：

- `--dry-run` **先跑这个**，它会打印切分结果和总字数，不消耗额度。字数估算出来后再决定是否继续。
- `--keep-dir` 会把每段单独留盘。合成中断（网络抖动、额度耗尽）后重跑同一条命令，**已完成的段会直接复用**，不会重复扣额度。做有声书时务必带上。
- 段与段之间会自动插入短暂静音；`--gap` 控制句间、`--para-gap` 控制段间。默认 0.25 / 0.7 秒。

### 3. 多人对话 / 播客

写一个脚本文本，每行 `角色: 台词`：

```
jay_klee: 今天聊聊语音合成。
narr: 好，从最基础的开始。
```

```bash
python scripts/shengyu.py dialogue --file script.txt -o dialogue.wav
```

- 行首 `#` 是注释，空行表示段落（会产生更长的停顿）。
- 角色名默认就是声屿的音色名。想让脚本可读性更好，用别名：`--map 旁白=narr --map 小雨=jay_klee`。
- 也可以直接写 `[音色名] 台词` 覆盖。

### 4. 克隆音色

```bash
python scripts/shengyu.py clone --character my_voice --label "我的声音" --files ref1.wav ref2.wav
```

参考音频要求：干净人声、无背景音乐、5 秒 ~ 2 分钟/个。**1~3 个 10 秒左右的样本效果通常最好**。克隆是异步生效的，完成后立即可用于 `tts`。

## 出问题时怎么排查

| 现象 | 原因与处理 |
| --- | --- |
| HTTP 401 | 密钥无效/过期 → 让用户重新生成，别重试 |
| HTTP 403 | 用了非本人音色 → `voices` 里确认归属 |
| HTTP 429 | 当日额度用尽 → 立即停下，告知用户剩余额度，别循环重试 |
| HTTP 502 | 声屿后端 TTS 异常 → 可以隔几秒重试一次，仍失败则报给用户 |
| HTTP 400 | 文本超 500 字或参数越界 → 改用 `long` |
| 合成出来是空的/静音 | 音色名拼错或参考音频失效 → 重新 `voices` 确认 |

**永远不要**为了"重试"而无限循环调用合成接口——额度是真金白银。失败两次就停下来报告。

## 交付习惯

- 合成完把**文件绝对路径**和**时长**告诉用户，别只说"完成了"。
- 长文合成完成后，主动报告消耗了多少字、剩余额度大概多少。
- 用户没指定音色时，`voices` 里挑 2~3 个候选让用户选，不要自己随便定一个就批量合成几十段。

## 参考文档

- `references/api.md` — 接口字段、错误码、音色筛选、克隆素材规范的完整表
- `README.md` — 把这套技能安装到 Claude Code / Cursor / DSH 等工具的位置
- `scripts/shengyu.py` — 全部逻辑都在这里，可以直接读源码确认行为