跳转到主要内容
语音合成

非实时语音合成

使用 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)

使用设计音色

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

情感与富语言标签

Qwen-Audio-TTS 系列模型支持在待合成文本(text 参数)中直接嵌入情感与富语言标签,用于控制语音的情感表达或在指定位置插入拟声效果(如笑声、叹息等),无需调整复杂的音频参数即可生成更具表现力的语音。
支持的模型:仅 qwen-audio-3.0-tts-plusqwen-audio-3.0-tts-flash
控制类标签 控制类标签用于设定语音的情感或风格。将标签写在文本中,标签会作用于其后的所有文本,直到遇到下一个控制类标签,或因句子较长被自动切分为止。
标签说明
[sad]悲伤
[amazed]惊叹
[deep and loud shouting]深沉大声呐喊
[trembling]颤抖
[angry]愤怒
[excited]兴奋
[sarcastic]讽刺
[curious]好奇
[like dracula]德古拉风格(低沉、阴森)
[bored]无聊
[tired]疲惫
[singing]唱歌
[scornful]轻蔑
[shouting]大喊
[asmr]ASMR 轻柔耳语
[panicked]恐慌
[mischievously]调皮
[empathetic]共情
[whispers]耳语
[reluctantly]不情愿
[crying]哭泣
[serious]严肃
[very slowly]非常缓慢地说话
[very fast]非常快速地说话
富语言类标签 富语言类标签用于在文本的当前位置插入一段拟声效果,不影响前后文本的情感风格。
标签说明
[gasp]倒吸一口气
[sighing]叹息
[clears throat]清嗓
[giggles]咯咯笑
[laughing]大笑
[cough]咳嗽
[snorts]哼声、嗤笑
使用示例 以下示例展示如何在 text 参数中组合使用控制类标签和富语言类标签: [excited]今天的天气真不错![laughing]我们一起出去玩吧! 上述文本中,[excited] 是控制类标签,作用于其后的所有文本,使语音带有兴奋的情感;[laughing] 是富语言类标签,在该位置插入一段笑声效果后继续合成后续文本。 您也可以在同一段文本中切换不同情感: [serious]请注意安全事项。[excited]好了,现在让我们开始吧! 其中 [serious] 控制第一句为严肃语气,[excited] 从第二句起切换为兴奋语气。

文本预处理建议

cosyvoice-v3-flash 在合成包含点号(·)分隔数字段的文本时,可能出现漏读或重复念读的情况,例如连续的房号可能被读错。 将文本中的点号(·)替换为中文逗号(,)可规避该问题:
  • 原文:主楼五楼·501房是PU·502房是OOO
  • 预处理后:主楼五楼501房是PU,502房是OOO
此为模型层已知限制,仅在 cosyvoice-v3-flash 上确认,cosyvoice-v2 经交叉验证无此问题,不适用于 CosyVoice 其他型号或其他模型系列。在模型优化完成前,建议在代码侧对待合成文案统一做该预处理。

方言

本节介绍如何让模型用中文方言(如河南话、四川话等)输出语音。不同模型和音色类型的设置方式不同。 Qwen-Audio-TTS
  • 系统音色:在 Qwen-Audio-TTS 音色列表 中选择以下任一种音色:
    • 支持方言的系统音色,无需额外设置即可输出对应方言。
    • 支持指令控制且可指定方言的音色,通过指令文本指定方言。
  • 声音复刻音色:通过指令控制功能设置,例如指令文本写 请用河南话表达
  • 声音设计音色:暂不支持方言。
具体支持哪些方言:参见 Qwen-Audio-TTS 中各模型的语言支持说明。 CosyVoice
  • 系统音色:在 CosyVoice 音色列表 中选择以下任一种音色:
    • 支持方言的系统音色(例如 longshange_v3),无需额外设置即可输出对应方言。
    • 支持指令控制且可指定方言的音色(例如 longanhuan_v3),通过指令文本指定方言。
  • 声音复刻音色:通过指令控制功能设置,例如指令文本写 请用河南话表达
  • 声音设计音色:暂不支持方言。
具体支持哪些方言:参见 CosyVoice 中各模型的语言支持说明。 示例:以 cosyvoice-v3-flash + longanhuan_v3 音色,通过指令文本 "请用河南话表达。" 输出河南话语音。
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "叫你去买盐,你买回来一袋面,这不是弄啥嘞吗!",
      "voice": "longanhuan_v3",
      "format": "wav",
      "sample_rate": 24000,
      "instruction": "请用河南话表达。"
    }
}'
Qwen-TTS
  • 系统音色:使用支持方言的系统音色,参见 Qwen-TTS 音色列表
  • 声音复刻音色:不支持方言。
  • 声音设计音色:不支持方言。
具体支持哪些方言:参见 Qwen3-TTS 中各模型的语言支持说明。

自定义音色

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

API 参考

系统音色

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

常见问题

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

了解更多