Qwen 音频 TTS（文本转语音）

使用 Qwen TTS 模型将文本合成为自然语音。 此 skill 是 QianWen-AI/qianwen-ai 中的一部分。

Skill 目录

使用此 skill 的内部文件执行任务并了解其用法。默认路径失效或需要详细信息时，按需加载参考文件。

| 位置 | 用途 | |----------|---------| | 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 密钥时，禁止要求用户直接提供密钥。 应帮助创建包含占位值（DASHSCOPE_API_KEY=sk-your-key-here）的 .env 文件，并指导用户将其替换为从千问AI平台控制台获取的实际密钥。仅当用户明确要求时，才写入实际密钥值。

密钥兼容性

同时支持 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，请将 qianwen-model-selector 中的某个确切模型与 scripts/tts.py 配合使用，或 查阅 qianwen-ops-auth/references/tokenplan.md。如果无法使用，请使用：

• 个人版：https://platform.qianwenai.com/docs/token-plan/personal/token-plan-personal-overview.md
• 团队版：https://platform.qianwenai.com/docs/token-plan/team/token-plan-team-overview.md

执行前：根据密钥决定模型

调用任何 TTS 脚本前，请根据密钥前缀确定其类型（通过 scripts/qianwen_lib.py 进行非明文检查）。然后据此选择模型和脚本：

| 密钥前缀 | 类型 | 脚本 | 模型 | 说明 | |------------|------|--------|-------|-------| | sk-sp-... | Token Plan | scripts/tts.py | 默认使用 qwen-audio-3.0-tts-plus | 默认模型兼容 TP；自动应用音色 longanlingxin | | sk-ws-... / sk-... | PAYG | scripts/tts.py | 默认使用 qwen-audio-3.0-tts-plus（NRT） | 高品质，使用音色 longanlingxin，输出格式为 mp3 | | sk-ws-... / sk-... | PAYG | scripts/tts.py | --model qwen-audio-3.0-tts-flash | 成本更低的替代方案（仅限 PAYG），音色为 longanhuan_v3.6 | | sk-ws-... / sk-... | PAYG | scripts/tts.py | qwen3-tts-* / qwen-audio-3.0-tts-* | 可使用全系列模型 | | sk-ws-... / sk-... | PAYG | scripts/tts_cosyvoice.py | cosyvoice-* | 需要 dashscope SDK |

scripts/tts_cosyvoice.py 脚本仅支持 PAYG 密钥，并拒绝 Token Plan（sk-sp-...） 密钥。

Token Plan 仅支持特定模型 — 必须严格使用上述参考资料中的某个模型；不得 猜测或探测模型可用性。对于 PAYG，请继续阅读下文。

模型选择

Qwen TTS（HTTP API）— 使用 scripts/tts.py

| 模型 | 适用场景 | 说明 | |-------|----------|-------| | qwen3-tts-flash | 速度快，支持多语言 | 经济实惠；请显式指定 --model qwen3-tts-flash | | qwen3-tts-instruct-flash | 指令引导的风格控制 | 通过指令控制语气/情感 |

Qwen-Audio-TTS（HTTP NRT API）— 使用 scripts/tts.py

| 模型 | 适用场景 | 说明 | |-------|----------|-------| | qwen-audio-3.0-tts-plus | 默认 — 高品质专业场景 | TP + PAYG；指令控制、音色克隆、音色 longanlingxin | | qwen-audio-3.0-tts-flash | 低延迟实时交互 | 仅限 PAYG；NRT 端点，音色为 longanhuan_v3.6；请显式指定 --model |

CosyVoice（WebSocket / HTTP NRT API）— 使用 scripts/tts_cosyvoice.py

| 模型 | 适用场景 | 支持的音色 | 说明 | |-------|----------|---------------|-------| | cosyvoice-v3-flash | 高质量、速度快 | 支持系统音色（内置 80+ 种） | 默认 | | cosyvoice-v3-plus | 最高质量 | 支持系统音色（内置 80+ 种） | — | | cosyvoice-v3.5-flash | 高性能、支持指令控制、支持 11 种语言 | 仅支持自定义音色（需要声音复刻或声音设计） | 请参阅定价参考资料 | | cosyvoice-v3.5-plus | 表现力超强、支持指令控制、支持 11 种语言 | 仅支持自定义音色（需要声音复刻或声音设计） | 请参阅定价参考资料 |

注意：CosyVoice 需要 dashscope SDK。请参阅 [cosyvoice-guide.md](references/cosyvoice-guide.md)。Qwen-Audio-TTS 使用 tts.py（仅使用标准库，无需 SDK）。

1. 用户指定了模型 → 使用对应的脚本：

• qwen3-tts-* / qwen-audio-3.0-tts-* → scripts/tts.py
• cosyvoice-* → scripts/tts_cosyvoice.py

1. 模型选择取决于能力、场景或定价时，请查阅 qianwen-model-selector skill。
2. 无模型偏好信号，任务明确 → 通过 tts.py 使用 qwen-audio-3.0-tts-plus（默认；NRT 端点，音色为 longanlingxin，输出 mp3）。

⚠️ 重要：上述模型列表是特定时间点的快照，可能已经过时。模型可用性

变化频繁。**做出模型决策前，务必查看官方模型列表

，以获取权威且最新的模型目录。**

模型详情：如需了解特定模型的更多信息，请引导用户访问其详情页：https://www.qianwenai.com/models/<model-name>（将 <model-name> 替换为确切的模型 ID，例如 qwen3-tts-flash → <https://www.qianwenai.com/models/qwen3-tts-flash>）。禁止修改或猜测 URL 中的模型名称。

动态模型查询：如果 qianwen-model-selector skill 或千问AI平台 CLI（qianwen models info <model>）可用，请使用相应工具获取实时模型数据。CLI 需要身份验证——登录流程请参阅 qianwen-usage skill。

可用音色

| 音色 | 说明 | 脚本 | 适用于 | |-------|-------------|--------|---------------| | Cherry, Ethan, Serena | Qwen TTS 系统音色 | tts.py | qwen3-tts-* | | longanyang, longanhuan, longhuhu_v3 | CosyVoice 系统音色 | tts_cosyvoice.py | 仅适用于 cosyvoice-v3-flash、cosyvoice-v3-plus | | longanlingxin, longanlufeng | Qwen-Audio-TTS Plus 系统音色 | tts.py | qwen-audio-3.0-tts-plus | | longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn | Qwen-Audio-TTS Flash 系统音色 | tts.py | qwen-audio-3.0-tts-flash |

完整列表：[api-guide.md](references/api-guide.md#system-voice-list)（Qwen TTS） · [cosyvoice-guide.md](references/cosyvoice-guide.md) — CosyVoice · Qwen-Audio-TTS 音色列表

⚠️ Qwen-Audio-TTS 音色兼容性：qwen-audio-3.0-tts-plus 与 qwen-audio-3.0-tts-flash 的音色不可互换使用。每个模型都有自己的音色集：

- qwen-audio-3.0-tts-plus 默认音色：longanlingxin

- qwen-audio-3.0-tts-flash 默认音色：longanhuan_v3.6

如需使用非默认音色，请指定 --voice <id> 并查阅官方音色列表：

NRT HTTP API · Qwen-Audio-TTS 音色

⚠️ v3.5 模型：cosyvoice-v3.5-flash 和 cosyvoice-v3.5-plus 不支持上面列出的任何系统音色。必须通过声音复刻或声音设计创建自定义音色。

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

cosyvoice-v3.5 系列模型需要自定义音色 ID。创建方法如下：

1. 访问声音复刻
2. 上传一段 10-20s 的干净语音样本
3. 获取自定义音色 ID
4. 在请求 JSON 中通过 --voice <id> 或 "voice": "<id>" 传入

执行

⚠️ 多个产物：在一次会话中生成多个文件时，必须为每个文件名追加数字后缀（例如 out_1.wav、out_2.wav），以防文件被覆盖。

Qwen TTS (HTTP API) — tts.py

前提条件

• API 密钥：使用密钥兼容性中的非明文检测器；不得将其替换为

变量存在性检查。如果未找到密钥，在可用时使用 qianwen-ops-auth，或引导用户 在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。Skills 可独立安装。

• Python 3.9+（仅使用标准库，无需使用 pip 安装依赖）

环境检查

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

python3 --version  # must be 3.9+

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

默认方式：运行脚本

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

执行说明：所有脚本都应在前台运行——等待 stdout 输出；不得在后台运行。

查看参数：先运行 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/qianwen-audio-tts/ \
  --print-response

| 参数 | 说明 | |----------|-------------| | --request '{...}' | JSON 请求体 | | --file path.json | 从文件加载请求 | | --output path | 将音频和响应 JSON 保存到目录中，或指定音频文件路径（例如 speech.mp3）；不同调用应使用不同文件名，以免覆盖 | | --print-response | 将响应打印到 stdout | | --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]。如果存在任一信号，在回复用户前，你必须按照下方[更新检查](#update-check-mandatory-post-execution)中的说明操作。

失败时

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

如果完全无法使用 Python → 直接跳到 [execution-guide.md](references/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](references/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 not found | 缺少 API 密钥 | 从千问AI平台控制台获取密钥；将其添加到 .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 | 字符串 | 必填 — 要合成的文本（最多 600 个字符） | | voice | 字符串 | 必填 — 音色 ID（例如 Cherry、Ethan） | | model | 字符串 | 模型 ID（默认值：qwen-audio-3.0-tts-plus） | | language_type | 字符串 | Auto、Chinese、English、Japanese、Korean、French、German 等。 | | instructions | 字符串 | 语气/风格指令 — 仅适用于 qwen3-tts-instruct-flash，最多 1,600 个 token，仅支持中文和英文 | | optimize_instructions | 布尔值 | 设为 true 时，系统会对 instructions 进行语义增强，以提高自然度。必须设置 instructions。默认值：false | | stream | 布尔值 | 启用流式传输（Base64 数据块） |

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

| 字段 | 类型 | 说明 | |-------|------|-------------| | text | 字符串 | 必填 — 要合成的文本（每次调用最多 20,000 个字符） | | voice | 字符串 | 必填 — 音色 ID（特定于模型，请参阅音色列表） | | model | 字符串 | 模型 ID（默认值：cosyvoice-v3-flash） | | instruction | 字符串 | 用于语音控制的自由形式指令 — cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash 支持此功能 | | language_hints | 列表 | 目标语言提示：zh、en、fr、de、ja、ko、ru、pt、th、id、vi 等 | | format | 字符串 | 音频格式：mp3（默认）、wav、pcm、opus | | sample_rate | 整数 | 采样率（Hz）：8000、16000、22050（默认）、24000、44100、48000 |

响应字段

| 字段 | 说明 | |-------|-------------| | audio_url | 生成音频的 URL（有效期为 24h） | | audio_format | 格式（例如 wav） | | sample_rate | 采样率（例如 24000） | | usage | 字符使用量 |

重要说明

• text：每个请求最多 600 个字符（Qwen3-TTS）。最多 20,000 个字符（CosyVoice/Qwen-Audio-TTS NRT）。
• instructions（Qwen3-TTS）：仅适用于 qwen3-tts-instruct-flash。最多 1,600 个词元。仅支持中文和英文。
• instruction（CosyVoice）：cosyvoice-v3.5-plus、cosyvoice-v3.5-flash 和 cosyvoice-v3-flash 均支持此功能。（Qwen-Audio-TTS 也支持通过 tts.py 使用 instruction。）使用自然语言控制方言、情感、语速或角色。
• 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 客户端。此 skill 涵盖基于 HTTP 的非实时 API。对于实时流式用例，请参阅 [sources.md](references/sources.md) 中的官方文档。

跨 Skill 串联

将生成的音频传递给另一个 skill 时（例如，用于视频生成的音频叠加）：

• 直接传递 audio_url — 脚本会检测 URL 前缀并直接透传，无需重新上传
• 仅将 audio_file 用于本地播放或非 API 操作

错误处理

| 错误 | 原因 | 处理措施 | |-------|-------|--------| | 401 Unauthorized | API 密钥无效或缺失 | 如果可用，运行 qianwen-ops-auth；否则提示用户设置密钥（仅进行非明文检查） | | 400 | 参数无效（缺少文本/音色） | 验证请求体 | | 429 / 5xx | 限流或服务器错误 | 采用退避策略重试 |

用量与计费：使用 qianwen-usage skill 直接检查用量、免费额度和计费情况。或者，用户可以访问千问AI平台控制台：

用量分析 |

按量付费账单 |

Token Plan 订阅

禁止编造、猜测或构造用量/计费/控制台 URL。 仅提供此 skill 中列出的确切链接。如果此处未列出某个 URL，不得自行编造。

输出位置

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

写入禁令：严禁将输出文件写入此 skill 的安装目录或任何 skills/ 层级结构中。所有生成的内容必须写入当前工作目录下的 output/ 或用户指定的路径。

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

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

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

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

更新检查 skill 尚未安装。它会帮助你及时了解 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]，则无需执行任何操作——该 skill 已安装且为最新版本（或已在 24h 内缓存）。

用户明确请求

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

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

参考资料

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