# 阿里云百炼 TTS 语音合成 完整总结

> 基于阿里云官方文档整理：[非实时语音合成](https://help.aliyun.com/zh/model-studio/non-realtime-tts-user-guide) | [CosyVoice音色列表](https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list) | [模型选型指南](https://help.aliyun.com/zh/model-studio/tts-model) | [指令控制](https://help.aliyun.com/zh/model-studio/non-realtime-tts-user-guide#nrt-instruct-h3)

---

## 一、三大模型系列对比

| 维度 | 🥇 CosyVoice V3.5 | 🥈 Qwen3-TTS | 🥉 MiniMax |
|------|-------------------|-------------|-----------|
| **合成质量** | 最高（官方首选） | 中等 | 中等偏上 |
| **系统音色数** | 80+（V3-Flash） | 有限 | 有限 |
| **声音复刻** | ✅ | ✅（仅vc模型） | ✅ |
| **声音设计** | ✅ | ✅（仅vd模型） | ❌ |
| **指令控制** | ✅ | ✅（仅instruct） | ❌ |
| **中文方言** | **17种** | 9种 | 少量 |
| **外语支持** | 9种 | 8种 | 视模型 |
| **情感控制** | 通过指令 | 通过指令 | ✅ 直接参数 |
| **语速/音调** | 通过指令 | 通过指令 | ✅ 直接参数 |
| **通信协议** | WS + HTTP | HTTP（部分WS） | 仅HTTP |
| **地域** | 仅北京 | 北京+新加坡 | 仅北京 |
| **推荐场景** | 全场景旗舰 | 轻量快速 | 需精确参数控制 |

### 模型版本详情

| 模型 | API协议 | 声音复刻 | 声音设计 | 指令控制 | 定位 |
|------|---------|---------|---------|---------|------|
| **cosyvoice-v3.5-plus** ⭐ | WS/HTTP | ✅ | ✅ | ✅ | 功能最全，效果最佳 |
| **cosyvoice-v3.5-flash** | WS/HTTP | ✅ | ✅ | ✅ | 功能全，速度更快 |
| **cosyvoice-v3-plus** | WS/HTTP | ✅ | ✅ | ❌ | 无指令控制 |
| **cosyvoice-v3-flash** | WS/HTTP | ✅ | ✅ | ✅ | 轻量快速版 |
| **cosyvoice-v2** | WS/HTTP | ✅ | ❌ | ❌ | 旧版，仅复刻 |
| **qwen3-tts-flash** | HTTP | ❌ | ❌ | ❌ | 基础版，仅系统音色 |
| **qwen3-tts-instruct-flash** | HTTP/WS | ❌ | ❌ | ✅ | 支持指令控制 |
| **qwen3-tts-vc** | HTTP/WS | ✅ | ❌ | ❌ | 专注声音复刻 |
| **qwen3-tts-vd** | HTTP/WS | ❌ | ✅ | ❌ | 专注声音设计 |
| **MiniMax/speech-2.8-hd** | HTTP | ✅ | ❌ | ❌ | 高清，声音复刻 |
| **MiniMax/speech-2.8-turbo** | HTTP | ✅ | ❌ | ❌ | 快速，声音复刻 |

---

## 二、模型选型决策树

```
需要自定义音色？
├── 是 → CosyVoice V3.5-Plus（最全能：复刻+设计+指令控制）
└── 否 → 需要情感/语速精确参数控制？
    ├── 是 → MiniMax（speed/pitch/emotion 直接参数）
    └── 否 → 需要指令控制或方言？
        ├── 是 → CosyVoice V3-Flash（80+音色+Instruct，17种方言）
        └── 否 → Qwen3-TTS-Flash（最简单便宜）
```

---

## 三、前置准备

```bash
# 1. 获取 API Key：https://help.aliyun.com/zh/model-studio/get-api-key
# 2. 设置环境变量
export DASHSCOPE_API_KEY="sk-xxxxxxxx"
```

⚠️ **注意**：非实时语音合成仅在北京地域可用（`dashscope.aliyuncs.com`），新加坡地域需使用对应端点。

---

## 四、CosyVoice 使用方法（推荐，效果最好）

### 端点

```
https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer
```

### 4.1 非流式（返回音频URL）

```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "你好，欢迎使用语音合成服务。",
      "voice": "longanyang",
      "format": "mp3",
      "sample_rate": 24000
    }
}'
```

**响应示例**：

```json
{
  "output": {
    "audio": {
      "url": "https://xxx.oss-cn-beijing.aliyuncs.com/xxx.mp3",
      "expires_at": "2026-06-15T14:00:00Z"
    }
  }
}
```

> ⚠️ 音频URL **24小时内有效**，过期后需重新调用接口。

### 4.2 流式（边生成边返回PCM）

```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-SSE: enable" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "你好，欢迎使用语音合成服务。",
      "voice": "longanyang",
      "format": "pcm",
      "sample_rate": 24000
    }
}'
```

### 4.3 指令控制（方言/情绪）

> ⚠️ 仅支持 Instruct 的音色可用，详见音色列表中的标记。

```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "叫你去买盐，你买回来一袋面，这不是弄啥嘞吗！",
      "voice": "longanhuan_v3",
      "format": "mp3",
      "sample_rate": 24000,
      "instruction": "请用河南话表达，语气要夸张搞笑。"
    }
}'
```

### CosyVoice 核心参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `model` | ✅ | `cosyvoice-v3.5-plus` / `cosyvoice-v3.5-flash` / `cosyvoice-v3-plus` / `cosyvoice-v3-flash` / `cosyvoice-v2` |
| `input.text` | ✅ | 待合成文本 |
| `input.voice` | ✅ | 音色ID，见下方音色列表 |
| `input.format` | ❌ | `wav` / `mp3` / `pcm`，默认wav |
| `input.sample_rate` | ❌ | 采样率，如 24000 |
| `input.instruction` | ❌ | 自然语言指令，≤100字符（汉字按2字符计），仅支持Instruct的音色可用 |

---

## 五、Qwen3-TTS 使用方法

### 端点

```
https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
```

### 5.1 普通非流式

```bash
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3-tts-flash",
    "input": {
        "text": "那我来给大家推荐一款T恤。",
        "voice": "Cherry",
        "language_type": "Chinese"
    }
}'
```

### 5.2 指令控制版（qwen3-tts-instruct-flash）

```bash
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3-tts-instruct-flash",
    "input": {
        "text": "欢迎来到我们的直播间，今天给大家带来超值福利！",
        "voice": "Cherry",
        "language_type": "Chinese",
        "instructions": "年轻活泼的女性声音，语速较快，带有明显的上扬语调，适合直播带货"
    }
}'
```

### 5.3 流式（SSE）

添加 Header `X-DashScope-SSE: enable` 即可，返回 Base64 编码的 PCM 音频片段。

```bash
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d '{
    "model": "qwen3-tts-flash",
    "input": {
        "text": "你好啊，我是千问",
        "voice": "Cherry",
        "language_type": "Chinese"
    }
}'
```

### Qwen-TTS 核心参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `model` | ✅ | `qwen3-tts-flash` / `qwen3-tts-instruct-flash` / `qwen3-tts-vc` / `qwen3-tts-vd` / `qwen-tts` |
| `input.text` | ✅ | 待合成文本 |
| `input.voice` | ✅ | 音色ID（见Qwen-TTS音色列表） |
| `input.language_type` | ✅ | `"Chinese"` / `"English"` 等 |
| `input.instructions` | ❌ | 声音描述指令，≤1600 Token（仅instruct模型） |

---

## 六、MiniMax 使用方法

### 端点

```
https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
```

> ⚠️ MiniMax 仅在北京地域可用，仅支持 HTTP。

### 非流式（含情感/语速/音调控制）

```bash
curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "MiniMax/speech-2.8-hd",
  "input": {
    "text": "今天天气真不错，适合出去走走。",
    "voice_setting": {
      "voice_id": "male-qn-qingse",
      "speed": 1,
      "vol": 1,
      "pitch": 0,
      "emotion": "happy"
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    }
  }
}'
```

### 流式

添加 Header `X-DashScope-SSE: enable` 即可。

### MiniMax 核心参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `model` | ✅ | `MiniMax/speech-2.8-hd` / `MiniMax/speech-2.8-turbo` / `MiniMax/speech-02-hd` / `MiniMax/speech-02-turbo` |
| `input.text` | ✅ | 待合成文本 |
| `voice_setting.voice_id` | ✅ | 音色ID |
| `voice_setting.speed` | ❌ | 语速，默认1 |
| `voice_setting.vol` | ❌ | 音量，默认1 |
| `voice_setting.pitch` | ❌ | 音调，0为基准 |
| `voice_setting.emotion` | ❌ | 情感：`happy` / `sad` / `angry` 等 |
| `audio_setting.sample_rate` | ❌ | 采样率（如 32000） |
| `audio_setting.bitrate` | ❌ | 比特率（如 128000） |
| `audio_setting.format` | ❌ | `mp3` / `wav` |
| `audio_setting.channel` | ❌ | 声道数，默认1 |

---

## 七、CosyVoice V3-Flash 音色速查表

### 🌟 标杆音色（支持 Instruct 指令控制）

| voice参数 | 名称 | 特质 | 语言 |
|-----------|------|------|------|
| `longanyang` | 龙安洋 | 20-30岁 阳光大男孩 | 普通话+英文 |
| `longanhuan_v3` | 龙安欢V3 | 20-30岁 欢脱元气女 | 普通话+英文+8种方言 |
| `longhuhu_v3` | 龙呼呼 | 6-10岁 天真烂漫女童 | 普通话+英文 |

### 👶 儿童/故事机场景

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longpaopao_v3` | 龙泡泡 | 6-15岁 飞天泡泡音 |
| `longjielidou_v3` | 龙杰力豆 | 10岁 阳光顽皮男 |
| `longxian_v3` | 龙仙 | 12岁 豪放可爱女 |
| `longling_v3` | 龙铃 | 10岁 稚气呆板女 |
| `longshanshan_v3` | 龙闪闪 | 6-15岁 戏剧化童声 |
| `longniuniu_v3` | 龙牛牛 | 6-15岁 阳光男童声 |

### 🗣️ 方言音色

| voice参数 | 方言 | 特质 |
|-----------|------|------|
| `longjiaxin_v3` | 粤语 | 30-35岁 优雅粤语女 |
| `longjiayi_v3` | 粤语 | 25-30岁 知性粤语女 |
| `longanyue_v3` | 粤语 | 25-35岁 欢脱粤语男 |
| `longlaotie_v3` | 东北话 | 25-30岁 东北直率男 |
| `longshange_v3` | 陕西话 | 25-35岁 原味陕北男 |
| `longanmin_v3` | 闽南话 | 18-25岁 清纯萝莉女 |

### 📖 有声书场景

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longmiao_v3` | 龙妙 | 25-30岁 抑扬顿挫女 |
| `longsanshu_v3` | 龙三叔 | 25-45岁 沉稳质感男 |
| `longyuan_v3` | 龙媛 | 35-40岁 温暖治愈女 |
| `longyue_v3` | 龙悦 | 30-35岁 温暖磁性女 |
| `longxiu_v3` | 龙修 | 25-35岁 博才说书男 |
| `longnan_v3` | 龙楠 | 25-30岁 睿智青年男 |
| `longwanjun_v3` | 龙婉君 | 20-30岁 细腻柔声女 |
| `longyichen_v3` | 龙逸尘 | 20-30岁 洒脱活力男 |
| `longlaobo_v3` | 龙老伯 | 60岁以上 沧桑岁月爷 |
| `longlaoyi_v3` | 龙老姨 | 60岁以上 烟火从容阿姨 |

### 📢 新闻播报

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `loongbella_v3` | Bella3.0 | 25-30岁 精准干练女 |
| `longshuo_v3` | 龙硕 | 25-30岁 博才干练男 |
| `longshu_v3` | 龙书 | 20-25岁 沉稳青年男 |

### 🛒 直播带货

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longanran_v3` | 龙安燃 | 30-40岁 活泼质感女 |
| `longanxuan_v3` | 龙安宣 | 30-40岁 经典直播女 |

### 🎬 短视频配音

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longjiqi_v3` | 龙机器 | 20-30岁 呆萌机器人 |
| `longhouge_v3` | 龙猴哥 | 20-25岁 经典猴哥 |
| `longdaiyu_v3` | 龙黛玉 | 15-25岁 娇率才女音 |

### 📞 客服/语音助手

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longyingling_v3` | 龙应聆 | 25-30岁 温和共情女 |
| `longyingjing_v3` | 龙应静 | 25-35岁 低调冷静女 |
| `longyingtao_v3` | 龙应桃 | 25-30岁 温柔淡定女 |
| `longyingxiao_v3` | 龙应笑 | 20-25岁 清甜推销女 |
| `longyingxun_v3` | 龙应询 | 20-25岁 年轻青涩男 |
| `longxiaochun_v3` | 龙小淳 | 25-30岁 知性积极女 |
| `longxiaoxia_v3` | 龙小夏 | 25-30岁 沉稳权威女 |
| `longanyun_v3` | 龙安昀 | 30-35岁 居家暖男 |

### 🎭 社交陪伴

| voice参数 | 名称 | 特质 |
|-----------|------|------|
| `longhua_v3` | 龙华 | 20-25岁 元气甜美女 |
| `longcheng_v3` | 龙橙 | 20-25岁 智慧青年男 |
| `longze_v3` | 龙泽 | 25-30岁 温暖元气男 |
| `longzhe_v3` | 龙哲 | 25-30岁 呆板大暖男 |
| `longyan_v3` | 龙颜 | 30-35岁 温暖春风女 |
| `longxing_v3` | 龙星 | 20-25岁 温婉邻家女 |
| `longtian_v3` | 龙天 | 30-35岁 磁性理智男 |
| `longwan_v3` | 龙婉 | 20-30岁 细腻柔声女 |
| `longqiang_v3` | 龙嫱 | 30-35岁 浪漫风情女 |
| `longfeifei_v3` | 龙菲菲 | 20-25岁 甜美娇气女 |
| `longhao_v3` | 龙浩 | 30-35岁 多情忧郁男 |
| `longanrou_v3` | 龙安柔 | 20-35岁 温柔闺蜜女 |
| `longhan_v3` | 龙寒 | 30-35岁 温暖痴情男 |

### 🌍 出海营销（外语原生）

**美式英文**：`loongabby_v3`, `loongandy_v3`, `loongannie_v3`, `loongava_v3`, `loongbeth_v3`, `loongbetty_v3`, `loongcally_v3`, `loongcindy_v3`, `loongdavid_v3`, `loongdonna_v3`

**英式英文**：`loongemily_v3`, `loongeric_v3`, `loongluna_v3`, `loongluca_v3`

**日语**：`loongriko_v3`（二次元霓虹女）, `loongtomoka_v3`, `loongtomoya_v3`, `loongyuuna_v3`, `loongyuuma_v3`

**韩语**：`loongkyong_v3`, `loongjihun_v3`

**印尼语**：`loongindah_v3`

---

## 八、场景推荐速查表

| 场景 | 推荐音色 | voice参数 | 模型 |
|------|---------|-----------|------|
| **通用男声** | 龙安洋（阳光大男孩） | `longanyang` | cosyvoice-v3-flash |
| **通用女声** | 龙安欢（元气女） | `longanhuan_v3` | cosyvoice-v3-flash |
| **儿童故事** | 龙呼呼（天真女童） | `longhuhu_v3` | cosyvoice-v3-flash |
| **有声书男** | 龙三叔（沉稳质感） | `longsanshu_v3` | cosyvoice-v3-flash |
| **有声书女** | 龙媛（温暖治愈） | `longyuan_v3` | cosyvoice-v3-flash |
| **直播带货** | 龙安燃（活泼质感女） | `longanran_v3` | cosyvoice-v3-flash |
| **新闻播报** | Bella3.0（精准干练女） | `loongbella_v3` | cosyvoice-v3-flash |
| **粤语** | 龙嘉欣（优雅粤语女） | `longjiaxin_v3` | cosyvoice-v3-flash |
| **东北话** | 龙老铁（东北直率男） | `longlaotie_v3` | cosyvoice-v3-flash |
| **陕西话** | 龙陕哥（原味陕北男） | `longshange_v3` | cosyvoice-v3-flash |
| **英语美式** | loongabby（美式女） | `loongabby_v3` | cosyvoice-v3-flash |
| **英语英式** | loongemily（英式女） | `loongemily_v3` | cosyvoice-v3-flash |
| **日语** | Riko（二次元霓虹女） | `loongriko_v3` | cosyvoice-v3-flash |
| **客服** | 龙应聆（温和共情女） | `longyingling_v3` | cosyvoice-v3-flash |
| **电话销售** | 龙应笑（清甜推销女） | `longyingxiao_v3` | cosyvoice-v3-flash |
| **语音助手** | 龙小淳（知性积极女） | `longxiaochun_v3` | cosyvoice-v3-flash |

---

## 九、常见问题

**Q：音频文件链接的有效期是多久？**
A：音频文件链接在生成后 **24 小时** 内有效。链接过期后，重新调用接口即可获取新链接。

**Q：流式和非流式如何选择？**
A：非实时场景（有声书、配音制作）用非流式；需要边生成边播放用流式（需加 `X-DashScope-SSE: enable` Header）。

**Q：如何切换音色？**
A：修改 `input.voice` 参数即可，需使用模型支持范围内的音色 ID。

**Q：北京和新加坡地域有什么区别？**
A：北京地域支持 CosyVoice + Qwen-TTS + MiniMax 全系列；新加坡地域仅支持 Qwen-TTS 部分模型，需使用新加坡 API Key。

---

## 十、指令控制（Instruct Control）详细指南

> 指令控制允许通过**自然语言描述**直接控制合成语音的音调、语速、情感和音色特点，无需调整复杂的音频参数。

---

### 10.1 CosyVoice 指令控制

#### 支持模型与限定条件

| 模型 | 系统音色 | 声音复刻/设计音色 |
|------|----------|-------------------|
| **cosyvoice-v3.5-plus / v3.5-flash** | 不支持系统音色 | ✅ 可输入任意指令 |
| **cosyvoice-v3-plus** | ⚠️ 指令须用固定格式（见音色列表） | ❌ 不支持指令控制 |
| **cosyvoice-v3-flash** | ⚠️ 指令须用固定格式（见音色列表） | ✅ 可输入任意指令 |

> ⚠️ 对于 v3-plus 和 v3-flash 的系统音色，指令内容必须严格遵循官方音色列表中规定的固定格式，不能随意编写。

#### 系统音色指令固定格式

对于 **cosyvoice-v3-plus** 和 **cosyvoice-v3-flash** 的系统音色（如 `longanyang`、`longanhuan_v3` 等），`instruction` 必须使用以下严格格式：

```
设置情感：{emotion}。
```

**格式要求**：
- 必须使用**中文**
- 严格按 `设置情感：{emotion}。` 格式填写
- 包括标点符号（冒号、句号）不可遗漏
- **结尾必须有句号**

**支持的情感值（7种）**：

| 情感值 | 中文含义 | 适用场景 |
|--------|---------|---------|
| `neutral` | 中性 | 普通叙述、信息播报 |
| `happy` | 开心 | 祝福、庆祝、积极内容 |
| `sad` | 悲伤 | 伤感故事、悼念内容 |
| `angry` | 愤怒 | 激烈辩论、争吵场景 |
| `fearful` | 恐惧 | 悬疑故事、惊悚内容 |
| `surprised` | 惊讶 | 意外发现、惊叹内容 |
| `disgusted` | 厌恶 | 嫌弃、反感表达 |

**正确示例**：
```bash
# ✅ 正确格式（v3-flash + 系统音色）
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "我家的后面有一个很大的花园。",
      "voice": "longanyang",
      "format": "wav",
      "sample_rate": 24000,
      "instruction": "设置情感：happy。"
    }
}'

# ✅ 正确格式
"instruction": "设置情感：sad。"
"instruction": "设置情感：surprised。"
"instruction": "设置情感：neutral。"
```

**错误示例**：
```bash
# ❌ 遗漏句号
"instruction": "设置情感：happy"

# ❌ 英文描述（系统音色不支持）
"instruction": "Please use a happy tone."

# ❌ 随意格式（系统音色不支持）
"instruction": "用开心的语气说"

# ❌ 多内容拼接
"instruction": "设置情感：happy。语速快一点。"
```

> 💡 **提示**：如果需要灵活的指令控制（任意自然语言描述），请使用 **cosyvoice-v3.5-plus / v3.5-flash** + **声音复刻/设计音色**，此时 `instruction` 不受此格式限制。

#### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `instruction` | string | 自然语言指令，控制语音表现力 |

#### 支持语言

| 模型 | 声音复刻/设计音色 | 系统音色 |
|------|------------------|----------|
| cosyvoice-v3.5-plus/flash | 中、英、法、德、日、韩、俄、葡、泰、印尼、越南语 | 无系统音色 |
| cosyvoice-v3-plus | 中、英、法、德、日、韩、俄语 | 指令用固定格式（中文为主） |
| cosyvoice-v3-flash | 中、英、法、德、日、韩、俄语 | 仅中文 |

#### 长度限制

- 不超过 **100 字符**
- 汉字（含简体、繁体、日文汉字、韩文汉字）按 **2 个字符** 计算
- 其他字符（标点、字母、数字、假名、谚文等）按 **1 个字符** 计算

#### 示例代码

**方言控制示例**：
```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "我家的后面有一个很大的花园。",
      "voice": "longanyang",
      "format": "wav",
      "sample_rate": 24000,
      "instruction": "请用河南话表达。"
    }
}'
```

**情绪/风格控制示例**：
```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3.5-flash",
    "input": {
      "text": "欢迎来到我们的直播间，今天给大家带来超值福利！",
      "voice": "<复刻音色ID>",
      "format": "mp3",
      "sample_rate": 24000,
      "instruction": "语速偏快，语调上扬，充满激情和感染力，适合直播带货"
    }
}'
```

---

### 10.2 Qwen-TTS 指令控制

#### 支持模型

- **仅** `qwen3-tts-instruct-flash` 系列（普通版 `qwen3-tts-flash` 不支持）
  - `qwen3-tts-instruct-flash`（稳定版）
  - `qwen3-tts-instruct-flash-2026-01-26`（快照版）

#### 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `instructions` | string | ❌ | 自然语言声音描述 |
| `optimize_instructions` | boolean | ❌ | 是否自动优化指令，默认 `false` |

#### 支持语言

- 仅支持**中文**和**英文**描述

#### 长度限制

- 不超过 **1,600 Token**（基于 tokenizer 计算，非字符数）

#### 适用场景

- 有声书和广播剧配音
- 广告和宣传片配音
- 游戏角色和动画配音
- 情感化的智能语音助手
- 纪录片和新闻播报

#### 示例代码

```bash
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3-tts-instruct-flash",
    "input": {
        "text": "你好，这是指令控制示例。",
        "voice": "Cherry",
        "language_type": "Chinese",
        "instructions": "沉稳的中年男性，语速缓慢，音色低沉有磁性",
        "optimize_instructions": true
    }
}'
```

---

### 10.3 编写高质量声音描述的指南（Qwen-TTS）

#### 五大核心原则

| 原则 | 说明 | 反例 |
|------|------|------|
| **具体而非模糊** | 使用"低沉"、"清脆"、"语速偏快"等描绘性词语 | ❌ "好听"、"普通" |
| **多维而非单一** | 同时描述性别、年龄、情感、用途等多个维度 | ❌ 只说"女声" |
| **客观而非主观** | 聚焦声音的物理和感知特征 | ❌ "我最喜欢的声音" |
| **原创而非模仿** | 描述特质，不要求模仿特定人物 | ❌ "像周杰伦的声音" |
| **简洁而非冗余** | 每个词语都有明确作用 | ❌ 重复同义词 |

#### 描述维度参考表

| 维度 | 可选项 / 示例 |
|------|-------------|
| **性别** | 男性、女性、中性 |
| **年龄** | 儿童（5-12岁）、青少年（13-18岁）、青年（19-35岁）、中年（36-55岁）、老年（55岁以上） |
| **音调** | 高音、中音、低音、偏高、偏低 |
| **语速** | 快速、中速、缓慢、偏快、偏慢 |
| **情感** | 开朗、沉稳、温柔、严肃、活泼、冷静、治愈 |
| **特点** | 有磁性、清脆、沙哑、圆润、甜美、浑厚、有力 |
| **用途** | 新闻播报、广告配音、有声书、动画角色、语音助手、纪录片解说 |

#### 优秀指令示例

| 场景 | 指令内容 |
|------|---------|
| **标准播音** | "吐字清晰精准，字正腔圆" |
| **时尚带货** | "年轻活泼的女性声音，语速较快，带有明显的上扬语调，适合介绍时尚产品" |
| **新闻解说** | "沉稳的中年男性，语速缓慢，音色低沉有磁性，适合朗读新闻或纪录片解说" |
| **有声书** | "温柔知性的女性，30岁左右，语调平和，适合有声书朗读" |
| **动画角色** | "可爱的儿童声音，大约8岁女孩，说话略带稚气，适合动画角色配音" |

---

### 10.4 CosyVoice vs Qwen-TTS 指令控制对比

| 维度 | CosyVoice | Qwen-TTS |
|------|-----------|----------|
| **参数名** | `instruction` | `instructions` |
| **长度限制** | 100 字符（汉字×2） | 1,600 Token |
| **支持语言** | 中/英/法/德/日/韩/俄等 | 仅中/英文 |
| **系统音色** | ⚠️ 仅固定格式（v3-plus/flash） | ❌ 不支持 |
| **复刻/设计音色** | ✅ 任意指令 | ❌ 不支持指令控制 |
| **方言** | ✅ 通过指令切换 | ❌ 需选方言音色 |
| **自动优化** | ❌ | ✅ `optimize_instructions` |

---

### 10.5 指令控制最佳实践

1. **选对模型**：CosyVoice 音色多+方言强，Qwen-TTS 指令长度更宽松
2. **v3-plus/flash 系统音色注意**：指令必须用固定格式（见音色列表），不可随意编写
3. **v3.5-plus/flash 最灵活**：配合声音复刻/设计音色可实现任意指令控制
4. **方言两种方式**：CosyVoice 可直接用方言音色，也可用 `instruction` 指定方言
5. **指令要具体**：避免模糊描述，从性别、年龄、音调、语速、情感、用途多维度描述
6. **开启优化**：Qwen-TTS 建议开启 `optimize_instructions: true` 提升效果
7. **地域注意**：指令控制仅北京地域可用，新加坡地域不支持

---

## 十一、最终推荐

> **追求效果** → `cosyvoice-v3-flash` + `longanyang`/`longanhuan_v3`，80+音色随便选
>
> **需要指令控制情绪/方言** → `cosyvoice-v3-flash` + `instruction` 参数（仅限标杆音色）
>
> **需要精确控制语速/音调/情感** → `MiniMax/speech-2.8-hd` + `voice_setting` 参数
>
> **最简单快速** → `qwen3-tts-flash` + 系统音色
>
> **极致效果/自定义音色** → `cosyvoice-v3.5-plus`（声音复刻 + 声音设计 + 指令控制）

---

## 十二、tonggan 项目 TTS 音色推荐

> 基于 tonggan 产品设计文档（儿童注意力训练 App，5-12 岁，AI 教练角色），从 CosyVoice 80+ 音色中精选适配方案。

---

### 12.1 tonggan 语音需求回顾

| 需求维度 | 产品要求 | 对音色的要求 |
|---------|---------|------------|
| **角色定位** | AI 注意力训练教练 | 亲切、可信赖、像大姐姐/大哥哥 |
| **目标用户** | 5-12 岁儿童 | 声音不能机械、不能冷淡、不能可怕 |
| **性别偏好** | 女声优先 | 音调偏高、温暖柔和 |
| **语速要求** | rate=0.9（偏慢） | 清哳可辨，孩子能跟上 |
| **情感要求** | 鼓励为主，不否定 | 开心、温柔、惊喜（避免愤怒/恐惧/厌恶） |
| **使用场景** | 指令播报、实时鼓励、休息引导、故事朗读 | 不同场景可用不同音色 |
| **丰富度要求** | 鼓励语 8 种变化，语调随机化 | 需要支持 Instruct 控制情绪变化 |

---

### 12.2 🥇 首选方案：双音色组合（推荐）

| 角色 | 音色 | voice参数 | 特质 | 支持 Instruct |
|------|------|-----------|------|:--:|
| **主教练（女声）** | 龙安欢 V3 | `longanhuan_v3` | 20-30岁 欢脱元气女 | ✅ |
| **辅助音色（男声）** | 龙安洋 | `longanyang` | 20-30岁 阳光大男孩 | ✅ |

**为什么选这两个**：
- ✅ 都是**标杆音色**，合成质量最高
- ✅ 都支持 **Instruct 指令控制**，可以通过 `instruction` 动态切换情绪
- ✅ 声音亲切阳光，**不机械不冰冷**，适合儿童
- ✅ 一男一女组合，可以区分不同场景避免单调
- ✅ `longanhuan_v3` 额外支持 8 种方言，未来可扩展趣味方言模式

---

### 12.3 📋 场景音色分配表

| 场景 | 推荐音色 | voice参数 | 情感指令 | 说明 |
|------|---------|-----------|---------|------|
| **指令播报**（听指令做动作） | 龙安欢 V3 | `longanhuan_v3` | `设置情感：happy。` | 元气女声，孩子喜欢听 |
| **正向鼓励**（"太棒了！"） | 龙安欢 V3 | `longanhuan_v3` | `设置情感：surprised。` | 惊喜上扬语调 |
| **温柔提醒**（"再试一次～"） | 龙安欢 V3 | `longanhuan_v3` | `设置情感：neutral。` | 平静温和不施压 |
| **静坐挑战** | 龙安洋 | `longanyang` | `设置情感：neutral。` | 沉稳男声帮助安定 |
| **舒尔特方格** | 龙安洋 | `longanyang` | `设置情感：happy。` | 中性活力播报 |
| **休息引导**（"喝口水吧～"） | 龙安欢 V3 | `longanhuan_v3` | `设置情感：neutral。` | 温柔关心 |
| **结算庆祝** | 龙安欢 V3 | `longanhuan_v3` | `设置情感：happy。` | 热烈庆祝 |
| **故事朗读**（复述故事） | 龙媛 | `longyuan_v3` | ❌ 不支持 | 35-40岁 温暖治愈女，讲故事最合适 |

---

### 12.4 🎭 进阶方案：多角色音色矩阵

当产品打磨到一定阶段，可以为不同场景配置更多音色增加趣味性：

#### 日常训练主教练

| 优先级 | 音色 | voice参数 | 特质 | 适用 |
|:--:|------|-----------|------|------|
| ⭐ | 龙安欢 V3 | `longanhuan_v3` | 欢脱元气女 | 主力教练（支持Instruct） |
| ⭐ | 龙安洋 | `longanyang` | 阳光大男孩 | 辅助教练（支持Instruct） |
| ② | 龙星 | `longxing_v3` | 温婉邻家女 | 柔和版女教练 |
| ② | 龙泽 | `longze_v3` | 温暖元气男 | 活力版男教练 |
| ③ | 龙华 | `longhua_v3` | 元气甜美女 | 更甜美风格 |
| ③ | 龙安柔 | `longanrou_v3` | 温柔闺蜜女 | 更亲密风格 |

#### 故事朗读（复述故事）

| 优先级 | 音色 | voice参数 | 特质 |
|:--:|------|-----------|------|
| ⭐ | 龙媛 | `longyuan_v3` | 35-40岁 温暖治愈女 |
| ⭐ | 龙三叔 | `longsanshu_v3` | 25-45岁 沉稳质感男 |
| ② | 龙悦 | `longyue_v3` | 30-35岁 温暖磁性女 |
| ② | 龙妙 | `longmiao_v3` | 25-30岁 抑扬顿挫女 |
| ③ | 龙老伯 | `longlaobo_v3` | 60岁以上 沧桑岁月爷（爷爷讲故事） |
| ③ | 龙老姨 | `longlaoyi_v3` | 60岁以上 烟火从容阿姨（奶奶讲故事） |

#### 趣味角色（游戏化元素）

| 音色 | voice参数 | 特质 | 使用场景 |
|------|-----------|------|---------|
| 龙呼呼 | `longhuhu_v3` | 6-10岁 天真烂漫女童 ⭐ | 同龄小伙伴角色，训练伙伴 |
| 龙机器 | `longjiqi_v3` | 呆萌机器人 | 机器人裁判/计时器 |
| 龙猴哥 | `longhouge_v3` | 经典猴哥 | 中国风趣味角色 |
| 龙杰力豆 | `longjielidou_v3` | 10岁 阳光顽皮男 | 男孩训练伙伴 |
| 龙仙 | `longxian_v3` | 12岁 豪放可爱女 | 女孩训练伙伴 |

> ⚠️ 儿童音色（龙呼呼等）也支持 Instruct，可以用 `设置情感：happy。` 让它更生动。

---

### 12.5 🎯 首版最小方案（P0，推荐立即采用）

**只选 3 个音色，覆盖全部场景**：

| # | 音色 | voice参数 | 覆盖场景 | 选择理由 |
|:--:|------|-----------|---------|---------|
| 1 | **龙安欢 V3** | `longanhuan_v3` | 指令播报、正向鼓励、休息引导、结算庆祝 | 女声首选，支持Instruct切换情绪 |
| 2 | **龙安洋** | `longanyang` | 静坐挑战、舒尔特方格 | 男声区分场景，同样支持Instruct |
| 3 | **龙媛** | `longyuan_v3` | 故事朗读（复述故事） | 专业讲故事音色，温暖治愈 |

**使用模型**：`cosyvoice-v3-flash`（80+音色全支持，有 Instruct）

**Instruct 情感策略**：只用 3 种正向情感

| 情感 | 指令 | 何时使用 |
|------|------|---------|
| `happy` | `设置情感：happy。` | 指令播报、积极鼓励、结算庆祝 |
| `neutral` | `设置情感：neutral。` | 静坐引导、温柔提醒、休息提示 |
| `surprised` | `设置情感：surprised。` | 惊喜鼓励（孩子连续做对时） |

> ❌ **不使用** `sad`、`angry`、`fearful`、`disgusted` —— 与 tonggan"不打击孩子"的产品原则一致。

---

### 12.6 🔧 TTS 调用封装建议

```typescript
// tonggan TTS 服务封装（伪代码）
const TTS_SERVICE = {
  model: 'cosyvoice-v3-flash',
  voices: {
    coach: 'longanhuan_v3',      // 主教练
    assistant: 'longanyang',     // 辅助教练
    storyteller: 'longyuan_v3',  // 讲故事
  },
  
  // 情感映射
  emotions: {
    encourage: '设置情感：happy。',
    calm: '设置情感：neutral。',
    surprise: '设置情感：surprised。',
  },
  
  // 场景调用
  async speakInstruction(text: string) {
    return tts(text, this.voices.coach, this.emotions.encourage);
  },
  async speakPraise(text: string) {
    // 随机选择情感增加变化
    const emo = Math.random() > 0.7 ? this.emotions.surprise : this.emotions.encourage;
    return tts(text, this.voices.coach, emo);
  },
  async speakCalm(text: string) {
    return tts(text, this.voices.assistant, this.emotions.calm);
  },
  async tellStory(text: string) {
    return tts(text, this.voices.storyteller); // 无Instruct
  },
};
```

---

### 12.7 📊 方案对比

| 方案 | 音色数 | 开发量 | 体验丰富度 | 推荐阶段 |
|------|:--:|:--:|:--:|:--:|
| **最小方案（3音色）** | 3 | 低 | ⭐⭐⭐ | 🟢 **首版 P0** |
| 双音色+情感（2音色+Instruct） | 2+情感 | 中 | ⭐⭐⭐⭐ | 🟡 P1 优化 |
| 多角色矩阵（8+音色） | 8+ | 高 | ⭐⭐⭐⭐⭐ | 🔵 P2 丰富期 |

---

> 📅 整理日期：2026-06-14
> 📄 数据来源：阿里云百炼官方帮助文档

---

## 十三、声音设计（Voice Design）使用指南

> 文档来源：[声音设计用户指南](https://help.aliyun.com/zh/model-studio/voice-design-user-guide)

### 13.1 概述

声音设计（Voice Design）**无需音频样本**，仅通过自然语言描述即可生成专属定制音色。适用于需要精确控制音色特征（音调、语速、年龄、情感）但不想被系统音色限制的场景。

### 13.2 支持模型

| 模型 | 描述长度上限 | 地域 |
|------|:--:|------|
| `cosyvoice-v3.5-plus` | 500字符 | 仅北京 |
| `cosyvoice-v3.5-flash` | 500字符 | 仅北京 |
| `cosyvoice-v3-plus` | 500字符 | 仅北京 |
| `cosyvoice-v3-flash` | 500字符 | 仅北京 |
| `qwen3-tts-vd` 系列 | 2048字符 | 北京+新加坡 |

### 13.3 计费

| 模型 | 创建费用 | 配额 |
|------|:--:|:--:|
| **CosyVoice** | **免费** 🆓 | 每账号最多1000个音色 |
| Qwen-TTS | 0.2元/次 | 90天内10次免费 |

> ⚠️ 音色若1年内未被使用，系统自动清理。

### 13.4 API 调用流程

**步骤1：创建音色**

```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
      "action": "create_voice",
      "target_model": "cosyvoice-v3-flash",
      "voice_prompt": "25岁温柔大姐姐，中等偏沉音调、绝不尖锐刺耳，语速适中偏慢、吐字清晰，语气温暖亲切",
      "preview_text": "太棒了，你做得真好！",
      "prefix": "myvoice"
    },
    "parameters": {
      "sample_rate": 24000,
      "response_format": "mp3"
    }
}'
```

**返回**：
```json
{
  "output": {
    "voice_id": "cosyvoice-v3-flash-vd-myvoice-xxxxxxxx",
    "preview_audio": {
      "data": "<base64编码音频>",
      "sample_rate": 24000,
      "response_format": "wav"
    }
  }
}
```

**步骤2：使用定制音色合成**

```bash
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "今天我们来做一个新游戏！",
      "voice": "cosyvoice-v3-flash-vd-myvoice-xxxxxxxx",
      "format": "mp3"
    }
}'
```

### 13.5 关键参数说明

| 参数 | 必填 | 说明 |
|------|:--:|------|
| `model` | ✅ | 固定为 `voice-enrollment` |
| `action` | ✅ | 固定为 `create_voice` |
| `target_model` | ✅ | 目标合成模型，如 `cosyvoice-v3-flash` |
| `voice_prompt` | ✅ | 声音描述，≤500字符，仅中英文 |
| `preview_text` | ❌ | 预览音频朗读文本 |
| `prefix` | ❌ | 音色名前缀，≤10字符，仅英文字母+数字 |

### 13.6 声音描述编写指南

**五大原则**：
| 原则 | 说明 |
|------|------|
| 具体不模糊 | "低沉""语速偏快" 而非 "好听" |
| 多维度覆盖 | 性别、年龄、音调、语速、情感、特点、用途 |
| 客观描述 | 聚焦物理/感知特征，不模仿特定人物 |
| 简洁不冗余 | 每个词都有明确作用 |

**描述维度参考**：

| 维度 | 可选值 |
|------|------|
| 性别 | 男性、女性、中性 |
| 年龄 | 儿童(5-12)、青年(19-35)、中年(36-55) |
| 音调 | 高音、中音、低音、偏高、偏低 |
| 语速 | 快速、中速、缓慢、偏快、偏慢 |
| 情感 | 开朗、沉稳、温柔、严肃、活泼、冷静、治愈 |
| 特点 | 有磁性、清脆、沙哑、圆润、甜美、浑厚、圆润 |
| 用途 | 新闻播报、广告配音、有声书、动画角色、纪录片解说 |

**高质量描述示例**：
- "沉稳的中年男性，语速缓慢，音色低沉有磁性，适合朗读新闻或纪录片解说。"
- "年轻活泼的女性声音，语速较快，带有明显的上扬语调，适合介绍时尚产品。"

### 13.7 与系统音色对比

| 维度 | 系统音色 | 声音设计 |
|------|:--:|:--:|
| 音色数量 | 80+（固定） | 无限（按需创建） |
| 音调控制 | 看运气 | ✅ 精确描述 |
| 语速控制 | ❌ 不支持 | ✅ 描述控制 |
| 情感控制 | ❌ (需Instruct权限) | ✅ 描述控制 |
| 创建成本 | 零 | **免费** |
| 适合场景 | 通用合成 | 需定制化声音 |

### 13.8 tonggan 项目使用建议

**推荐方案**：声音设计代替系统音色，因为：

1. **精确控制音色**：可以指定"中等偏沉音调、绝不尖锐"，彻底解决儿童项目的声音尖锐问题
2. **完全免费**：CosyVoice 声音设计不收费
3. **一次创建永久使用**：voice_id 持续有效（需每年至少用一次）
4. **不满意可重来**：相同描述每次结果不同，可多次生成选最优

**tonggan 教练音色描述建议**：
```
25-30岁温柔女性声音，中等偏沉音调、绝不能尖锐刺耳，
语速适中偏慢、吐字非常清晰圆润，
语气温暖亲切有亲和力，适合引导5-12岁儿童，
情感表达乐观积极，鼓励语气自然不做作。
```

> ⚠️ **实测提醒**：当前 API Key 的 `instruction` 参数在所有模型均返回错误 428，无法通过指令控制系统音色的情感/语速。因此声音设计是**唯一的精确控制方案**。

---

## 十四、声音设计 API 完整参考

> 文档来源：[声音设计API参考](https://help.aliyun.com/zh/model-studio/voice-design-api-references)

### 14.1 服务端点

```
POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
```

| 地域 | 端点 |
|------|------|
| 华北2（北京） | `dashscope.aliyuncs.com` |
| 新加坡 | `{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com` |

**通用请求头**：

| 参数 | 值 |
|------|-----|
| `Authorization` | `Bearer <api_key>` |
| `Content-Type` | `application/json` |

### 14.2 四种操作一览

| 操作 | CosyVoice action | Qwen action | 说明 |
|------|:--:|:--:|------|
| 创建音色 | `create_voice` | `create` | 用文字描述生成定制音色 |
| 查询列表 | `list_voice` | `list` | 分页查看所有已创建音色 |
| 查询详情 | `query_voice` | `query` | 查看单个音色详细信息 |
| 删除音色 | `delete_voice` | `delete` | 删除不再使用的音色 |

### 14.3 创建音色（完整参数）

**Top-Level 参数**：

| 参数 | 类型 | 必选 | 说明 |
|------|------|:--:|------|
| `model` | string | ✅ | `voice-enrollment`（CosyVoice）或 `qwen-voice-design`（Qwen） |
| `input` | object | ✅ | 输入参数对象 |
| `parameters` | object | ❌ | 音频输出参数配置 |

**`input` 对象**：

| 参数 | 类型 | 必选 | CosyVoice | Qwen | 说明 |
|------|------|:--:|:--:|:--:|------|
| `action` | string | ✅ | `create_voice` | `create` | 操作类型 |
| `target_model` | string | ✅ | 同左 | 同左 | 目标合成模型 |
| `voice_prompt` | string | ✅ | ≤500字符 | ≤2048字符 | 声音描述，仅中/英文 |
| `preview_text` | string | ✅ | ≤200字符 | ≤1024字符 | 预览朗读文本 |
| `prefix` | string | 条件 | ≤10字符，字母+数字 | — | CosyVoice 音色名前缀 |
| `preferred_name` | string | 条件 | — | ≤16字符，字母+数字+下划线 | Qwen 音色名前缀 |
| `language_hints` | array | ❌ | `["zh"]` / `["en"]` | — | 语言倾向，仅处理第一个 |
| `language` | string | ❌ | — | zh/en/de/it/pt/es/ja/ko/fr/ru | 语言倾向 |

**`parameters` 对象**：

| 参数 | 类型 | 必选 | CosyVoice | Qwen | 默认值 |
|------|------|:--:|-----------|------|:--:|
| `sample_rate` | int | ❌ | 16000/24000/48000 | 8000/16000/24000/48000 | 24000 |
| `response_format` | string | ❌ | pcm/wav/mp3 | pcm/wav/mp3/opus | wav |

**返回体关键字段**：
- `output.voice_id`：CosyVoice 音色 ID（后续合成使用）
- `output.voice`：Qwen 音色名称
- `output.preview_audio.data`：Base64 编码音频
- `output.preview_audio.sample_rate`：采样率
- `output.preview_audio.response_format`：音频格式
- `usage.count`：固定为 1

### 14.4 查询音色列表

**`input` 参数**：

| 参数 | 类型 | 必选 | 说明 |
|------|------|:--:|------|
| `action` | string | ✅ | `list_voice`（CosyVoice）/ `list`（Qwen） |
| `prefix` | string | ❌ | 按前缀筛选（仅 CosyVoice） |
| `page_index` | int | ❌ | 页码索引 |
| `page_size` | int | ❌ | 每页条数 |

**返回字段**（CosyVoice）：
- `output.voice_list[]`：每项含 `voice_id`、`gmt_create`、`gmt_modified`、`status`、`voice_prompt`、`preview_text`

**返回字段**（Qwen）：
- 额外返回 `page_index`、`page_size`、`total_count`
- `voice_list[]` 中用 `voice` 代替 `voice_id`
- 包含 `language`、`target_model`，无 `status`

### 14.5 查询音色详情

| 参数 | 类型 | 必选 | 说明 |
|------|------|:--:|------|
| `action` | string | ✅ | `query_voice`（CosyVoice）/ `query`（Qwen） |
| `voice_id` | string | 条件 | 仅 CosyVoice，要查询的音色 ID |
| `voice` | string | 条件 | 仅 Qwen，要查询的音色名称 |

### 14.6 删除音色

| 参数 | 类型 | 必选 | 说明 |
|------|------|:--:|------|
| `action` | string | ✅ | `delete_voice`（CosyVoice）/ `delete`（Qwen） |
| `voice_id` | string | 条件 | 仅 CosyVoice，要删除的音色 ID |
| `voice` | string | 条件 | 仅 Qwen，要删除的音色名称 |

### 14.7 音色状态（仅 CosyVoice）

| 状态 | 含义 |
|:--:|------|
| `DEPLOYING` | 审核中/处理中 |
| `OK` | ✅ 审核通过，可正常使用 |
| `UNDEPLOYED` | ❌ 审核未通过，不可使用 |

> 💡 创建音色后建议轮询 `query_voice` 等待状态变为 `OK` 再使用。

### 14.8 CosyVoice vs Qwen 声音设计差异速查

| 维度 | CosyVoice (`voice-enrollment`) | Qwen (`qwen-voice-design`) |
|------|------|------|
| 创建 action | `create_voice` | `create` |
| 描述长度 | ≤500字符 | ≤2048字符 |
| 预览文本 | ≤200字符 | ≤1024字符 |
| 音色标识 | `voice_id` | `voice` |
| 命名参数 | `prefix`（≤10字符，字母+数字） | `preferred_name`（≤16字符） |
| 状态管理 | ✅ 3种状态 | ❌ 无状态 |
| 分页信息 | ❌ | ✅ 返回 total_count |
| 费用 | **免费** | 0.2元/次（90天内10次免费） |
| 合成时使用 | `voice: voice_id` | `voice: voice`（名称） |

---

## 十五、audio_codebuddy 项目实测验证记录

> 📅 实测日期：2026-06-14 | 环境：阿里云 ECS 服务器 (8.159.134.106:22622) | API Key: sk-c2567...

### 15.1 核心配置（已验证可用）

```json
{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "你好测试",
    "voice": "longanhuan_v3",
    "format": "mp3",
    "sample_rate": 48000
  }
}
```

**测试结果**：✅ 调用成功，返回音频 URL

```json
{
  "output": {
    "audio": {
      "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/...mp3"
    },
    "finish_reason": "stop"
  },
  "usage": { "characters": 8 }
}
```

### 15.2 同步 vs 流式模式选择

| 模式 | CosyVoice v3-flash 系统音色 | 结论 |
|------|:--:|------|
| **同步非流式** | ✅ 返回 `output.audio.url` | **推荐使用** |
| **SSE 流式** (`X-DashScope-SSE: enable`) | ❌ 返回 `text/event-stream` 但 `audioEvents=0` | **不可用** |

> ⚠️ **重要**：CosyVoice v3-flash 系统音色的 SSE 流式模式会返回空的音频事件（`audioEvents=0`），必须走同步非流式模式获取音频 URL。

### 15.3 sample_rate 兼容性

| sample_rate | 文档说明 | 实测结果 |
|:--:|------|:--:|
| 24000 | 默认值 | ✅ 通过 |
| 48000 | 白名单支持 | ✅ 通过（tonggan 项目也用此值） |

> audio_codebuddy 当前使用 48000，与 tonggan 项目一致，已验证可用。

### 15.4 错误码速查表

| HTTP状态 / 错误码 | 含义 | 原因 | 解决方案 |
|------|------|------|------|
| `428` | Precondition Required | **模型服务未在百炼控制台开通** | 到阿里云百炼控制台激活 CosyVoice 模型 |
| `400` (本地 curl) | Bad Request | Windows cmd/PowerShell 的 curl 对 JSON 转义处理有问题 | 用 Git Bash 或从服务器端测试 |
| `418` | Unsupported voice | 音色与模型不兼容（如 v3.5 模型用系统音色） | 检查模型版本与音色的兼容性 |
| `429` | Rate Limit | QPS 超限 | 降低并发或等待后重试 |

### 15.5 voice_id 映射验证

audio_codebuddy 的 10 个统一音色 → CosyVoice 真实音色映射验证结果：

| 统一ID | 名称 | CosyVoice 真名 | 支持Instruct | 验证 |
|--------|------|---------------|:--:|:--:|
| voice_01 | 温柔女声 | `longanhuan_v3` | ✅ | ✅ |
| voice_02 | 磁性男声 | `longanyang` | ✅ | ✅ |
| voice_03 | 活泼女声 | `longhuhu_v3` | ✅ | ✅ |
| voice_04 | 知性女声 | `longyuan_v3` | ❌ | ✅ |
| voice_05 | 阳光男声 | `longyichen_v3` | ✅ | ✅ |
| voice_06 | 沧桑男声 | `longlaobo_v3` | ❌ | ✅ |
| voice_07 | 甜美女声 | `longhua_v3` | ❌ | ✅ |
| voice_08 | 清朗男声 | `longshuo_v3` | ❌ | ✅ |
| voice_09 | 亲切女声 | `longanrou_v3` | ✅ | ✅ |
| voice_10 | 稚嫩童声 | `longpaopao_v3` | ✅ | ✅ |

> 所有音色 ID 均已对照官方音色列表确认有效。支持 Instruct 的音色可使用固定格式 `设置情感：{emotion}。` 控制情感。

### 15.6 Provider 优先级配置

```
优先级：bailian (阿里云 CosyVoice) > edge-tts (微软免费备用)
```

- bailian 熔断阈值设 999（永不熔断），冷却 10s
- edge-tts 作为纯备用方案，声音偏机械
- 用户偏好：阿里云优先，edge-tts 仅兜底

### 15.7 实测结论

1. **参数完全正确**：model、voice、format、sample_rate 全部与官方文档 + tonggan 验证结果一致
2. **同步模式是唯一选择**：SSE 流式对 CosyVoice 系统音色无效
3. **48000 采样率可用**：tonggan 项目和 audio_codebuddy 均验证通过
4. **instruction 固定格式**：`设置情感：{emotion}。`（中文冒号、中文句号，不可遗漏）
5. **428 = 模型未开通**：不是代码问题，需要去百炼控制台开通服务
6. **本地 400 与 IP 无关**：阿里云不封用户 IP，本地 curl 失败通常是 shell 转义问题

---