跳转到主要内容
语音合成

非实时语音合成

使用 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 参数中指定指令。示例:"语速快,语调上扬明显,适合时尚产品介绍。" 支持的语言:仅中文和英文。 长度限制:最多 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 小时后过期。

了解更多