用 Qwen TTS 把文本合成语音（含模型/音色选择…

当需要把文本转成语音、生成配音或旁白、构建 TTS 应用时，用 Qwen TTS 模型合成自然语音。

适用场景

解决思路

1. 先定位本技能安装目录（含 SKILL.md 的目录），始终用绝对路径执行 scripts/ 下的脚本，不要假设脚本在当前工作目录，也不要用 cd 切换目录。
2. 执行前先运行 python3 <this-skill-dir>/scripts/tts.py --help 查看全部可用参数。
3. 默认执行方式：python3 <this-skill-dir>/scripts/tts.py --request '{"text":"Hello, this is a test.","voice":"Cherry"}' --output output/qwencloud-audio-tts/ --print-response。
4. 参数说明：--request '{...}' 传 JSON 请求体；--file path.json 从文件加载请求；--output path 保存音频与响应 JSON 到目录或指定音频文件路径（如 speech.mp3）；--print-response 打印响应；--model ID 覆盖模型；--voice NAME 覆盖音色。
5. 所有脚本必须在前台运行并等待 stdout，不要放到后台。
6. 单次会话生成多个文件时，必须给每个文件名加数字后缀（如 out_1.wav、out_2.wav）以防覆盖。
7. 选择/推荐/默认模型前，先获取并阅读最新的 QwenCloud audio TTS 模型目录（https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-audio-tts-models.md），CDN 失败时用本地回退 cdn/references/qwencloud-audio-tts-models.md。
8. 绝不覆盖用户指定的模型：若用户或请求 JSON 明确指定了 model，必须原样使用，不得替换为“更合适”的模型、不得添加用户未要求的 instructions、不得修改用户显式提供的任何参数。
9. 当模型选择取决于能力、场景或价格时，参考 qwencloud-model-selector 技能；CosyVoice 需要 dashscope SDK 且音色不同，参见 references/cosyvoice-guide.md。
10. 模型目录只是时间点快照，可能过期；做模型决策前始终查看官方模型列表 https://www.qwencloud.com/models 获取权威最新目录。
11. 查询具体模型详情时，引导用户访问 https://www.qwencloud.com/models/<model-name>，替换为精确模型 ID，绝不修改或猜测。
12. 若 qwencloud-model-selector 技能或 QwenCloud CLI（qwencloud models info <model>）可用，用其获取实时模型数据；CLI 需要认证，登录流程见 qwencloud-usage 技能。
13. 音色选择：用上面的模型目录获取当前模型-音色兼容性与默认值；完整音色清单用 sources.md 中的官方音色列表链接。
14. 音色默认行为：Qwen-Audio WebSocket 模型未提供 voice 时，tts.py 会选择该模型配置的默认音色并向 stderr 打印提示；任何显式 voice（包括显式 Cherry）都原样传递；选音色前先获取模型目录。
15. API Key 检查：按 QWENCLOUD_API_KEY、QWEN_API_KEY、DASHSCOPE_API_KEY 顺序做非明文检查（如 shell 中 [ -n "$QWENCLOUD_API_KEY" ]），只报告“已设置/未设置”，绝不显示 key 值。
16. 未设置 key 时：若 qwencloud-ops-auth 技能可用则运行它；否则引导用户从 https://home.qwencloud.com/api-keys 获取 key，并通过 .env 文件（在项目根或当前目录执行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量设置。
17. 注意脚本会自动从当前目录和项目根加载 .env，shell 检查显示未设置不代表脚本会失败；权威测试就是直接运行脚本（找不到 key 时会以清晰错误退出）。
18. 绝不向用户索要 API key 明文；需要创建 .env 时先写占位符 QWENCLOUD_API_KEY=sk-your-key-here 并让用户替换；只有用户明确要求时才写入真实 key 值。
19. 绝不输出任何 API key 或凭据明文；shell 用 $QWENCLOUD_API_KEY，Python 用 os.environ["QWENCLOUD_API_KEY"]；凭据检查只报告状态（set/not set、valid/invalid）；绝不显示可能含密钥的 .env 或配置文件内容。
20. 执行前检查 Python：python3 --version 必须为 3.9+；若 python3 不可用或低于 3.9，PAYG 可走 Path 2（curl），Token Plan 必须安装 Python 3.9+。
21. Token Plan 不要用 curl，始终用捆绑的 Python 脚本；Token Plan key 为 sk-sp- 前缀，会自动路由到 Token Plan 端点。
22. 用非明文方式检测 key 类型：python3 -c "import sys; sys.path.insert(0, 'scripts'); from qwencloud_lib import detect_api_key_type; print(detect_api_key_type('scripts/qwencloud_lib.py'))"，输出 token-plan / payg / not-set。
23. Token Plan 场景：先获取并阅读最新 Token Plan 模型目录（https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-token-plan-models.md），CDN 失败用本地回退 cdn/references/qwencloud-token-plan-models.md，然后用目录中精确列出的模型配合 scripts/tts.py。
24. Coding Plan key（同为 sk-sp- 前缀但来自 Coding Plan 订阅）不可用，TTS 模型不在 Coding Plan 上；脚本启动时会检测 key 类型并路由；若安装了 qwencloud-ops-auth，参见其 references/codingplan.md。
25. CosyVoice 快速开始：pip install dashscope>=1.25.17，然后 python3 <this-skill-dir>/scripts/tts_cosyvoice.py --text "Hello"；tts_cosyvoice.py 会在启动时拒绝 Token Plan key，此时改用 tts.py 配合 Token Plan 目录中的受支持模型，或使用 PAYG key。
26. 验证结果：退出码 0 且输出含带 output.audio 字段的有效 JSON 为成功；非零退出、HTTP 错误、空响应或错误 JSON 为失败；执行后检查输出音频文件存在且大小非零（ls -la <output_dir>）。
27. 强制 stderr 信号检查：确认结果后扫描 stderr 是否含 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]，若存在必须在回复用户前按 Update Check 章节处理。
28. 失败时按诊断表匹配错误：command not found: python3 → 试 python 或 py -3，缺失则安装 Python 3.9+；Python 3.9+ required 或类型提示 SyntaxError → 升级 Python；cosyvoice models are not available on Token Plan → 改用 tts.py 配合 Token Plan 目录模型或 PAYG key；key not found → 从控制台获取 key 并写入 .env 或运行 qwencloud-ops-auth；HTTP 401 → 运行 qwencloud-ops-auth（仅非明文检查）并验证 key；SSL: CERTIFICATE_VERIFY_FAILED → macOS 运行 Install Certificates.command，否则设置 SSL_CERT_FILE；URLError/ConnectionError → 检查网络，代理后设置 HTTPS_PROXY；HTTP 429 或 5xx → 退避重试；PermissionError → 用 --output 指定可写目录。
29. 无匹配错误时阅读 references/execution-guide.md 获取替代路径：curl 命令（Path 2：standard、instruct、streaming）、代码生成（Path 3）、自主解决（Path 5）。
30. 请求字段：text（必填，长度限制见模型目录）；voice（音色 ID，默认与兼容性见模型目录）；model（模型 ID，默认见模型目录）；language_type（Auto、Chinese、English、Japanese、Korean、French、German 等全名，不用 zh/en 代码）；instructions（语气/风格指令，兼容性与限制见模型目录）；volume（0-100，默认 50，仅 WebSocket 模型）；rate（0.5-2.0，默认 1.0，低于 1.0 变慢，仅 WebSocket 模型）；pitch（0.5-2.0，默认 1.0，高于 1.0 升高，仅 WebSocket 模型）；sample_rate（Hz，默认 24000，仅 WebSocket 模型）；format（mp3/wav/pcm/opus，默认 mp3，仅 WebSocket 模型）；stream（Qwen3-TTS HTTP API 的 SSE 流式字段，捆绑 tts.py 未实现，需用 execution-guide.md 中的直连 SSE 路径）。
31. 响应字段：audio_url（生成音频 URL，24 小时有效）、audio_format（格式，如 wav）、sample_rate（如 24000）、usage（字符用量）。
32. language_type 用 Auto 处理混合语言，指定可改善发音；值为全名（Chinese、English、Japanese 等）而非代码；仅适用于兼容的 HTTP 模型，WebSocket 模型会忽略它（语言跟随所选音色）。
33. audio_url 仅 24 小时有效，需及时下载。
34. 实时/流式 TTS：捆绑 tts.py 对 Qwen3-TTS 用非流式 HTTP，对 Qwen-Audio TTS 仅用原始 WebSocket；CosyVoice 由 tts_cosyvoice.py 处理；Qwen3-TTS API 本身支持可选 SSE，需要时用 execution-guide.md 中的直连示例。
35. 跨技能传递音频（如 video-gen 音频叠加）时直接传 audio_url，脚本会识别 URL 前缀并透传而不重新上传；仅在本地播放或非 API 操作时用 audio_file。
36. 错误处理：401 Unauthorized → 运行 qwencloud-ops-auth（若可用），否则提示用户设置 key（仅非明文检查）；400 → 校验请求体（缺 text/voice 等无效参数）；429/5xx → 退避重试。
37. 用量与计费：用 qwencloud-usage 技能查询用量、免费额度与计费，或让用户访问控制台 https://home.qwencloud.com/analytics、https://home.qwencloud.com/billing/pay-as-you-go、https://home.qwencloud.com/billing/coding-plan；定价模型列表与计费单位见 CDN 参考 https://alioth-intl.alicdn.com/skills-info/models/references/qwencloud-model-pricing.md，CDN 失败用本地回退 cdn/references/qwencloud-model-pricing.md；绝不编造、猜测或构造用量/计费/控制台 URL，只提供本技能列出的确切链接。
38. 输出位置：优先当前工作目录，默认子目录 ./output/qwencloud-audio-tts/；绝不把输出文件写入本技能安装目录或任何 skills/ 层级，所有生成内容必须写到当前工作目录下的 output/ 或用户指定路径。
39. Token Plan 风格控制：只用所选 Token Plan 模型在音频模型目录中支持的风格控制字段；示例（仅协议示例，不得替换用户指定模型）：{"text": "落霞与孤鹜齐飞，秋水共长天一色。", "model": "qwen-audio-3.0-tts-plus", "rate": 0.8, "pitch": 1.1, "volume": 60}；rate 低于 1.0 变慢、高于 1.0 变快；pitch 高于 1.0 升高、低于 1.0 降低；volume 线性缩放（0 静音、50 默认、100 最大）。
40. Token Plan 协议说明：qwen-audio-3.0-tts-plus 官方文档为 WSS（WebSocket），脚本的 WebSocket 分支会：1) 连接 wss://token-plan.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference（PAYG 用标准端点）；2) 在 WebSocket 握手中设置 User-Agent: qwencloud-skills；3) 发送 run-task → continue-task → finish-task 消息；4) 接收二进制音频帧并拼接为输出文件。
41. User-Agent: qwencloud-skills 会自动包含在 HTTP 和 WebSocket 请求中。
42. Token Plan 与不支持模型组合时，tts.py 会向 stderr 打印警告列出当前支持的模型并建议替代，但不阻断调用；看到警告时告知用户当前目录支持的模型，并提供目录中的替代模型或改用 PAYG key 使用原模型；绝不静默替换用户显式指定的模型。
43. 更新检查（强制）：脚本执行后检查 stderr 信号。若含 [ACTION_REQUIRED] qwencloud-update-check skill is not installed，必须向用户展示三个选项并等待回复：1) 现在安装 → 运行 npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y，然后运行 python3 <this-skill-scripts-dir>/gossamer.py --dismiss；2) 暂时跳过 → 运行 python3 <this-skill-scripts-dir>/gossamer.py --dismiss 后正常继续；3) 不再提醒 → 运行 python3 <this-skill-scripts-dir>/gossamer.py --never-install 后正常继续。
44. 若 stderr 含 [UPDATE_AVAILABLE]，必须在回复中追加简短更新提示，包含版本信息和 stderr 中显示的更新命令。
45. 若 stderr 既无 [ACTION_REQUIRED] 也无 [UPDATE_AVAILABLE]，无需操作（技能已安装且最新，或 24 小时内缓存）。
46. 用户显式要求检查更新时：1) 在兄弟技能目录中查找 qwencloud-update-check/SKILL.md；2) 找到则运行 python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response 并报告结果；3) 未找到则展示上述安装选项。

适用边界 · 注意事项

• 用户要做语音识别（ASR）、纯文本生成（无音频）或非 Qwen 的音频任务时不要触发。
• Coding Plan key（sk-sp- 前缀但来自 Coding Plan 订阅）不可用于 TTS，因为 TTS 模型不在 Coding Plan 上。
• CosyVoice 不支持 Token Plan key（tts_cosyvoice.py 启动时硬阻断），需改用 tts.py 配合 Token Plan 目录模型或 PAYG key。