A síntese de fala não em tempo real converte texto em áudio por meio da API HTTP. Esse recurso atende a cenários que toleram maior latência, como produção de audiolivros, narração para educação online e criação de conteúdo. Ele oferece suporte a uma ampla variedade de vozes, múltiplos idiomas, clonagem de voz e design de voz.
Visão geral
Converta textos completos em arquivos de áudio pela API HTTP. Dois modos de saída estão disponíveis: sem streaming e com streaming.
- O modo sem streaming retorna uma URL de arquivo de áudio válida por 24 horas; o modo com streaming retorna dados de áudio em blocos.
- Há suporte para vários idiomas, incluindo dialetos do chinês.
- Compatível com Voice cloning e Voice Design para criação de vozes personalizadas.
- Permite o uso de Instruction control para controlar a expressividade da fala por meio de instruções em linguagem natural.
Para cenários de streaming com baixa latência, consulte Real-time speech synthesis. Para recomendações sobre a escolha de modelos, veja Speech synthesis.
O áudio sintetizado na página de design de voz no console do Model Studio serve apenas para pré-visualização online e não pode ser baixado diretamente como arquivo. Para obter o arquivo de áudio, chame a API ou utilize o SDK. No modo sem streaming, a resposta inclui uma URL de arquivo de áudio válida por 24 horas.
Pré-requisitos
Antes de começar, conclua as seguintes preparações:
- Configure an API key e set it as an environment variable
- (Opcional) Se você for chamar a API pelo DashScope SDK, install the latest SDK
Início rápido
As abas a seguir demonstram a síntese de fala para cada série de modelos. Para mais exemplos de código em diferentes linguagens e descrições detalhadas dos parâmetros, consulte API reference.
Qwen-TTS
Todos os exemplos nesta seção utilizam system voices.
Saída sem streaming
No modo sem streaming, a resposta inclui um campo url que aponta para o arquivo de áudio sintetizado. A URL tem validade de 24 horas.
Python
import os
import dashscope
# The following is the configuration for the Singapore region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
text = "Today is a wonderful day to build something people love!"
# Interface usage: dashscope.MultiModalConversation.call(...)
response = dashscope.MultiModalConversation.call(
# To use the instruction control feature, replace model with qwen3-tts-instruct-flash
model="qwen3-tts-flash",
# The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
text=text,
voice="Cherry",
language_type="English", # We recommend matching this with the language of the text for correct pronunciation and natural intonation.
# To use the instruction control feature, uncomment the lines below and replace model with qwen3-tts-instruct-flash
# instructions='Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.',
# optimize_instructions=True,
stream=False
)
print(response)
Java
Importe a dependência Gson. Adicione-a usando Maven ou Gradle:
Maven
Adicione o seguinte trecho ao arquivo 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>
Gradle
Acrescente o seguinte ao arquivo 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 {
// To use the instruction control feature, replace MODEL with 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()
// The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio 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)
.languageType("English") // We recommend matching this with the language of the text for correct pronunciation and natural intonation.
// To use the instruction control feature, uncomment the lines below and replace model with qwen3-tts-instruct-flash
// .parameter("instructions","Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.")
// .parameter("optimize_instructions",true)
.build();
MultiModalConversationResult result = conv.call(param);
String audioUrl = result.getOutput().getAudio().getUrl();
System.out.print(audioUrl);
// Download the audio file to local storage
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("\nAudio file downloaded to: downloaded_audio.wav");
} catch (Exception e) {
System.out.println("\nFailed to download audio file: " + e.getMessage());
}
}
public static void main(String[] args) {
// The following is the configuration for the Singapore region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
cURL
# ======= Important =======
# The following configuration is for the Singapore region.
# The API keys for the Singapore region and the Beijing region are different. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Remove this comment before running ===
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"
}
}'
Saída com streaming
No modo com streaming, os dados de áudio retornam em blocos codificados em Base64 no formato PCM. O último pacote contém a URL do arquivo de áudio completo.
Python
# 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
# The following is the configuration for the Singapore region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
p = pyaudio.PyAudio()
# Create an audio stream
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(
# The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# To use the instruction control feature, replace model with qwen3-tts-instruct-flash
model="qwen3-tts-flash",
text=text,
voice="Cherry",
language_type="English", # We recommend matching this with the language of the text for correct pronunciation and natural intonation.
# To use the instruction control feature, uncomment the lines below and replace model with qwen3-tts-instruct-flash
# instructions='Fast-paced speech with noticeable upward intonation, ideal for presenting 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)
# Play audio data directly
stream.write(audio_np.tobytes())
if chunk.output.finish_reason == "stop":
print(f"finish at: {chunk.output.audio.expires_at}")
time.sleep(0.8)
# Clean up resources
stream.stop_stream()
stream.close()
p.terminate()
Java
Importe a dependência Gson. Adicione-a usando Maven ou Gradle:
Maven
Adicione o seguinte trecho ao arquivo 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>
Gradle
Acrescente o seguinte ao arquivo build.gradle:
// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")
// Please install the latest version of the 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 {
// To use the instruction control feature, replace MODEL with 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()
// The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio 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)
.languageType("English") // We recommend matching this with the language of the text for correct pronunciation and natural intonation.
// To use the instruction control feature, uncomment the lines below and replace model with qwen3-tts-instruct-flash
// .parameter("instructions","Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.")
// .parameter("optimize_instructions",true)
.build();
Flowable<MultiModalConversationResult> result = conv.streamCall(param);
result.blockingForEach(r -> {
try {
// 1. Get the Base64-encoded audio data
String base64Data = r.getOutput().getAudio().getData();
byte[] audioBytes = Base64.getDecoder().decode(base64Data);
// 2. Configure the audio format (adjust according to the audio format returned by the API)
AudioFormat format = new AudioFormat(
AudioFormat.Encoding.PCM_SIGNED,
24000, // Sample rate (must match the format returned by the API)
16, // Bit depth
1, // Number of channels
2, // Frame size (in bytes)
24000, // Frame rate (must match the sample rate)
false // Big-endian
);
// 3. Play audio data in real time
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) {
// The following is the configuration for the Singapore region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
streamCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
cURL
# ======= Important =======
# The following configuration is for the Singapore region.
# The API keys for the Singapore region and the Beijing region are different. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Remove this comment before running ===
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"
}
}'
Recursos avançados
Controle por instruções
Especificações de instruções por modelo:
Qwen-TTS
Modelos suportados: Apenas a série Qwen3-TTS-Instruct-Flash.
Uso: Passe o conteúdo da instrução através do parâmetro instructions.
Idiomas suportados para texto de instrução: Somente Chinês e Inglês.
Limite de comprimento do texto de instrução: Até 1.600 tokens.
Dialetos
Esta seção explica como gerar fala em dialetos chineses (como o dialeto de Henan e o de Sichuan). O método de configuração depende do modelo e do tipo de voz.
Qwen-TTS
- Vozes do sistema: Utilize vozes do sistema com suporte a dialetos. Consulte Qwen-TTS voice list.
- Vozes clonadas: Sem suporte para dialetos.
- Vozes desenhadas: Sem suporte para dialetos.
Dialetos suportados: Confira a seção "Idiomas suportados" de cada modelo em Qwen3-TTS.
Modelos e regiões suportados
Singapore
Utilize uma chave de API da região de Singapore para chamar os seguintes modelos:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash: qwen3-tts-instruct-flash (versão estável, atualmente equivalente a qwen3-tts-instruct-flash-2026-01-26), qwen3-tts-instruct-flash-2026-01-26 (snapshot mais recente)
- Qwen3-TTS-VD: qwen3-tts-vd-2026-01-26 (snapshot mais recente)
- Qwen3-TTS-VC: qwen3-tts-vc-2026-01-22 (snapshot mais recente)
- Qwen3-TTS-Flash: qwen3-tts-flash (versão estável, atualmente equivalente a qwen3-tts-flash-2025-11-27), qwen3-tts-flash-2025-11-27, qwen3-tts-flash-2025-09-18
China (Beijing)
Para acessar os modelos abaixo, utilize uma chave de API da região de Beijing:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash: qwen3-tts-instruct-flash (versão estável, atualmente equivalente a qwen3-tts-instruct-flash-2026-01-26), qwen3-tts-instruct-flash-2026-01-26 (snapshot mais recente)
- Qwen3-TTS-VD: qwen3-tts-vd-2026-01-26 (snapshot mais recente)
- Qwen3-TTS-VC: qwen3-tts-vc-2026-01-22 (snapshot mais recente)
- Qwen3-TTS-Flash: qwen3-tts-flash (versão estável, atualmente equivalente a qwen3-tts-flash-2025-11-27), qwen3-tts-flash-2025-11-27, qwen3-tts-flash-2025-09-18
- Qwen-TTS: qwen-tts (versão estável, atualmente equivalente a qwen-tts-2025-04-10), qwen-tts-latest (versão mais recente, atualmente equivalente a qwen-tts-2025-05-22), qwen-tts-2025-05-22 (snapshot), qwen-tts-2025-04-10 (snapshot)
Vozes do sistema suportadas
Cada modelo oferece suporte a um conjunto diferente de vozes. Defina o parâmetro de requisição voice com um valor da coluna parâmetro de voz nas tabelas a seguir.
Referência da API
Perguntas frequentes
P: Qual é a validade da URL do arquivo de áudio?
R: A URL do arquivo de áudio é válida por 24 horas após a geração. Quando a URL expirar, chame a API novamente para obter uma nova URL.