qwencloud-audio-tts

Qwen Audio TTS（文本转语音）

使用 Qwen TTS 模型，将文本合成为自然语音。 此技能属于 qwencloud/qwencloud-ai。

技能目录

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

位置	用途
scripts/tts.py	Qwen TTS / Qwen Audio TTS（HTTP 和 WebSocket）；当前兼容性和默认设置见下方的模型目录
scripts/tts_cosyvoice.py	CosyVoice（WebSocket API）——需要 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 中使用 $QWENCLOUD_API_KEY，在 Python 中使用 os.environ["QWENCLOUD_API_KEY"]）。脚本依次接受 QWENCLOUD_API_KEY、QWEN_API_KEY 和 DASHSCOPE_API_KEY。对凭证进行任何检查或检测时，都必须避免明文：只报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不显示可能包含密钥的 .env 或配置文件内容。

如果尚未配置 API 密钥，绝不要求用户直接提供。 请改为协助创建包含占位符的 .env 文件（QWENCLOUD_API_KEY=sk-your-key-here），并指导用户从 QwenCloud Console 获取实际密钥并替换占位符。只有在用户明确要求时，才能写入实际密钥值。

关键兼容性说明

脚本同时支持标准 QwenCloud API 密钥（sk-...）和 Token Plan 密钥（sk-sp-...）。对于受支持的 TTS 模型，Token Plan 密钥会自动路由到 Token Plan 端点——请参阅下方的 Token Plan 支持。

Token Plan：不要使用 curl；始终使用随附的 Python 脚本。

Coding Plan 密钥（前缀同为 sk-sp-，但通过 Coding Plan 订阅购买）不可使用——Coding Plan 不提供 TTS 模型。脚本会在启动时检测密钥类型并据此路由。如果已安装 qwencloud-ops-auth，请参阅其 references/codingplan.md 了解完整详情。

检测 API 密钥类型，但不暴露密钥：

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	检测到 Token Plan 密钥（前缀为 sk-sp-）
payg	检测到标准 PAYG 密钥
not-set	环境中未找到 API 密钥

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

模型选择

🚫 关键——绝不要覆盖用户的模型选择。 如果用户（或请求 JSON）明确指定了 model，你必须严格使用该模型。不要：

• 将其替换为“更适合”的模型（例如，将风格化／诗意文本的模型切换为 qwen3-tts-instruct-flash）
• 添加用户未要求的 instructions
• 修改用户明确提供的任何参数

仅当用户未指定模型时，才适用以下模型选择指南。

在选择、推荐或设定默认模型之前，请获取并阅读最新的 QwenCloud 音频 TTS 模型目录。其中包含模型列表、基本模型信息、脚本和语音兼容性、推荐及默认设置。如果 CDN 无法访问，请使用本地备用文件。

当模型选择取决于能力、场景或定价时，请查阅 qwencloud-model-selector 技能。CosyVoice 需要 dashscope SDK，并使用不同的语音；请参阅 cosyvoice-guide.md。

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

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

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

可用语音

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

默认语音：对于未提供语音的 Qwen-Audio WebSocket 模型，tts.py 会选择该模型配置的默认语音，并向 stderr 输出提示。任何明确指定的语音（包括明确指定的 Cherry）都会原样传递。选择语音前，请先获取模型目录。

执行

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

Qwen TTS（HTTP API）—— tts.py

前置条件

• API 密钥：使用非明文检查方式依次检查 QWENCLOUD_API_KEY、QWEN_API_KEY，然后是 DASHSCOPE_API_KEY（例如，在 shell 中执行：[ -n "$QWENCLOUD_API_KEY" ]；仅报告“已设置”或“未设置”，绝不要显示密钥值）。如果未设置：若 qwencloud-ops-auth 技能可用，则运行该技能；否则，引导用户从 QwenCloud Console 获取密钥，并通过 .env 文件（在项目根目录或当前目录中执行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量进行设置。脚本会在当前工作目录和项目根目录中查找 .env。技能可能单独安装——不要假设存在 qwencloud-ops-auth。 注意：除已导出的环境变量外，脚本还会自动从当前目录和项目根目录加载 .env。shell 检查显示 $QWENCLOUD_API_KEY“未设置”并不意味着脚本会失败——它仍可能在 .env 中找到密钥。shell 检查仅供参考；权威的测试方式是直接运行脚本（如果在任何位置都找不到密钥，脚本会退出并显示明确的错误）。
• Python 3.9+（仅使用标准库，无需安装 pip 包）

环境检查

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

python3 --version  # must be 3.9+

如果 python3 不可用或版本低于 3.9，PAYG 可以使用 路径 2（curl）；Token Plan 则必须安装 Python 3.9+。

默认方式：运行脚本

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

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

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

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

参数	说明
--request '{...}'	JSON 请求正文
--file path.json	从文件加载请求
--output path	将音频和响应 JSON 保存到目录，或指定音频文件路径（例如 speech.mp3）；每次调用使用不同的文件名，以免覆盖
--print-response	将响应打印到标准输出
--model ID	覆盖模型
--voice NAME	覆盖语音

验证结果

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

失败时

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

如果 Python 完全不可用 → PAYG 可以使用路径 2（curl）；Token Plan 必须安装 Python 3.9+。

---

CosyVoice — tts_cosyvoice.py

CosyVoice 需要 dashscope SDK。快速开始：

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

Token Plan：tts_cosyvoice.py 会在启动时拒绝 Token Plan 密钥。获取上方链接的 Token Plan 目录，并使用 tts.py 搭配一个完全匹配且受支持的 TTS 模型，或使用 PAYG 密钥。未经用户确认，切勿替换用户明确指定的模型。

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

错误模式	诊断	解决方案
command not found: python3	Python 不在 PATH 中	尝试 python 或 py -3；如果未安装，请安装 Python 3.9+
Python 3.9+ required	脚本版本检查失败	将 Python 升级到 3.9+
SyntaxError near type hints	Python < 3.9	将 Python 升级到 3.9+
cosyvoice models are not available on Token Plan	检测到 Token Plan 密钥	使用 tts.py 搭配 Token Plan 目录中完全匹配且受支持的模型，或使用 PAYG 密钥
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	缺少 API 密钥	从 QwenCloud Console 获取密钥；添加到 .env：echo 'QWENCLOUD_API_KEY=sk-...' >> .env；或运行 qwencloud-ops-auth（如果可用）
HTTP 401	密钥无效或不匹配	运行 qwencloud-ops-auth（仅进行非明文检查）；确认密钥有效
SSL: CERTIFICATE_VERIFY_FAILED	SSL 证书问题（代理/企业网络）	macOS：运行 Install Certificates.command；否则设置 SSL_CERT_FILE 环境变量
URLError / ConnectionError	网络不可用	检查互联网连接；如果使用代理，请设置 HTTPS_PROXY
HTTP 429	请求频率受限	等待后使用退避策略重试
HTTP 5xx	服务器错误	使用退避策略重试
PermissionError	无法写入输出	使用 --output 指定可写目录

快速参考

请求字段

字段	类型	描述
text	string	必填 — 要合成的文本；有关模型专属限制，请查看上方的模型目录
voice	string	音色 ID；有关当前默认值和兼容性，请查看上方的模型目录
model	string	模型 ID；有关当前默认值，请查看上方的模型目录
language_type	string	Auto、Chinese、English、Japanese、Korean、French、German 等——使用完整名称，而非代码（zh、en）
instructions	string	语气/风格指示；有关当前兼容性和限制，请查看上方的模型目录
volume	int	音量 [0-100]，默认值为 50——仅支持 WebSocket 模型；请查看模型目录
rate	float	语速 [0.5-2.0]，默认值为 1.0；低于 1.0 会减慢语速——仅限 WebSocket 模型
pitch	float	音高倍数 [0.5-2.0]，默认值为 1.0；高于 1.0 会提高音高——仅限 WebSocket 模型
sample_rate	int	采样率，单位为 Hz，默认值为 24000——仅限 WebSocket 模型
format	string	音频格式：mp3/wav/pcm/opus，默认值为 mp3——仅限 WebSocket 模型
stream	bool	用于 SSE 流式传输的直接 Qwen3-TTS HTTP API 字段。随附的 tts.py 未实现此字段；请使用 execution-guide.md 中的直接 SSE 路径

响应字段

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

重要说明

• text：查看上方模型目录，了解所选模型当前的请求限制。
• instructions：支持情况因模型而异；使用前请查看上方模型目录。
• language_type：混合语言时使用 Auto；指定语言可获得更好的发音效果。值为完整名称（Chinese、English、Japanese 等），而非代码（zh、en）。此参数仅适用于兼容的 HTTP 模型；对于语言由所选语音决定的 WebSocket 模型，脚本会忽略此参数。
• audio_url：有效期为 24 小时，请尽快下载。
• 实时／流式 TTS：捆绑的 tts.py 对 Qwen3-TTS 使用非流式 HTTP，仅对 Qwen-Audio TTS 使用原始 WebSocket；CosyVoice 则由 tts_cosyvoice.py 处理。Qwen3-TTS API 本身支持可选的 SSE；需要时请使用 execution-guide.md 中的直接调用示例。

跨技能串联

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

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

错误处理

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

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

如需获取当前定价模型列表和计费单位，请获取 CDN 模型定价参考。如果无法访问 CDN，请使用本地备用文件。

**绝不要捏造、猜测或拼接用量／计费／控制台 URL。**只能提供此技能中列出的确切链接。如果此处未列出某个 URL，请勿自行编造。

输出位置

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

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

Token Plan 支持

Token Plan 仅支持部分 TTS 模型。选择或验证模型前，请获取并阅读当前的 Token Plan 模型目录。如果无法访问 CDN，请使用本地备用文件。

当 Token Plan 密钥与不受支持的模型搭配使用时，tts.py 会向 stderr 打印警告，列出当前受支持的模型并建议替代选项；但不会阻止调用。如果看到此警告，请告知用户当前目录支持哪些模型，并提供目录中列出的替代模型，或建议对原模型使用 PAYG 密钥。绝不要在未告知用户的情况下替换其明确指定的模型。

对于 CosyVoice，tts_cosyvoice.py 会在启动时强制禁止使用 Token Plan 密钥。请使用 tts.py 搭配当前 Token Plan 目录中列出的模型，或使用 PAYG 密钥。

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 = 最大值）

协议说明

QwenCloud 模型页面记录了 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. 接收二进制音频帧，并将其拼接到输出文件中

必需的请求头

User-Agent: qwencloud-skills 会自动包含在 HTTP 和 WebSocket 请求中。

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

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

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

当 stderr 包含此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。请勿默默跳过。

尚未安装更新检查 skill。它会帮助你及时了解 qwencloud/qwencloud-ai 的新功能和错误修复。

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

用户回复后：

• 用户选择 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，然后正常继续

信号：[UPDATE_AVAILABLE]

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

stderr 中没有信号

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

用户明确提出请求

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

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

参考资料

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