qianwen-audio-tts

Qwen Audio TTS（文本转语音）

使用 Qwen TTS 模型从文本合成自然语音。 此技能属于 QianWen-AI/qianwen-ai。

技能目录

使用此技能的内部文件来执行任务和了解相关信息。默认路径失效或需要更多详情时，按需加载参考文件。

位置	用途
scripts/tts.py	Qwen TTS（HTTP API）— qwen3-tts-、qwen-audio-3.0-tts-
scripts/tts_cosyvoice.py	CosyVoice（WebSocket / HTTP NRT）— 需要 dashscope SDK
references/cosyvoice-guide.md	CosyVoice 设置、语音、示例、错误
references/execution-guide.md	回退方案：curl（标准、指令、流式）、代码生成
references/prompt-guide.md	语音文本格式、指令模板、语音选择
references/api-guide.md	API 补充说明
references/sources.md	官方文档 URL

安全

绝不要以明文形式输出任何 API 密钥或凭据。 始终使用变量引用（在 shell 中使用 $DASHSCOPE_API_KEY，在 Python 中使用 os.environ["DASHSCOPE_API_KEY"]）。任何凭据检查或检测都必须采用非明文方式：只报告状态（例如“已设置”／“未设置”、“有效”／“无效”），绝不显示密钥值。绝不要显示可能包含机密的 .env 或配置文件内容。

未配置 API 密钥时，绝不要要求用户直接提供密钥。 应帮助用户创建带有占位符的 .env 文件（DASHSCOPE_API_KEY=sk-your-key-here），并指导用户从 QianWen Console 获取实际密钥并替换占位符。只有在用户明确要求时，才写入实际密钥值。

密钥兼容性

支持 PAYG（sk-ws-...；旧版 sk-...）和 Token Plan（sk-sp-...）密钥。检测 API 密钥类型时不得暴露密钥：

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

输出	含义
token-plan	Token Plan 密钥——只能使用下方 Token Plan 目录中的模型。
payg	按量付费密钥——可使用完整模型目录。
not-set	未配置密钥。

对于 Token Plan，请获取并阅读当前的 Token Plan 模型目录，然后使用其中精确列出的模型和 scripts/tts.py。如果 CDN 访问失败，请使用本地回退文件。

执行前：基于密钥的模型选择

调用 TTS 脚本前，请通过密钥前缀确定密钥类型（使用 scripts/qianwen_lib.py 进行非明文检查），然后获取并阅读当前的 Qwen 音频 TTS 模型目录，以了解脚本兼容性、建议和默认设置。如果 CDN 访问失败，请使用本地回退文件。

Token Plan 仅支持特定模型——必须严格使用上述参考资料中列出的模型；不要猜测或试探模型是否可用。PAYG 用户请继续阅读下文。

模型选择

选择、推荐或设置默认模型之前，请使用上方链接的 Qwen 音频 TTS 模型目录。该目录包含模型列表、基本信息、脚本和语音兼容性、建议及默认设置。

⚠️ 重要：模型目录是一个特定时间点的快照，可能已经过时。模型可用性 变化频繁。在做出模型选择前，务必查看官方模型列表， 以获取权威且最新的目录。

模型详情：如需了解特定模型的更多信息，请引导用户访问 https://www.qianwenai.com/models/<model-name>。将 <model-name> 替换为确切的模型 ID；绝不要修改或猜测该 ID。

动态查询模型：如果可以使用 qianwen-model-selector 技能或 QianWen CLI（qianwen models info <model>），请使用它获取实时模型数据。CLI 需要身份验证——登录流程请参阅 qianwen-usage 技能。

可用语音

请使用上方链接的 Qwen 音频 TTS 模型目录，查看最新的模型与语音兼容性及默认设置。完整的语音列表请参阅 sources.md 中的官方语音列表链接。

自定义语音（v3.5 必需）

cosyvoice-v3.5 模型需要自定义语音 ID。创建方法：

1. 访问 Voice Cloning
2. 上传一段 10-20s 的清晰语音样本
3. 获取自定义语音 ID
4. 通过 --voice <id> 或请求 JSON 中的 "voice": "<id>" 传入

执行

⚠️ 多个制品：在单个会话中生成多个文件时，必须为每个文件名添加数字后缀（例如 out_1.wav、out_2.wav），以防覆盖。

Qwen TTS（HTTP API）— tts.py

前置条件

• API Key：使用 Key Compatibility 中的非明文检测器；不要将其替换为变量是否存在的检查。如果未找到 Key，请在可用时使用 qianwen-ops-auth，或指导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。技能可以单独安装。
• Python 3.9+（仅使用标准库，无需 pip install）

环境检查

首次执行前，请确认 Python 可用：

python3 --version  # must be 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9，请跳转至 execution-guide.md 中的 路径 2（curl）。

默认方式：运行脚本

脚本路径：脚本位于此技能目录（即包含此 SKILL.md 的目录）下的 scripts/ 子目录中。**必须先定位此技能的安装目录，然后始终使用完整绝对路径执行脚本。**不要假设脚本位于当前工作目录中。执行前不要使用 cd 切换目录。

执行说明：在前台运行所有脚本——等待标准输出；不要在后台运行。

**发现参数：**先运行 python3 <this-skill-dir>/scripts/tts.py --help，查看所有可用参数。

python3 <this-skill-dir>/scripts/tts.py \
  --request '{"text":"Hello, this is a test.","voice":"longanlingxin"}' \
  --output output/qianwen-audio-tts/ \
  --print-response

参数	说明
--request '{...}'	JSON 请求体
--file path.json	从文件加载请求
--output path	将音频和响应 JSON 保存到目录，或指定音频文件路径（例如 speech.mp3）；多次调用时使用不同的文件名以避免覆盖
--print-response	将响应打印到标准输出
--model ID	覆盖模型
--voice NAME	覆盖语音
--format	Qwen-Audio-TTS NRT 模型的音频格式（默认值为 mp3，也可为 wav、pcm）
--sample-rate	Qwen-Audio-TTS NRT 模型的采样率（单位：Hz；默认值：24000）

模型优先级：--model CLI 标志 > --request JSON 中的 "model" 字段 > 内置默认值。

验证结果

• 退出代码为 0，且输出包含带有 output.audio 字段的有效 JSON → 成功
• 退出代码非零、HTTP 错误、响应为空或返回错误 JSON → 失败
• 执行后检查：确认输出音频文件存在且大小非零（ls -la <output_dir>）
• 必须 — 检查 stderr 信号：确认结果后，检查命令的 stderr 输出中是否包含 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]。如果出现任一信号，在回复用户之前，必须遵循下方 更新检查 中的说明。

失败时

如果脚本运行失败，请将错误输出与下方的诊断表进行匹配，以确定解决方法。如果没有匹配项，请阅读 execution-guide.md，了解替代方案：curl 命令（路径 2 — 标准、指令式、流式）、代码生成（路径 3）和自主解决（路径 5）。

如果完全无法使用 Python → 直接跳转至 execution-guide.md 中的路径 2（curl）。

---

CosyVoice — tts_cosyvoice.py

CosyVoice 需要 dashscope SDK。快速开始：

pip install dashscope>=1.25.17
python3 <this-skill-dir>/scripts/tts_cosyvoice.py --text "Hello"

完整指南：cosyvoice-guide.md（设置、音色、示例、错误）

错误模式	诊断	解决方法
command not found: python3	Python 不在 PATH 中	尝试 python 或 py -3；如果未安装，请安装 Python 3.9+
Python 3.9+ required	脚本版本检查失败	将 Python 升级到 3.9+
类型提示附近出现 SyntaxError	Python < 3.9	将 Python 升级到 3.9+
未找到 QIANWEN_API_KEY/DASHSCOPE_API_KEY	缺少 API 密钥	从 QianWen Console 获取密钥；添加到 .env：echo 'DASHSCOPE_API_KEY=sk-...' >> .env；或者在可用时运行 qianwen-ops-auth
HTTP 401	密钥无效或不匹配	运行 qianwen-ops-auth（仅进行非明文检查）；确认密钥有效
SSL: CERTIFICATE_VERIFY_FAILED	SSL 证书问题（代理/企业网络）	macOS：运行 Install Certificates.command；否则设置 SSL_CERT_FILE 环境变量
URLError / ConnectionError	网络不可达	检查互联网连接；如果在代理后，请设置 HTTPS_PROXY
HTTP 429	请求频率受限	等待后退避重试
HTTP 5xx	服务端错误	退避重试
PermissionError	无法写入输出	使用 --output 指定可写目录

快速参考

请求字段（Qwen3-TTS HTTP API — tts.py）

字段	类型	描述
text	string	必填 — 要合成的文本（最多 600 个字符）
voice	string	必填 — 音色 ID（例如 Cherry、Ethan）
model	string	模型 ID；当前默认值请参阅上方的模型目录
language_type	string	Auto、Chinese、English、Japanese、Korean、French、German 等
instructions	string	语气/风格指令；当前模型的兼容性和限制请参阅上方的模型目录
optimize_instructions	bool	为 true 时，系统会对 instructions 进行语义增强，以提升自然度。必须设置 instructions。默认值：false
stream	bool	启用流式传输（Base64 分块）

请求字段（CosyVoice NRT API — tts_cosyvoice.py）

字段	类型	描述
text	string	必填 — 要合成的文本（每次调用最多 20,000 个字符）
voice	string	必填 — 音色 ID（因模型而异，请参阅音色列表）
model	string	模型 ID；当前默认值请参阅上方的模型目录
instruction	string	用于语音控制的自由格式指令；当前模型的兼容性请参阅上方的模型目录
language_hints	list	目标语言提示：zh、en、fr、de、ja、ko、ru、pt、th、id、vi 等
format	string	音频格式：mp3（默认）、wav、pcm、opus
sample_rate	int	采样率（Hz）：8000、16000、22050（默认）、24000、44100、48000

响应字段

字段	描述
audio_url	生成音频的 URL（有效期 24 小时）
audio_format	格式（例如 wav）
sample_rate	采样率（例如 24000）
usage	字符用量

重要说明

• text：每次请求最多 600 个字符（Qwen3-TTS）。最多 20,000 个字符（CosyVoice/Qwen-Audio-TTS NRT）。
• instructions / instruction model compatibility：先查看上方的模型目录，然后使用所选模型对应的参数形式。
• language_type（Qwen3-TTS）：混合语言时使用 Auto；指定语言可获得更好的发音效果。
• language_hints（CosyVoice/Qwen-Audio-TTS）：指定目标语言代码（zh、en 等），以提升合成质量。
• audio_url：有效期为 24 小时，请尽快下载。
• 实时/流式 TTS：基于 WebSocket 的实时 TTS（CosyVoice、qwen3-tts-flash-realtime）需要 WebSocket 客户端。本技能介绍基于 HTTP 的非实时 API。实时流式处理场景请参阅 sources.md 中的官方文档。

跨技能串联

将生成的音频传递给其他技能（例如，视频生成音频叠加）时：

• 直接传递 audio_url——脚本会检测 URL 前缀并直接传递，不会重新上传
• 仅在本地播放或执行非 API 操作时使用 audio_file

错误处理

错误	原因	操作
401 Unauthorized	API 密钥无效或缺失	如果可用，运行 qianwen-ops-auth；否则提示用户设置密钥（仅进行非明文检查）
400	参数无效（缺少 text/voice）	验证请求正文
429 / 5xx	速率限制或服务端错误	采用退避策略重试

用量与计费：使用 qianwen-usage 技能直接查看用量、免费额度和计费信息。用户也可以访问 QianWen 控制台： 用量分析 | 按量付费 | Token 套餐订阅

**绝不要编造、猜测或拼接用量/计费/控制台 URL。**只能提供此技能中列出的确切链接。此处未列出的 URL 一律不得编造。

输出位置

优先使用当前工作目录。默认子目录：./output/qianwen-audio-tts/。

禁止写入：绝不要将输出文件写入此技能的安装目录或任何 skills/ 层级。所有生成内容都必须写入当前工作目录下的 output/，或用户指定的路径。

更新检查（执行后必须进行）

脚本执行后，检查 stderr 中的操作信号。脚本会自动检测更新状态并发出结构化信号。你必须根据这些信号采取相应操作。本节也适用于用户明确要求检查更新的情况。

信号：[ACTION_REQUIRED] qianwen-update-check skill is not installed

当 stderr 中出现此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。不要默默跳过此步骤。

更新检查技能尚未安装。它会及时通知你有关 QianWen-AI/qianwen-ai 的新功能和错误修复。

1. 立即安装——我会为你运行安装命令
2. 暂时跳过——本次不执行任何操作
3. 不再提醒——永久关闭此提示

用户回复后：

• 用户选择 1 → 运行：npx skills add QianWen-AI/qianwen-ai --skill qianwen-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，然后正常继续

信号：[UPDATE_AVAILABLE]

当 stderr 中出现此信号时，你必须在回复中附上一则简短的更新通知，其中包含版本信息和 stderr 输出中显示的更新命令。

stderr 中没有信号

如果 stderr 中既没有 [ACTION_REQUIRED]，也没有 [UPDATE_AVAILABLE]，则无需采取任何操作——该技能已安装且为最新版本（或缓存时间在 24 小时内）。

用户明确请求

当用户明确要求检查更新时（例如“检查更新”“检查版本”）：

1. 在同级技能目录中查找 qianwen-update-check/SKILL.md。
2. 如果找到，则运行：python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response，并报告结果。
3. 如果未找到，则提供上述安装选项。

参考资料

• execution-guide.md — 回退路径（curl 标准/指令/流式传输、代码生成、自主运行）
• api-guide.md — API 补充指南
• sources.md — 官方文档 URL