跳转到主要内容
语音合成

非实时语音合成

使用 Qwen3-TTS、CosyVoice 和 MiniMax 进行非实时语音合成

非实时语音合成通过 HTTP API 将文本转换为语音,适用于有声读物、课件配音、内容生产等对延迟不敏感的场景。支持 Qwen-TTS、CosyVoice 和 MiniMax 多种模型系列,提供丰富音色、多语言支持、声音复刻与声音设计等能力。

支持的模型

调用以下模型时需使用 API key
  • Qwen3-TTS-Instruct-Flash
  • Qwen3-TTS-VD
  • Qwen3-TTS-VC
  • Qwen3-TTS-Flash
  • cosyvoice-v3-plus
  • cosyvoice-v3-flash
  • MiniMax(MiniMax-Speech-02-HD)
模型 ID 和快照版本详见语音合成模型
CosyVoice 使用 DashScope WebSocket SDK(dashscope.audio.tts_v2 中的 SpeechSynthesizer),而非 Qwen3-TTS 所用的 HTTP REST API。如需使用 CosyVoice 进行实时流式合成,请参见实时语音合成

快速开始

  • Qwen3-TTS
  • CosyVoice
前提条件
在 DashScope Python SDK 中,SpeechSynthesizer 接口已替换为 MultiModalConversation。升级时只需替换接口名称,其他参数完全兼容。

使用系统音色

使用系统音色进行语音合成。非流式输出通过返回的 url 获取合成后的音频文件,该 URL 有效期为 24 小时。Java 需要导入 Gson 依赖。如果使用 Maven 或 Gradle,按如下方式添加依赖:
  • Maven
  • Gradle
pom.xml 中添加以下内容:
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.13.1</version>
</dependency>
import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

text = "Today is a wonderful day to build something people love!"
# 使用 SpeechSynthesizer 接口:dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
  # 如需使用指令控制,请将模型替换为 qwen3-tts-instruct-flash。
  model="qwen3-tts-flash",
  # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  text=text,
  voice="Cherry",
  language_type="English", # 建议与文本语言保持一致,以确保发音正确、语调自然。
  # 如需使用指令控制,请取消以下注释,并将模型替换为 qwen3-tts-instruct-flash。
  # instructions='Speak quickly with a noticeable rising intonation, suitable for introducing fashion products.',
  # optimize_instructions=True,
  stream=False
)
print(response)
流式输出以 Base64 格式流式输出音频数据。最后一个数据包包含完整音频文件的 URL。
# coding=utf-8
#
# pyaudio 安装说明:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   或
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import os
import dashscope
import pyaudio
import time
import base64
import numpy as np

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

p = pyaudio.PyAudio()
# 创建音频流
stream = p.open(format=pyaudio.paInt16,
        channels=1,
        rate=24000,
        output=True)


text = "Today is a wonderful day to build something people love!"
response = dashscope.MultiModalConversation.call(
  # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # 如需使用指令控制,请将模型替换为 qwen3-tts-instruct-flash。
  model="qwen3-tts-flash",
  text=text,
  voice="Cherry",
  language_type="English", # 建议与文本语言保持一致,以确保发音正确、语调自然。
  # 如需使用指令控制,请取消以下注释,并将模型替换为 qwen3-tts-instruct-flash。
  # instructions='Speak quickly with a noticeable rising intonation, suitable for introducing fashion products.',
  # optimize_instructions=True,
  stream=True
)

for chunk in response:
  if chunk.output is not None:
      audio = chunk.output.audio
      if audio.data is not None:
          wav_bytes = base64.b64decode(audio.data)
          audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
          # 直接播放音频数据
          stream.write(audio_np.tobytes())
      if chunk.output.finish_reason == "stop":
          print("finish at: {} ", chunk.output.audio.expires_at)
time.sleep(0.8)
# 清理资源
stream.stop_stream()
stream.close()
p.terminate()

使用克隆音色

声音克隆不提供预览音频。将克隆音色应用于语音合成后才能评估效果。以下示例基于非流式输出代码,将 voice 参数替换为克隆音色。
  • 关键原则:声音克隆所用的模型(target_model)必须与语音合成所用的模型(model)一致,否则合成将失败。
  • 本示例使用本地音频文件 voice.mp3 进行声音克隆,运行代码时请替换该路径。
Java 需要添加 Gson 依赖。如果使用 Maven 或 Gradle,按如下方式添加依赖:
  • Maven
  • Gradle
pom.xml 中添加以下内容:
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.13.1</version>
</dependency>
使用声音克隆生成的自定义音色进行语音合成时,请按如下方式设置 voice 参数:
MultiModalConversationParam param = MultiModalConversationParam.builder()
        .parameter("voice", "your_voice") // 将 voice 参数替换为克隆生成的自定义音色
        .build();
import os
import requests
import base64
import pathlib
import dashscope

# ======= 常量配置 =======
DEFAULT_TARGET_MODEL = "qwen3-tts-vc-2026-01-22"  # 声音克隆和语音合成使用同一模型
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # 用于声音克隆的本地音频文件相对路径


def create_voice(file_path: str,
                 target_model: str = DEFAULT_TARGET_MODEL,
                 preferred_name: str = DEFAULT_PREFERRED_NAME,
                 audio_mime_type: str = DEFAULT_AUDIO_MIME_TYPE) -> str:
  """
  创建音色并返回 voice 参数。
  """
  # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
  api_key = os.getenv("DASHSCOPE_API_KEY")

  file_path_obj = pathlib.Path(file_path)
  if not file_path_obj.exists():
    raise FileNotFoundError(f"音频文件不存在:{file_path}")

  base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
  data_uri = f"data:{audio_mime_type};base64,{base64_str}"

  url = "https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization"
  payload = {
    "model": "qwen-voice-enrollment", # 请勿修改此值
    "input": {
      "action": "create",
      "target_model": target_model,
      "preferred_name": preferred_name,
      "audio": {"data": data_uri}
    }
  }
  headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
  }

  resp = requests.post(url, json=payload, headers=headers)
  if resp.status_code != 200:
    raise RuntimeError(f"创建音色失败:{resp.status_code}, {resp.text}")

  try:
    return resp.json()["output"]["voice"]
  except (KeyError, ValueError) as e:
    raise RuntimeError(f"解析音色响应失败:{e}")


if __name__ == '__main__':
  dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

  text = "How's the weather today?"
  # 使用 SpeechSynthesizer 接口:dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
  response = dashscope.MultiModalConversation.call(
    model=DEFAULT_TARGET_MODEL,
    # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    text=text,
    voice=create_voice(VOICE_FILE_PATH), # 将 voice 参数替换为克隆生成的自定义音色
    stream=False
  )
  print(response)
客户端与工具

Claude Code

在 Claude Code 中使用千问云模型

安装 Claude Code

  • macOS/Linux
  • Windows
  1. 安装或更新 Node.js(v18.0 或更高版本)。
  2. 在终端中执行下列命令,安装 Claude Code。
npm install -g @anthropic-ai/claude-code
  1. 运行以下命令验证安装。若有版本号输出,则表示安装成功。
claude --version

配置 Token Plan 团队版

在 Claude Code 中接入 Token Plan 团队版,需要配置以下信息:
  • ANTHROPIC_BASE_URL:设置为 https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
  • ANTHROPIC_AUTH_TOKEN:设置为 Token Plan 团队版专属 API Key。
  • ANTHROPIC_MODEL:设置为 Token Plan 团队版支持的模型。
  • macOS/Linux
  • Windows
  1. 创建并打开配置文件 ~/.claude/settings.json
~ 代表当前系统账户的主目录。如果 .claude 目录不存在,需要先行创建。可在终端执行 mkdir -p ~/.claude 来创建。
nano ~/.claude/settings.json
  1. 编辑配置文件。将 YOUR_API_KEY 替换为 Token Plan 团队版专属 API Key。
{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.7-max",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.7-max",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-max",
        "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-max"
    }
}
保存配置文件,重新打开一个终端即可生效。
  1. 编辑或新增 ~/.claude.json 文件,将 hasCompletedOnboarding 字段的值设置为 true 并保存文件。
{
  "hasCompletedOnboarding": true
}
hasCompletedOnboarding 作为顶层字段,请勿嵌套于其他字段。该步骤可避免启动 Claude Code 时报错:Unable to connect to Anthropic services

配置按量计费

YOUR_API_KEY 替换为千问云 API Key。可用模型请参考支持的模型
配置项说明
Base URLhttps://dashscope.aliyuncs.com/apps/anthropic
API Key千问云 API Key(格式为 sk-xxxxx
可用模型支持的模型
创建或编辑 ~/.claude/settings.json(Windows 路径:C:\Users\<用户名>\.claude\settings.json),写入以下配置:
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_MODEL": "qwen3.7-max",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.7-max",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-max",
    "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-max"
  }
}
配置保存后,新开一个终端窗口执行 claude "你好"。若模型正常返回响应,配置成功。如需进一步确认,在 Claude Code 中执行 /status,检查 ANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN 是否正确指向千问云地址。

使用 CC Switch

CC Switch 是社区开源的桌面 GUI,可在多个 API Key 或计费方案之间一键切换,免去手动改 settings.json

安装

  • macOS:brew tap farion1231/ccswitch && brew install --cask cc-switch,或从 Releases 下载 .dmg
  • Windows:从 Releases 下载 .msi 安装包或便携版 .zip
  • Linux:Arch 用 paru -S cc-switch-bin;其他发行版从 Releases 下载 .deb / .rpm / .AppImage

添加供应商

  1. 在 CC Switch 主界面顶部图标栏选中 Claude Code 橙色星形图标,点击右上角 + 进入添加新供应商,按下表填入配置后点击添加
计费方案配置信息
Token Plan 团队版供应商名称:千问云-Token Plan
API Key:控制台获取
请求地址:https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
按量计费供应商名称:千问云-按量计费
API Key:控制台获取
请求地址:https://dashscope.aliyuncs.com/apps/anthropic
  1. 展开高级选项配置模型映射,将主模型与 Haiku、Sonnet、Opus 默认模型填为对应方案支持的模型。具体映射关系按需选择,例如:
    • 主模型:qwen3.7-max
    • Haiku 默认模型:qwen3.6-flash
    • Sonnet 默认模型:qwen3.7-max
    • Opus 默认模型:qwen3.7-max
  2. 回到主界面,点击该供应商右侧启用按钮,然后新开一个 Claude Code 会话使配置生效。

接入 Claude Code 桌面版

  1. Claude 下载页安装 Claude Code 桌面版。
  2. 顶部菜单 HelpTroubleshootingEnable Developer Mode,重启后顶部出现 Developer 菜单。
  3. DeveloperConfigure Third-Party InferenceConnectionGateway,按下表填写后点击 Apply locally
字段填写
Gateway base URLCC Switch 路由监听地址,默认 http://127.0.0.1:15721,如已修改则与下一步保持一致。
Gateway API key千问云 API Key
Gateway auth schemebearer
Model listModel ID 须为 Anthropic 风格,如 claude-opus-4.7。实际调用模型由 CC Switch 路由决定,对应关系即供应商高级选项中的模型映射。Display name 仅影响下拉显示。
  1. CC Switch 左上角设置 → 路由,开启路由总开关,监听地址默认 127.0.0.1:15721,如需修改请同步上一步。
  2. 在桌面版模型下拉选择已配置的模型 ID 即可使用。

使用 Claude Code

  1. 打开终端,并进入项目所在的目录。运行以下命令启动 Claude Code:
cd path/to/your_project
claude
  1. 启动后,需要授权 Claude Code 执行文件。
  2. 输入 /status 确认模型、Base URL、API Key 是否配置正确。
  3. 在 Claude Code 中对话。

切换模型

  • 启动 Claude Code 时切换:在终端执行 claude --model <模型名称> 指定模型并启动 Claude Code,例如 claude --model qwen3.7-max
  • 会话期间:在对话框输入 /model <模型名称> 命令切换模型,例如 /model qwen3.7-max

接入图像生成模型

通过 Claude Code 的斜杠命令(Slash Command),可以调用 Token Plan 团队版的图像生成模型(qwen-image-2.0、wan2.7-image 等)。

使用设计音色

声音设计会返回预览音频。请先试听预览确认效果满意后再用于合成,以降低成本。
1

生成自定义音色并预览效果

如果对效果满意,请继续下一步;否则,请重新生成。Java 需要导入 Gson 依赖。如果使用 Maven 或 Gradle,按如下方式添加依赖:
  • Maven
  • Gradle
pom.xml 中添加以下内容:
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.13.1</version>
</dependency>
使用声音设计生成的自定义音色进行语音合成时,必须按如下方式设置 voice 参数:
MultiModalConversationParam param = MultiModalConversationParam.builder()
        .parameter("voice", "your_voice") // 将 voice 参数替换为声音设计生成的自定义音色
        .build();
import requests
import base64
import os

def create_voice_and_play():
  # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
  api_key = os.getenv("DASHSCOPE_API_KEY")

  if not api_key:
    print("错误:未找到 DASHSCOPE_API_KEY 环境变量,请先设置 API key。")
    return None, None, None

  # 准备请求数据
  headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
  }

  data = {
    "model": "qwen-voice-design",
    "input": {
      "action": "create",
      "target_model": "qwen3-tts-vd-2026-01-26",
      "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
      "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
      "preferred_name": "announcer",
      "language": "en"
    },
    "parameters": {
      "sample_rate": 24000,
      "response_format": "wav"
    }
  }

  url = "https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization"

  try:
    # 发送请求
    response = requests.post(
      url,
      headers=headers,
      json=data,
      timeout=60  # 添加超时设置
    )

    if response.status_code == 200:
      result = response.json()

      # 获取音色名称
      voice_name = result["output"]["voice"]
      print(f"音色名称:{voice_name}")

      # 获取预览音频数据
      base64_audio = result["output"]["preview_audio"]["data"]

      # 解码 Base64 音频数据
      audio_bytes = base64.b64decode(base64_audio)

      # 将音频文件保存到本地
      filename = f"{voice_name}_preview.wav"

      # 将音频数据写入本地文件
      with open(filename, 'wb') as f:
        f.write(audio_bytes)

      print(f"音频已保存到本地文件:{filename}")
      print(f"文件路径:{os.path.abspath(filename)}")

      return voice_name, audio_bytes, filename
    else:
      print(f"请求失败,状态码:{response.status_code}")
      print(f"响应内容:{response.text}")
      return None, None, None

  except requests.exceptions.RequestException as e:
    print(f"网络请求出错:{e}")
    return None, None, None
  except KeyError as e:
    print(f"响应数据格式错误,缺少必需字段:{e}")
    print(f"响应内容:{response.text if 'response' in locals() else '无响应'}")
    return None, None, None
  except Exception as e:
    print(f"发生未知错误:{e}")
    return None, None, None

if __name__ == "__main__":
  print("开始创建音色...")
  voice_name, audio_data, saved_filename = create_voice_and_play()

  if voice_name:
    print(f"\n成功创建音色 '{voice_name}'")
    print(f"音频文件已保存为:'{saved_filename}'")
    print(f"文件大小:{os.path.getsize(saved_filename)} 字节")
  else:
    print("\n音色创建失败")
2

使用自定义音色进行语音合成

使用上一步生成的自定义音色进行非流式语音合成。本示例基于非流式输出代码,将 voice 参数替换为声音设计生成的自定义音色。如需流式合成,请参见快速开始关键原则:声音设计所用的模型(target_model)必须与后续语音合成所用的模型(model)一致,否则合成将失败。
import os
import dashscope


if __name__ == '__main__':
  dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

  text = "How is the weather today?"
  response = dashscope.MultiModalConversation.call(
    model="qwen3-tts-vd-2026-01-26",
    # 如未配置环境变量,请将下行替换为:api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    text=text,
    voice="myvoice", # 将 voice 参数替换为声音设计生成的自定义音色
    stream=False
  )
  print(response)

指令控制

通过自然语言指令控制音高、语速、情感和音色,无需调整音频参数。 支持的模型:仅 Qwen3-TTS-Instruct-Flash 系列。 使用方式:在 instructions 参数中指定指令。示例:"语速快,语调上扬明显,适合时尚产品介绍。" 支持的语言:仅中文和英文。 长度限制:最多 1600 个 Token。 适用场景
  • 有声书和广播剧配音
  • 广告和宣传视频配音
  • 游戏角色和动画配音
  • 情感智能语音助手
  • 纪录片和新闻播报
编写高质量音色描述 核心原则
  1. 具体明确:使用"低沉"、"清脆"、"快节奏"等描述性词汇,避免使用"好听"、"正常"等模糊词汇。
  2. 多维描述:结合音高、语速、情感等多个维度,避免仅使用"高音"等单一维度描述。
  3. 客观描述:聚焦物理和感知特征,而非个人喜好。使用"高亢有力"而非"我最喜欢的声音"。
  4. 原创描述:描述声音特质,不要要求模仿特定人物。模型不支持直接模仿。
  5. 简洁精炼:确保每个词都有意义,避免重复的近义词或无意义的修饰词。
维度描述参考:可组合多个维度,创造更丰富的音频效果。
维度示例
音高高、中、低、高亢、低沉
语速快、中、慢、快节奏、慢节奏
情感欢快、平静、温柔、严肃、活泼、沉稳、舒缓
特征磁性、清脆、沙哑、醇厚、甜美、深沉、有力
用途新闻播报、广告配音、有声书、动画角色、语音助手、纪录片旁白
示例
  • 标准播报风格:吐字清晰准确,字正腔圆。
  • 渐进情绪效果:音量从正常对话迅速提升到大喊,性格直爽、容易激动,情绪表达丰富。
  • 特殊情绪状态:抽泣的语气导致发音略微含糊沙哑,哭腔中带有明显的紧张感。
  • 广告配音风格:音调高、语速适中、充满活力和感染力,适合广告配音。
  • 温柔舒缓风格:语速缓慢,音调温柔甜美,语气舒缓温暖,如同关心你的朋友。

自定义音色

Qwen3-TTS 支持声音克隆(Qwen3-TTS-VC)和声音设计(Qwen3-TTS-VD)。API 参考请参见声音克隆 (Qwen)声音设计 (Qwen)

API 参考

系统音色

支持的音色清单、模型兼容性与试听见 Qwen-TTS 音色列表

常见问题

Q:音频文件 URL 的有效期是多久? 音频文件 URL 在 24 小时后过期。

了解更多