Back to Details

qwencloud-audio-tts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Agent setup: If your agent doesn't auto-load skills (e.g. Claude Code), see agent-compatibility.md once per session.
Agent 设置: 如果你的Agent不会自动加载技能（例如Claude Code）， 每次会话首次使用时请查看 agent-compatibility.md。

Qwen Audio TTS (Text-to-Speech)

Qwen Audio TTS (文本转语音)

Synthesize natural speech from text using Qwen TTS models. This skill is part of qwencloud/qwencloud-ai.
使用Qwen TTS模型将文本合成为自然语音。 本技能属于 qwencloud/qwencloud-ai 套件的一部分。

Skill directory

技能目录

Use this skill's internal files to execute and learn. Load reference files on demand when the default path fails or you need details.
LocationPurpose
scripts/tts.py
Qwen TTS (HTTP API) — qwen3-tts-flash, qwen3-tts-instruct-flash
scripts/tts_cosyvoice.py
CosyVoice (WebSocket API) — requires 
dashscope
SDK
references/cosyvoice-guide.md
CosyVoice setup, voices, examples, errors
references/execution-guide.md
Fallback: curl (standard, instruct, streaming), code generation
references/prompt-guide.md
Text formatting for speech, instructions templates, voice selection
references/api-guide.md
API supplement
references/sources.md
Official documentation URLs
references/agent-compatibility.md
Agent self-check: register skills in project config for agents that don't auto-load
使用此技能的内部文件执行操作和查阅说明。当默认路径失效或你需要详细信息时，按需加载参考文件。
位置用途
scripts/tts.py
Qwen TTS (HTTP API) — 支持qwen3-tts-flash、qwen3-tts-instruct-flash模型
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
官方文档链接
references/agent-compatibility.md
Agent自检：为不会自动加载技能的Agent在项目配置中注册技能

Security

安全说明

NEVER output any API key or credential in plaintext. Always use variable references (
$DASHSCOPE_API_KEY
in shell, 
os.environ["DASHSCOPE_API_KEY"]
in Python). Any check or detection of credentials must be non-plaintext: report only status (e.g. "set" / "not set", "valid" / "invalid"), never the value. Never display contents of 
.env
or config files that may contain secrets.
When the API key is not configured, NEVER ask the user to provide it directly. Instead, help create a 
.env
file with a placeholder (
DASHSCOPE_API_KEY=sk-your-key-here
) and instruct the user to replace it with their actual key from the QwenCloud Console. Only write the actual key value if the user explicitly requests it.
绝对不要明文输出任何API密钥或凭证。 请始终使用变量引用（Shell中用
$DASHSCOPE_API_KEY
，Python中用
os.environ["DASHSCOPE_API_KEY"]
）。任何凭证检查或检测都必须非明文：仅返回状态（例如"已设置"/"未设置"、"有效"/"无效"），绝不返回具体值。永远不要展示可能包含密钥的
.env
或配置文件内容。
当API密钥未配置时，绝对不要直接要求用户提供密钥。 而是帮助创建带占位符的
.env
文件（
DASHSCOPE_API_KEY=sk-your-key-here
），并指导用户将占位符替换为他们从QwenCloud控制台获取的实际密钥。仅当用户显式要求时才写入实际密钥值。

Key Compatibility

密钥兼容性

Scripts require a standard QwenCloud API key (
sk-...
). Coding Plan keys (
sk-sp-...
) cannot be used — TTS models are not available on Coding Plan, and Coding Plan does not support the native QwenCloud API. The script detects 
sk-sp-
keys at startup and prints a warning. If qwencloud-ops-auth is installed, see its 
references/codingplan.md
for full details.
脚本需要标准QwenCloud API密钥（
sk-...
格式）。编码方案密钥（
sk-sp-...
）无法使用——编码方案不支持TTS模型，也不支持原生QwenCloud API。脚本启动时会检测
sk-sp-
前缀的密钥并输出警告。如果安装了qwencloud-ops-auth技能，可查看其
references/codingplan.md
获取完整说明。

Model Selection

模型选择

Qwen TTS (HTTP API) — use 
scripts/tts.py

Qwen TTS (HTTP API) — 使用
scripts/tts.py

ModelUse CaseNotes
qwen3-tts-flash
Recommended (standard) — fast, multi-languageCost-effective, widely available
qwen3-tts-instruct-flash
Instruction-guided style controlTone/emotion via instructions
模型适用场景说明
qwen3-tts-flash
推荐通用款——速度快、支持多语言性价比高、覆盖区域广
qwen3-tts-instruct-flash
指令引导的风格控制通过指令调整语气/情绪

CosyVoice (WebSocket API) — use 
scripts/tts_cosyvoice.py

CosyVoice (WebSocket API) — 使用
scripts/tts_cosyvoice.py

ModelUse Case
cosyvoice-v3-flash
High quality, fast
cosyvoice-v3-plus
Highest quality
Note: CosyVoice requires 
dashscope
SDK and uses different voices. See cosyvoice-guide.md.
  1. User specified a model → use the appropriate script: 
    • qwen3-tts-*
      → 
      scripts/tts.py
    • cosyvoice-*
      → 
      scripts/tts_cosyvoice.py
  2. Consult the qwencloud-model-selector skill when model choice depends on capability, scenario, or pricing.
  3. No signal, clear task → 
    qwen3-tts-flash
    via 
    tts.py
    (default for standard tasks).
⚠️ Important: The model list above is a point-in-time snapshot and may be outdated. Model availability changes frequently. Always check the official model list for the authoritative, up-to-date catalog before making model decisions.
模型适用场景
cosyvoice-v3-flash
高质量、快速度
cosyvoice-v3-plus
最高质量
注意: CosyVoice需要
dashscope
SDK，且使用不同的音色库。请查看 cosyvoice-guide.md。
  1. 用户指定了模型 → 使用对应脚本： 
    • qwen3-tts-*
      → 
      scripts/tts.py
    • cosyvoice-*
      → 
      scripts/tts_cosyvoice.py
  2. 当模型选择取决于能力、场景或定价时，可调用qwencloud-model-selector技能辅助选择。
  3. 无明确指定需求、任务清晰 → 默认使用
    tts.py
    调用
    qwen3-tts-flash
    （通用任务默认选项）。
⚠️ 重要提示: 上述模型列表是当前时间点的快照，可能已过时。模型可用性会频繁更新。在确定模型选择前，请务必查阅官方模型列表获取权威、最新的目录。

Available Voices

可用音色

VoiceDescriptionScript
Cherry, Ethan, SerenaQwen TTS system voices
tts.py
longanyang, longanhuan, longhuhu_v3CosyVoice verified voices
tts_cosyvoice.py
Full lists: api-guide.md (Qwen TTS) · cosyvoice-guide.md (CosyVoice)
音色描述对应脚本
Cherry、Ethan、SerenaQwen TTS系统音色
tts.py
longanyang、longanhuan、longhuhu_v3CosyVoice官方认证音色
tts_cosyvoice.py
完整列表: api-guide.md（Qwen TTS）· cosyvoice-guide.md（CosyVoice）

Execution

执行说明

⚠️ Multiple artifacts: When generating multiple files in a single session, you MUST append a numeric suffix to each filename (e.g. 
out_1.wav
, 
out_2.wav
) to prevent overwrites.
⚠️ 多文件生成注意: 单个会话中生成多个文件时，你必须为每个文件名添加数字后缀（例如
out_1.wav
、
out_2.wav
），避免覆盖原有文件。

Qwen TTS (HTTP API) — 
tts.py

Qwen TTS (HTTP API) — 
tts.py

Prerequisites

前置要求

  • API Key: Check that 
    DASHSCOPE_API_KEY
    (or 
    QWEN_API_KEY
    ) is set using a non-plaintext check only (e.g. in shell: 
    [ -n "$DASHSCOPE_API_KEY" ]
    ; report only "set" or "not set", never the key value). If not set: run the qwencloud-ops-auth skill if available; otherwise guide the user to obtain a key from QwenCloud Console and set it via 
    .env
    file (
    echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
    in project root or current directory) or environment variable. The script searches for 
    .env
    in the current working directory and the project root. Skills may be installed independently — do not assume qwencloud-ops-auth is present.
  • Python 3.9+ (stdlib only, no pip install needed)
  • API密钥: 仅通过非明文方式检查
    DASHSCOPE_API_KEY
    （或
    QWEN_API_KEY
    ）是否已设置（例如Shell中执行
    [ -n "$DASHSCOPE_API_KEY" ]
    ；仅返回"已设置"或"未设置"，绝不返回密钥值）。如果未设置：如果有qwencloud-ops-auth技能则调用它；否则指导用户从QwenCloud控制台获取密钥，并通过
    .env
    文件（项目根目录或当前目录执行
    echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env
    ）或环境变量设置。脚本会在当前工作目录和项目根目录搜索
    .env
    文件。技能可能独立安装——不要默认qwencloud-ops-auth已安装。
  • Python 3.9+（仅需标准库，无需pip安装依赖）

Environment Check

环境检查

Before first execution, verify Python is available:
bash
python3 --version  # must be 3.9+
If 
python3
is not found, try 
python --version
or 
py -3 --version
. If Python is unavailable or below 3.9, skip to Path 2 (curl) in execution-guide.md.
首次执行前，验证Python可用：
bash
python3 --version  # 必须为3.9及以上版本
如果找不到
python3
，尝试
python --version
或
py -3 --version
。如果Python不可用或版本低于3.9，跳转至execution-guide.md中的路径2（curl）。

Default: Run Script

默认方式：运行脚本

Script path: Scripts are in the 
scripts/
subdirectory of this skill's directory (the directory containing this SKILL.md). You MUST first locate this skill's installation directory, then ALWAYS use the full absolute path to execute scripts. Do NOT assume scripts are in the current working directory. Do NOT use 
cd
to switch directories before execution.
Execution note: Run all scripts in the foreground — wait for stdout; do not background.
Discovery: Run 
python3 <this-skill-dir>/scripts/tts.py --help
first to see all available arguments.
bash
python3 <this-skill-dir>/scripts/tts.py \
  --request '{"text":"Hello, this is a test.","voice":"Cherry"}' \
  --output output/qwencloud-audio-tts/ \
  --print-response
ArgumentDescription
--request '{...}'
JSON request body
--file path.json
Load request from file
--output dir/
Save audio and response JSON to directory
--print-response
Print response to stdout
--model ID
Override model
--voice NAME
Override voice
脚本路径: 脚本位于本技能目录（包含此SKILL.md的目录）的
scripts/
子目录下。你必须先定位此技能的安装目录，然后始终使用完整绝对路径执行脚本。 不要假设脚本在当前工作目录下。执行前不要使用
cd
切换目录。
执行注意: 所有脚本都在前台运行——等待标准输出，不要后台运行。
参数查询: 先执行
python3 <本技能目录>/scripts/tts.py --help
查看所有可用参数。
bash
python3 <本技能目录>/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 dir/
将音频和响应JSON保存到指定目录
--print-response
将响应打印到标准输出
--model ID
覆盖默认模型
--voice NAME
覆盖默认音色

Verify Result

结果验证

  • Exit code 
    0
    + output contains valid JSON with 
    output.audio
    field → success
  • Non-zero exit, HTTP error, empty response, or error JSON → fail
  • Post-execution check: Verify the output audio file exists and has non-zero size (
    ls -la <output_dir>
    )
  • MANDATORY — stderr signal check: After confirming the result, scan the command's stderr output for 
    [ACTION_REQUIRED]
    or 
    [UPDATE_AVAILABLE]
    . If either signal is present, you MUST follow the instructions in Update Check below before responding to the user.
  • 退出码
    0
    + 输出包含带
    output.audio
    字段的有效JSON → 成功
  • 非零退出码、HTTP错误、空响应或错误JSON → 失败
  • 执行后检查: 验证输出音频文件存在且大小非零（执行
    ls -la <输出目录>
    ）
  • 强制要求——错误输出信号检查: 确认结果后，扫描命令的标准错误输出是否有
    [ACTION_REQUIRED]
    或
    [UPDATE_AVAILABLE]
    。如果存在任一信号，你必须先按照下方更新检查（执行后强制要求）的说明操作，再回复用户。

On Failure

失败处理

If the script fails, match the error output against the diagnostic table below to determine the resolution. If no match, read execution-guide.md for alternative paths: curl commands (Path 2 — standard, instruct, streaming), code generation (Path 3), and autonomous resolution (Path 5).
If Python is not available at all → skip directly to Path 2 (curl) in execution-guide.md.
如果脚本运行失败，将错误输出与下方诊断表匹配以确定解决方案。如果没有匹配项，查看execution-guide.md获取替代方案：curl命令（路径2——标准、指令版、流式）、代码生成（路径3）、自主解决（路径5）。
如果完全没有可用的Python环境 → 直接跳转至execution-guide.md中的路径2（curl）。

CosyVoice — 
tts_cosyvoice.py

CosyVoice — 
tts_cosyvoice.py

CosyVoice requires 
dashscope
SDK. Quick start:
bash
pip install dashscope>=1.24.6
python3 <this-skill-dir>/scripts/tts_cosyvoice.py --text "Hello"
Full guide: cosyvoice-guide.md (setup, voices, examples, errors)
Error PatternDiagnosisResolution
command not found: python3
Python not on PATHTry 
python
or 
py -3
; install Python 3.9+ if missing
Python 3.9+ required
Script version check failedUpgrade Python to 3.9+
SyntaxError
near type hints		Python < 3.9Upgrade Python to 3.9+
QWEN_API_KEY/DASHSCOPE_API_KEY not found
Missing API keyObtain key from QwenCloud Console; add to 
.env
: 
echo 'DASHSCOPE_API_KEY=sk-...' >> .env
; or run qwencloud-ops-auth if available
HTTP 401
Invalid or mismatched keyRun qwencloud-ops-auth (non-plaintext check only); verify key is valid
SSL: CERTIFICATE_VERIFY_FAILED
SSL cert issue (proxy/corporate)macOS: run 
Install Certificates.command
; else set 
SSL_CERT_FILE
env var
URLError
/ 
ConnectionError
Network unreachableCheck internet; set 
HTTPS_PROXY
if behind proxy
HTTP 429
Rate limitedWait and retry with backoff
HTTP 5xx
Server errorRetry with backoff
PermissionError
Can't write outputUse 
--output
to specify writable directory
CosyVoice需要
dashscope
SDK。快速开始：
bash
pip install dashscope>=1.24.6
python3 <本技能目录>/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及以上版本
QWEN_API_KEY/DASHSCOPE_API_KEY not found
缺失API密钥从QwenCloud控制台获取密钥；添加到
.env
：
echo 'DASHSCOPE_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
指定可写目录

Quick Reference

快速参考

Request Fields

请求字段

FieldTypeDescription
text
stringRequired — text to synthesize (max 600 chars)
voice
stringRequired — voice ID (e.g. 
Cherry
, 
Ethan
)
model
stringModel ID (default: 
qwen3-tts-flash
)
language_type
string
Auto
, 
Chinese
, 
English
, 
Japanese
, 
Korean
, 
French
, 
German
, etc.
instructions
stringTone/style instructions (instruct model only)
stream
boolEnable streaming (Base64 chunks)
字段类型描述
text
string必填——待合成文本（最多600字符）
voice
string必填——音色ID（例如
Cherry
、
Ethan
）
model
string模型ID（默认：
qwen3-tts-flash
）
language_type
string
Auto
、
Chinese
、
English
、
Japanese
、
Korean
、
French
、
German
等
instructions
string语气/风格指令（仅指令版模型支持）
stream
bool启用流式输出（Base64分片）

Response Fields

响应字段

FieldDescription
audio_url
URL of generated audio (valid 24h)
audio_format
Format (e.g. wav)
sample_rate
Sample rate (e.g. 24000)
usage
Character usage
字段描述
audio_url
生成音频的URL（24小时内有效）
audio_format
格式（例如wav）
sample_rate
采样率（例如24000）
usage
字符使用量

Important Notes

重要说明

  • text: Max 600 characters per request.
  • instructions: Only works with 
    qwen3-tts-instruct-flash
    .
  • language_type: 
    Auto
    for mixed language; specify for better pronunciation.
  • audio_url: Valid for 24 hours — download promptly.
  • Real-time/streaming TTS: For WebSocket-based real-time TTS (CosyVoice, qwen3-tts-flash-realtime), a WebSocket client is required. This skill covers the HTTP-based non-real-time API. For real-time streaming use cases, refer to the official docs in sources.md.
  • text: 单次请求最多600字符。
  • instructions: 仅支持
    qwen3-tts-instruct-flash
    模型。
  • language_type: 混合语言使用
    Auto
    ；指定语言可获得更好的发音效果。
  • audio_url: 24小时内有效——请及时下载。
  • 实时/流式TTS: 基于WebSocket的实时TTS（CosyVoice、qwen3-tts-flash-realtime）需要WebSocket客户端。本技能覆盖基于HTTP的非实时API。实时流式使用场景请参考sources.md中的官方文档。

Cross-Skill Chaining

跨技能联动

When passing generated audio to another skill (e.g., video-gen audio overlay):
  • Pass 
    audio_url
    directly     — scripts detect URL prefixes and pass through without re-upload
  • Use 
    audio_file
    only for local playback or non-API operations
将生成的音频传递给其他技能时（例如视频生成的音频叠加）：
  • 直接传递
    audio_url
    ——脚本会自动识别URL前缀，无需重新上传
  • 仅在本地播放或非API操作时使用
    audio_file

Error Handling

错误处理

ErrorCauseAction
401 Unauthorized
Invalid or missing API keyRun qwencloud-ops-auth if available; else prompt user to set key (non-plaintext check only)
400
Invalid parameters (missing text/voice)Validate request body
429
/ 
5xx
Rate limit or server errorRetry with backoff
错误原因处理方式
401 Unauthorized
API密钥无效或缺失如果有qwencloud-ops-auth则调用它；否则提示用户设置密钥（仅做非明文检查）
400
参数无效（缺失text/voice字段）校验请求体
429
/ 
5xx
频率限制或服务端错误指数退避后重试

Output Location

输出位置

Prefer the current working directory. Default subdirectory: 
./output/qwencloud-audio-tts/
.
Write prohibition: NEVER write output files into this skill's installation directory or any 
skills/
hierarchy. All generated content must go to 
output/
under the current working directory or a user-specified path.
优先使用当前工作目录。默认子目录：
./output/qwencloud-audio-tts/
。
写入禁止: 绝对不要将输出文件写入本技能的安装目录或任何
skills/
层级下。所有生成内容必须存放在当前工作目录下的
output/
目录或用户指定的路径。

Update Check (MANDATORY Post-Execution)

更新检查（执行后强制要求）

After script execution, check stderr for action signals. The script automatically detects update status and emits structured signals. You MUST act on them. This section also applies when the user explicitly asks to check for updates.
脚本执行后，检查标准错误输出中的动作信号。脚本会自动检测更新状态并输出结构化信号。你必须按要求处理。当用户显式要求检查更新时，本节内容也适用。

Signal: 
[ACTION_REQUIRED] qwencloud-update-check skill is not installed

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

When stderr contains this signal, you MUST present the following options to the user and wait for their response before proceeding. Do NOT silently skip this.
The update-check skill is not installed. It keeps you informed about new qwencloud/qwencloud-ai features and bug fixes.
  1. Install now — I'll run the install command for you
  2. Skip for now — do nothing this time
  3. Never remind me — permanently suppress this prompt
After the user responds:
  • User chooses 1 → run: 
    npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y
    , then run: 
    python3 <this-skill-scripts-dir>/gossamer.py --dismiss
  • User chooses 2 → run: 
    python3 <this-skill-scripts-dir>/gossamer.py --dismiss
    , then continue normally
  • User chooses 3 → run: 
    python3 <this-skill-scripts-dir>/gossamer.py --never-install
    , then continue normally
当标准错误输出包含此信号时，你必须向用户提供以下选项，等待用户回复后再继续操作，不要静默跳过。
更新检查技能未安装。它会及时通知你qwencloud/qwencloud-ai的新功能和bug修复。
  1. 立即安装——我会为你执行安装命令
  2. 本次跳过——暂时不做操作
  3. 永不提醒——永久关闭此提示
用户回复后：
  • 用户选择1 → 执行：
    npx skills add QwenCloud/qwencloud-ai --skill qwencloud-update-check -y
    ，然后执行：
    python3 <本技能脚本目录>/gossamer.py --dismiss
  • 用户选择2 → 执行：
    python3 <本技能脚本目录>/gossamer.py --dismiss
    ，然后正常继续
  • 用户选择3 → 执行：
    python3 <本技能脚本目录>/gossamer.py --never-install
    ，然后正常继续

Signal: 
[UPDATE_AVAILABLE]

信号：
[UPDATE_AVAILABLE]

When stderr contains this signal, you MUST append a brief update notice to your response, including the version info and the update command shown in the stderr output.
当标准错误输出包含此信号时，你必须在回复末尾附加简短的更新通知，包含标准错误输出中显示的版本信息和更新命令。

No signal in stderr

标准错误输出无信号

If stderr contains neither 
[ACTION_REQUIRED]
nor 
[UPDATE_AVAILABLE]
, no action is needed — the skill is installed and up to date (or cached within 24h).
如果标准错误输出既没有
[ACTION_REQUIRED]
也没有
[UPDATE_AVAILABLE]
，无需额外操作——技能已安装且为最新版本（或24小时内已缓存检查结果）。

Explicit user request

用户显式请求

When the user explicitly asks to check for updates (e.g. "check for updates", "check version"):
  1. Look for 
    qwencloud-update-check/SKILL.md
    in sibling skill directories.
  2. If found — run: 
    python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response
    and report the result.
  3. If not found — present the install options above.
当用户显式要求检查更新时（例如"检查更新"、"查看版本"）：
  1. 在同级技能目录中查找
    qwencloud-update-check/SKILL.md
    。
  2. 如果找到——执行：
    python3 <qwencloud-update-check目录>/scripts/check_update.py --print-response
    并报告结果。
  3. 如果未找到——提供上述安装选项。

References

参考文档

  • execution-guide.md — Fallback paths (curl standard/instruct/streaming, code generation, autonomous)
  • api-guide.md — API supplementary guide
  • sources.md — Official documentation URLs
  • execution-guide.md — 备用方案（curl标准/指令/流式、代码生成、自主解决）
  • api-guide.md — API补充指南
  • sources.md — 官方文档链接