外观
文本转语音 TTS（ruoyi-aihuman-tts）
模块：
ruoyi-aihuman-tts职责：文本转语音。实时播报全面采用流式双工（百炼实时）；非流式（阿里云 NLS 整段
/tts/aliyun）即将弃用，仅作兼容保留。另有百炼版「非流式下载」接口（/tts/qwen/download），仅用于生成预设语音 mp3 文件，不参与实时播报。
一、TTS 链路（非流式即将弃用）
/tts/aliyun 即将弃用，TTS 统一改用流式双工 /tts/aliyunStream/ws
非流式链路 POST /digital-human/tts/aliyun 及其下载接口 GET/POST /digital-human/tts/aliyun/download 即将弃用，后续版本将移除；新接入与前端播报请统一使用流式双工 WebSocket /digital-human/tts/aliyunStream/ws。
- 弃用原因：非流式必须等 LLM 的流式文本全部返回后才开始合成，首包延迟高（见第七节）；
- 替代方案：双工链路边收边投喂文本、音频分片实时回流，首包延迟更低、体验更好；
- 迁移方式：前端把非流式调用替换为双工 WebSocket；保留期内该链路仅作为双工不可用时的降级回退。
| 链路 | 接口 | 说明 |
|---|---|---|
| 非流式（整段 mp3）【即将弃用】 | POST /digital-human/tts/aliyun | 阿里云 NLS 整段合成，返回 audio/mpeg。即将弃用，请改用下方流式双工 |
| 非流式下载**【即将弃用】** | GET/POST /digital-human/tts/aliyun/download | 合成结果直接下载（Content-Disposition: attachment）。即将弃用 |
| 流式双工**【统一采用】** | WebSocket /digital-human/tts/aliyunStream/ws | 百炼实时合成，增量文本投喂、音频连续回流 |
| 非流式下载（百炼直出 mp3） | GET/POST /digital-human/tts/qwen/download | 生成预设语音文件：一次性合成、服务端直接输出 mp3，传参即下载（见 1.1） |
音色不可跨平台混用：NLS 音色只对
/tts/aliyun生效；百炼 Qwen 音色只对双工与预设语音下载（/tts/qwen/download）生效，混用报InvalidParameter。HTTP 版
/tts/aliyunStream已移除（延迟大），双工链路不受影响。⏱️ 23s 空闲超时已由后端自动规避：阿里云实时合成要求会话内 23s 必须有新文本送入，否则断开（
InvalidParameter: request timeout after 23 seconds，现象是 LLM 思考过久导致后半段回答没有声音）。AliyunRealtimeTtsBridge内置「空闲保活」看门狗——距上次真正投喂文本超过aihuman.tts.aliyun.realtime.idle-keep-alive-ms（默认 15000）就补发一段idle-keep-alive-text（默认「。」）当保活帧，只为重置服务端空闲计时；设为0关闭。日志关键字空闲 …ms 未投喂文本，补发保活帧。
1.1 预设语音 mp3 生成（百炼直出，非播报链路）
用途：方便生成 mp3 文件，直接下载作为「预设语音」使用。 把固定话术（数字人开场白、欢迎语、固定播报词等）一次性合成为 mp3 下载下来，作为静态音频资源使用。 它不是实时播报链路——前端实时播报仍统一走双工
WS /digital-human/tts/aliyunStream/ws。
| 接口 | 说明 |
|---|---|
GET /digital-human/tts/qwen/download?text=你好&voice=xuyanchu_v3.1 | 浏览器可直接打开 / <a href> 触发下载：返回 audio/mpeg 文件流（Content-Disposition: attachment，文件名 tts_<时间戳>.mp3） |
POST /digital-human/tts/qwen/downloadBody： { "text": "你好", "voice": "xuyanchu_v3.1" } | 同上，适合长文本或不便 URL 编码的场景 |
- 模型：
qwen-audio-3.1-tts-flash（与双工同款模型），API Key / 地址 / 默认音色沿用aihuman.tts.aliyun.realtime.*； - 参数：
text必填；voice可选，不传则用配置默认xuyanchu_v3.1（许言初，音色与模型强绑定，不可跨模型混用）； - 输出：非流式输入输出——整段文本投喂完后收齐全部音频再一次返回；服务端
format=mp3直出 mp3，后端无需再做 PCM→MP3 编码，二进制分片按序拼接即为完整可播放文件； - 限制：不受 NLS 版 300 字符限制，单条文本超过 20000 字符时自动按协议上限切分投喂；
- 配置（均有默认值，一般无需修改）：
aihuman.tts.aliyun.realtime.download-format（默认mp3）、download-sample-rate（默认24000）、download-timeout-ms（默认60000，超时自动取消云端任务并返回错误）； - 失败返回：HTTP 500 + JSON
{ "code": 500, "msg": "错误信息" }； - 实现类：
AliyunQwenTtsDownloadService（Bean 名aliyunQwenTtsService，TtsController的/qwen/download端点调用）。
与 NLS 版
/tts/aliyun/download的区别：后者走阿里云智能语音交互（NLS），使用 NLS 音色、单次限 300 字符、即将弃用；本接口走百炼，直接输出 mp3，用于产出预设语音文件，不涉及实时播报。
二、用到的模型 / 音色
| 平台 | 模型 / 音色 | 费用(付费) | 配置 | 音色列表 |
|---|---|---|---|---|
| 阿里云 NLS （非流式） 即将弃用（第一版遗留） | 默认 zhixiaoxia（知小夏）等 11 个音色 | 3万次/100 元/年 | aihuman.tts.aliyun.appkey access-key-id access-key-secret | 详情 |
| 阿里云百炼 3.1 （流式双工·统一采用 ＋预设语音 mp3 下载） | qwen-audio-3.1-tts-flash，默认音色 xuyanchu_v3.1（许言初） | 输入：1.5元/每百万tokens 输出：12元/每百万tokens | aihuman.tts.aliyun.realtime.api-key url | 详情 |
三、音色列表
- 阿里云 NLS（非流式，按次收费）共 11 个：知小夏（推荐）、知小白、知猫、若兮、思琪、思佳、知燕、知米、知妙、思悦、小云（前端
aliyunConfig.voiceList） - 百炼 Qwen（流式双工 / 预设语音 mp3 下载）统一使用
qwen-audio-3.1-tts-flash，共 8 个音色（默认xuyanchu_v3.1=许言初）（前端aliyunConfig.streamVoiceList）
四、凭证与安全
- 阿里云 NLS：Appkey / AccessKey ID / AccessKey Secret（
aihuman.tts.aliyun.*） - 阿里云百炼：API Key + WebSocket 域名（
aihuman.tts.aliyun.realtime.*） - TTS 接口安全令牌：前端以
X-TTS-Token头携带（aihuman.tts.security.access-token）
五、关键类
TtsController（/tts/aliyun、/tts/aliyun/download【即将弃用】；/tts/qwen/download预设语音 mp3 生成）TtsWebSocketConfig+AliyunTtsStreamWebSocketHandler（双工）AliyunRealtimeTtsBridge（双工实时桥）AliyunQwenTtsDownloadService（非流式一次性合成，服务端直出 mp3，供预设语音下载）
六、官方文档
- 阿里云 NLS 语音合成（接口说明）：https://help.aliyun.com/zh/isi/developer-reference/overview-of-speech-synthesis
- 阿里云 NLS 语音合成（RESTful API）：https://help.aliyun.com/zh/isi/developer-reference/restful-api-3
- 阿里云 NLS Access Token 获取：https://help.aliyun.com/zh/isi/getting-started/obtain-an-access-token
- 阿里云 NLS Token（HTTP/HTTPS 方式）：https://help.aliyun.com/zh/isi/getting-started/use-http-or-https-to-obtain-an-access-token
- 百炼实时语音合成用户指南：https://docs.bailian.console.aliyun.com/zh/model-studio/realtime-tts-user-guide
- 百炼 Qwen-Audio-TTS 音色列表：https://docs.bailian.console.aliyun.com/zh/model-studio/qwen-audio-tts-voice-list
七、价格及模型
7.1 NLS语音合成（即将弃用）
最开始使用的是NLS语音合成，价格为：3万次/100元/年；
- 优点：
- 预算有限不会超；
- 合成速度相对较快
- 缺点：
- 必须等llm的流式文本全部返回后，才开始转语音，有延迟
7.2 单实例部署
后来知道了项目为单实例部署，所以我就想着转为流式转tts，因为单实例用量消耗不会大的，恰好我看到阿里云官网发布了降价通知 
并且我也咨询了客服，客服说计费方式改为token后，更便宜了 
于是我实测了几次，大概算下来，折算每万字符大概0.3元 
7.3 流式tts合成
于是我尝试使用qwen-audio-3.1-tts-flash模型来合成测试，首包延迟更低了，可以做到后台的llm接口一边输出文字，数字人实时播报合成的tts语音，体验提升巨大；
而且，还有个好处，就是，单实例按量付费，可能一年也花不了几块钱；
配合我的文本清洗方法cleanTextForTTS ，剔除表格、代码、表情、冗余符号后，真正进入 TTS 的字符数大幅降低，单次与累计额度消耗都更少，详见。