# CosyVoice / Qwen-TTS 声音设计指南

> 数据来源:阿里云官方 [声音设计文档](https://help.aliyun.com/zh/model-studio/voice-design),
> 用户下载到 `tts音色/声音设计-...html` 后 playwright 渲染抽取。
> 文档生成时间:2026-07。

## 一、什么是"声音设计"

**声音设计(Voice Design)** 是阿里云百炼提供的一条**合成新音色**的路径,**无需训练数据,纯文本描述即可生成音色**。

适用场景:
- **快速原型验证** — 给 AI 助手 / 游戏角色试不同人设
- **创意内容生产** — 给虚拟主播 / 短视频创作者设计独特声音
- **游戏角色配音** — 为 NPC 创造专属声音

和**声音复刻**的区别:
| 维度 | 声音设计 | 声音复刻 |
|------|---------|----------|
| 输入 | 自然语言描述 | 真实音频样本 |
| 是否需要录音 | ❌ 不需要 | ✅ 需要 |
| 适合 | 创造新声音形象 | 还原特定人声 |
| 自由度 | 由 Prompt 决定(可多次尝试) | 固定基于样本 |

## 二、支持的模型与地域

### CosyVoice 系列
- ✅ `cosyvoice-v3.5-plus`(北京)
- ✅ `cosyvoice-v3.5-flash`(北京)
- ✅ `cosyvoice-v3-plus`(北京)
- ✅ `cosyvoice-v3-flash`(北京)

> ⚠️ CosyVoice 声音设计**仅支持北京地域**,其他地域不可用。

### Qwen-TTS 系列
- ✅ `qwen3-tts-vd-2026-01-26`(北京 — 最新快照)
- ✅ `qwen3-tts-vd-realtime-2026-01-15`(北京 + 新加坡)
- ✅ `qwen3-tts-vd-realtime-2025-12-16`(快照版)

> 声音描述长度上限:**2048 字符**(Qwen-TTS)。

## 三、声音描述 prompt 怎么写

### 1. 核心规则(必须遵守)
- **字数限制 100 字符**(汉字按 2,其他按 1)
- **描述语只支持中文/英文**
- **具体而非模糊**:用"低沉 / 清脆 / 语速偏快"
- **多维而非单一**:组合"性别 + 年龄 + 情感 + 用途"
- **客观而非主观**:用"音调偏高,带有活力"
- **原创而非模仿**:不要求模仿特定人物(版权风险)
- **简洁而非冗余**

### 2. 7 个推荐描述维度

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

### 3. 官方示例

```
✅ 标准播音风格:吐字清晰精准,字正腔圆

✅ 年轻活泼女性:语速较快,带有明显的上扬语调,适合介绍时尚产品

✅ 沉稳中年男性:语速缓慢,音色低沉有磁性,适合朗读新闻或纪录片解说

✅ 温柔知性女性:30 岁左右,语调平和,适合有声书朗读

✅ 可爱儿童:大约 8 岁女孩,说话略带稚气,适合动画角色配音
```

### 4. 同一描述 → 不同结果(有随机性)

阿里云官方原话:**"声音设计具有随机性,相同描述可能生成略有差异的音色。建议多次生成后试听,择优使用。"**

→ 产品设计建议:让用户**预览 + 重生成**至少 2-3 次,挑最好的保存。

## 四、CosyVoice 声音设计完整流程

### 步骤 1 — 通过文本描述创建音色

```bash
curl -X POST 'https://{WorkspaceId}.cn-beijing.maas.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.5-plus",
      "voice_prompt": "沉稳的中年男性播音员，音色低沉浑厚，富有磁性，语速平稳，吐字清晰，适合用于新闻播报或纪录片解说。",
      "preview_text": "各位听众朋友，大家好，欢迎收听晚间新闻。",
      "prefix": "announcer"
    },
    "parameters": {
      "sample_rate": 24000,
      "response_format": "wav"
    }
  }'
```

返回:
```json
{
  "output": {
    "voice_id": "voice_announcer_xxxxxx",
    "preview_audio_url": "https://...mp3"
  }
}
```

### 步骤 2 — 用创建的 voice_id 合成语音

```python
import dashscope, os
from dashscope.audio.tts_v2 import SpeechSynthesizer

dashscope.api_key = os.environ['DASHSCOPE_API_KEY']
dashscope.base_websocket_api_url = 'wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference'

# 关键:声音设计、语音合成要使用相同的模型
synthesizer = SpeechSynthesizer(
    model='cosyvoice-v3.5-plus',          # ← 同一个模型
    voice='voice_announcer_xxxxxx',        # ← 步骤1返回的 voice_id
)
audio = synthesizer.call("今天天气怎么样？")
with open('output.mp3', 'wb') as f:
    f.write(audio)
```

### Qwen-TTS 流程类似

```python
import dashscope, os
from dashscope.audio.tts_v2 import SpeechSynthesizer

VOICE_PROMPT = "年轻活泼的女性声音，语速较快，带有明显的上扬语调，适合介绍时尚产品。"
TARGET_MODEL = "qwen3-tts-vd-2026-01-26"  # 声音设计 / 合成 必须用同一个

# 创建音色
from dashscope.audio.tts_v2 import VoiceEnrollment
resp = VoiceEnrollment.create_voice(
    target_model=TARGET_MODEL,
    voice_prompt=VOICE_PROMPT,
    preferred_name='my_voice',
)
voice_id = resp.output.voice_id

# 用新音色合成
synth = SpeechSynthesizer(model=TARGET_MODEL, voice=voice_id)
audio = synth.call("你好,世界")
```

## 五、配额与计费

### 限额
- **每个账号最多 1000 个自定义音色**(CosyVoice / Qwen-TTS **各自独立**计算)
- 1 年未使用自动清理

### 计费
| 模型 | 创建费用 |
|------|---------|
| **CosyVoice** | ✅ 免费 |
| **Qwen-TTS** | 0.2 元/个(创建失败不收费) |

### 新用户免费额度
- 开通后 90 天内可享 **10 次免费**音色创建
- 仅限北京地域
- 创建失败不占用免费次数

## 六、产品设计建议(给"用户选音色"功能的)

### 系统音色 vs 自定义音色(用户视角)

```
音色选择 (UI)
├── 系统音色(开箱即用)
│   ├── CosyVoice v3-flash 系统音色(88 个)
│   ├── Qwen3-TTS 系统音色(48 个)
│   └── Edge TTS 系统音色(316 个)
└── 自定义音色(声音设计创建)
    ├── 我设计过(列表显示)
    └── 现在设计一个
```

### 关键 UX 设计要点

1. **每次创建都先试听预览,用户满意再保存**(避免一次性扣费 + 用户后悔)
2. **保留多次创建的能力**(同一个 prompt 可能产生 2-3 个不同结果,用户挑最好的)
3. **失败时显式提示**(返回 "preview_text 没有发音"/"网络错误" 等)
4. **支持删除**(释放配额,避免 1000 个上限)
5. **建议首选 CosyVoice**(免费 + 支持中英双语描述)

## 七、与现有项目整合的位置

### 后端服务
- 新建 `server/src/services/voice-design.service.ts`(声音设计 API 封装)
- 复用 `server/.env` 里的 `DASHSCOPE_API_KEY`(API Key 已配好)
- 新建控制器路由:
  - `POST /api/tts/voice-design/preview`(创建 + 预览,**不保存**)
  - `POST /api/tts/voice-design/save`(保存到账户)
  - `GET /api/tts/voice-design/list`(查已有自定义音色)
  - `DELETE /api/tts/voice-design/:voice_id`(删除)
  - 所有路由要强制 `target_model` = `voice_id` 创建时的模型(否则音色不匹配)

### 前端 UI(后续开发)
- 现有音色选择器旁加"+"按钮 → 进入声音设计向导:
  1. 选模型(CosyVoice v3.5-plus 推荐免费)
  2. 输入描述(或选模板示例)
  3. 调 `/preview` 接口拿预览音频播放
  4. "重新生成"重复 3
  5. "保存"调 `/save` 接口
- 音色保存后存 `Book.book.voiceId`(已存在的字段,扩展支持用户自定义音色 ID)

### 与"语言选择"功能的关系
- 声音描述语言:**只支持中/英文**(`voice_prompt` 字段)
- 但生成的音色 **可以用于合成多语言语音**(比如生成"温柔女声"后,可以用来合成英语/日语文本)
- 如果"用户选日语 + 声音设计" → prompt 用中英文写,生成新音色后合成日语文本

## 八、与 `cosyvoice-voice-list` 系统音色的本质区别

| 维度 | 系统音色(`voice-list`) | 声音设计(`voice-design`) |
|------|----------------------|---------------------------|
| 来源 | 阿里云预训练 | 用户文本描述实时生成 |
| 数量 | 216 个(CosyVoice)/ 48 个(Qwen) | 上限 1000 个/账号 |
| 稳定性 | 确定性,固定可重现 | 有随机性,需试听择优 |
| 成本 | 0 | CosyVoice 免费 / Qwen-TTS 0.2 元 |
| 速度 | 立即可用 | 1-5 秒生成预览 |
| 后端代码 | `ALIYUN_VOICE_MAP` 直接列名字 | 需要 API 调用 + 用户保存 |

## 九、迁移指引

实现完整"声音设计"功能的预估工作量:
- **后端**(2-3 天):
  - `voice-design.service.ts` 封装阿里云 API
  - 5 个 REST 路由
  - 自定义音色列表查询(整合到现有 `pickTtsVendor()` 路由)
- **前端**(2-3 天):
  - 声音设计向导页(4 步流程)
  - 预览音频播放器(网页 audio 标签)
  - 用户自定义音色列表管理
- **测试**(1 天):每种模型 + 各种 prompt 类型的端到端

完整的功能开发建议在"用户选语言"功能稳定后再做(用户反映"想要更多音色")时启动。