非实时语音合成通过HTTP API将文本转换为语音,适用于有声书制作、在线教育配音、内容制作等对延迟要求不高的场景,支持丰富音色、多语言、声音复刻与声音设计。
通过HTTP API将完整文本转换为语音文件,支持非流式和流式两种输出模式。
- 非流式返回音频文件 URL,有效期 24 小时;流式逐段返回音频数据。
- 支持多种语言,含中文方言。
- 支持声音复刻与声音设计进行定制音色创建。
- 支持指令控制,通过自然语言指令控制语音表现力。
低延迟流式场景请参见实时语音合成。各模型选型建议请参见语音合成。
百炼控制台声音设计页面合成的语音仅支持在线试听,无法下载音频文件。如需下载音频,请通过 API 或 SDK 调用,非流式模式下响应中返回音频 URL,有效期 24 小时。
前提条件
开始前,请确认已完成以下准备工作:
快速开始
以下各 Tab 分别演示不同模型系列的语音合成。更多语言示例和详细参数说明,请参见API 参考。
本节所有示例均使用系统音色。非流式模式下,响应中包含 url 字段,指向合成的音频文件。URL 有效期为 24 小时。import os
import dashscope
# 以下为新加坡地域的配置。
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
text = "Today is a wonderful day to build something people love!"
# 接口使用方法:dashscope.MultiModalConversation.call(...)
response = dashscope.MultiModalConversation.call(
# 如需使用指令控制功能,请将model替换为qwen3-tts-instruct-flash
model="qwen3-tts-flash",
# 新加坡地域和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
text=text,
voice="Cherry",
language_type="English", # 建议与文本语种一致,以获得正确的发音和自然的语调。
# 如需使用指令控制功能,请取消下方注释,并将model替换为qwen3-tts-instruct-flash
# instructions='语速较快,带有明显的上扬语调,适合介绍时尚产品。',
# optimize_instructions=True,
stream=False
)
print(response)
需要导入 Gson 依赖,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>
在build.gradle中添加:// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.URL;
public class Main {
// 如需使用指令控制功能,请将MODEL替换为qwen3-tts-instruct-flash
private static final String MODEL = "qwen3-tts-flash";
public static void call() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡地域和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(MODEL)
.text("Today is a wonderful day to build something people love!")
.voice(AudioParameters.Voice.CHERRY)
.parameter("language_type", "English") // 建议与文本语种一致,以获得正确的发音和自然的语调。
// 如需使用指令控制功能,请取消下方注释,并将model替换为qwen3-tts-instruct-flash
// .parameter("instructions","语速较快,带有明显的上扬语调,适合介绍时尚产品。")
// .parameter("optimize_instructions",true)
.build();
MultiModalConversationResult result = conv.call(param);
String audioUrl = result.getOutput().getAudio().getUrl();
System.out.print(audioUrl);
// 下载音频文件到本地
try (InputStream in = new URL(audioUrl).openStream();
FileOutputStream out = new FileOutputStream("downloaded_audio.wav")) {
byte[] buffer = new byte[1024];
int bytesRead;
while ((bytesRead = in.read(buffer)) != -1) {
out.write(buffer, 0, bytesRead);
}
System.out.println("\n音频文件已下载到本地:downloaded_audio.wav");
} catch (Exception e) {
System.out.println("\n下载音频文件时出错:" + e.getMessage());
}
}
public static void main(String[] args) {
// 以下为新加坡地域的配置。
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
# ======= 重要提示 =======
# 以下为新加坡地域的配置。
# 新加坡地域和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
curl -X POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Today is a wonderful day to build something people love!",
"voice": "Cherry",
"language_type": "English"
}
}'
流式模式下,音频数据以 Base64 编码的 PCM 格式逐段返回,最后一个数据包中包含完整音频的 URL。# coding=utf-8
#
# Installation instructions for pyaudio:
# APPLE Mac OS X
# brew install portaudio
# pip install pyaudio
# Debian/Ubuntu
# sudo apt-get install python-pyaudio python3-pyaudio
# or
# 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-intl.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不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 如需使用指令控制功能,请将model替换为qwen3-tts-instruct-flash
model="qwen3-tts-flash",
text=text,
voice="Cherry",
language_type="English", # 建议与文本语种一致,以获得正确的发音和自然的语调。
# 如需使用指令控制功能,请取消下方注释,并将model替换为qwen3-tts-instruct-flash
# instructions='语速较快,带有明显的上扬语调,适合介绍时尚产品。',
# 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(f"finish at: {chunk.output.audio.expires_at}")
time.sleep(0.8)
# 清理资源
stream.stop_stream()
stream.close()
p.terminate()
需要导入 Gson 依赖,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>
在build.gradle中添加:// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")
// 请安装 DashScope SDK 的最新版本
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;
import javax.sound.sampled.*;
import java.util.Base64;
public class Main {
// 如需使用指令控制功能,请将MODEL替换为qwen3-tts-instruct-flash
private static final String MODEL = "qwen3-tts-flash";
public static void streamCall() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡地域和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(MODEL)
.text("Today is a wonderful day to build something people love!")
.voice(AudioParameters.Voice.CHERRY)
.parameter("language_type", "English") // 建议与文本语种一致,以获得正确的发音和自然的语调。
// 如需使用指令控制功能,请取消下方注释,并将model替换为qwen3-tts-instruct-flash
// .parameter("instructions","语速较快,带有明显的上扬语调,适合介绍时尚产品。")
// .parameter("optimize_instructions",true)
.build();
Flowable<MultiModalConversationResult> result = conv.streamCall(param);
result.blockingForEach(r -> {
try {
// 1. 获取Base64编码的音频数据
String base64Data = r.getOutput().getAudio().getData();
byte[] audioBytes = Base64.getDecoder().decode(base64Data);
// 2. 配置音频格式(根据API返回的音频格式调整)
AudioFormat format = new AudioFormat(
AudioFormat.Encoding.PCM_SIGNED,
24000, // 采样率(需与API返回格式一致)
16, // 采样位数
1, // 声道数
2, // 帧大小(字节数)
24000, // 帧率(需与采样率一致)
false // 大端序
);
// 3. 实时播放音频数据
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
try (SourceDataLine line = (SourceDataLine) AudioSystem.getLine(info)) {
if (line != null) {
line.open(format);
line.start();
line.write(audioBytes, 0, audioBytes.length);
line.drain();
}
}
} catch (LineUnavailableException e) {
e.printStackTrace();
}
});
}
public static void main(String[] args) {
// 以下为新加坡地域的配置。
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
streamCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
# ======= 重要提示 =======
# 以下为新加坡地域的配置。
# 新加坡地域和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
curl -X POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Today is a wonderful day to build something people love!",
"voice": "Cherry",
"language_type": "English"
}
}'
进阶功能
指令控制
指令控制通过自然语言描述控制语音的音调、语速、情感和音色特点,无需调整复杂的音频参数。
各模型指令规格:
支持的模型:仅支持Qwen3-TTS-Instruct-Flash 系列模型。使用方式:通过 instructions 参数传入指令内容。指令文本支持的语言:仅支持中文和英文。指令文本长度限制:不超过 1,600 Token。
适用场景:
- 有声书和广播剧配音
- 广告和宣传片配音
- 游戏角色和动画配音
- 情感化的智能语音助手
- 纪录片和新闻播报
如何编写高质量的声音描述:
-
核心原则:
- 具体而非模糊:使用描绘声音特质的词语,如“低沉”、“清脆”、“语速偏快”,避免“好听”、“普通”等主观或模糊的表述。
- 多维而非单一:好的描述通常涵盖多个维度(如性别、年龄、情感等)。仅写“女声”过于宽泛,难以生成有特色的音色。
- 客观而非主观:聚焦声音的物理和感知特征。例如,用”音调偏高,带有活力“代替”我最喜欢的声音”。
- 原创而非模仿:描述声音的特质,而非要求模仿特定人物(如名人、演员)。模型不支持模仿,且可能涉及版权风险。
- 简洁而非冗余:确保每个词都有明确作用,避免重复的同义词或无意义的修饰。
-
描述维度参考:
建议组合以下维度描述声音,维度越丰富,生成效果越精准。
维度 | 描述示例 |
性别 | 男性、女性、中性 |
年龄 | 儿童(5-12 岁)、青少年(13-18 岁)、青年(19-35 岁)、中年(36-55 岁)、老年(55 岁以上) |
音调 | 高音、中音、低音、偏高、偏低 |
语速 | 快速、中速、缓慢、偏快、偏慢 |
情感 | 开朗、沉稳、温柔、严肃、活泼、冷静、治愈 |
特点 | 有磁性、清脆、沙哑、圆润、甜美、浑厚、有力 |
用途 | 新闻播报、广告配音、有声书、动画角色、语音助手、纪录片解说 |
-
示例:
- 标准播音风格:吐字清晰精准,字正腔圆
- 年轻活泼的女性声音,语速较快,带有明显的上扬语调,适合介绍时尚产品
- 沉稳的中年男性,语速缓慢,音色低沉有磁性,适合朗读新闻或纪录片解说
- 温柔知性的女性,30 岁左右,语调平和,适合有声书朗读
- 可爱的儿童声音,大约 8 岁女孩,说话略带稚气,适合动画角色配音
本节介绍如何让模型用中文方言(如河南话、四川话等)输出语音。不同模型和音色类型的设置方式不同。
文本预处理建议
cosyvoice-v3-flash 在合成包含点号(·)分隔数字段的文本时,可能出现漏读或重复念读的情况,例如连续的房号可能被读错。
将文本中的点号(·)替换为中文逗号(,)可规避该问题:
- 原文:
主楼五楼·501房是PU·502房是OOO
- 预处理后:
主楼五楼501房是PU,502房是OOO
此为模型层已知限制,仅在 cosyvoice-v3-flash 上确认,cosyvoice-v2 经交叉验证无此问题,不适用于 CosyVoice 其他型号或其他模型系列。在模型优化完成前,建议在代码侧对待合成文案统一做该预处理。
支持的模型与地域
调用以下模型时,请选择新加坡地域的API Key:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash:qwen3-tts-instruct-flash(稳定版,当前等同 qwen3-tts-instruct-flash-2026-01-26)、qwen3-tts-instruct-flash-2026-01-26(最新快照版)
- Qwen3-TTS-VD:qwen3-tts-vd-2026-01-26(最新快照版)
- Qwen3-TTS-VC:qwen3-tts-vc-2026-01-22(最新快照版)
- Qwen3-TTS-Flash:qwen3-tts-flash(稳定版,当前等同 qwen3-tts-flash-2025-11-27)、qwen3-tts-flash-2025-11-27、qwen3-tts-flash-2025-09-18
调用以下模型时,请选择北京地域的API Key:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash:qwen3-tts-instruct-flash(稳定版,当前等同 qwen3-tts-instruct-flash-2026-01-26)、qwen3-tts-instruct-flash-2026-01-26(最新快照版)
- Qwen3-TTS-VD:qwen3-tts-vd-2026-01-26(最新快照版)
- Qwen3-TTS-VC:qwen3-tts-vc-2026-01-22(最新快照版)
- Qwen3-TTS-Flash:qwen3-tts-flash(稳定版,当前等同 qwen3-tts-flash-2025-11-27)、qwen3-tts-flash-2025-11-27、qwen3-tts-flash-2025-09-18
- Qwen-TTS:qwen-tts(稳定版,当前等同 qwen-tts-2025-04-10)、qwen-tts-latest(最新版,当前等同 qwen-tts-2025-05-22)、qwen-tts-2025-05-22(快照版)、qwen-tts-2025-04-10(快照版)
支持的系统音色
不同模型支持的音色不同。将请求参数 voice 设为下表中 voice 参数列的值即可。
API 参考
常见问题
Q:音频文件链接的有效期是多久?
A:音频文件链接在生成后 24 小时内有效。链接过期后,重新调用接口即可获取新链接。