Conheça os recursos da síntese de fala em tempo real, as chamadas em streaming e as formas de melhorar a qualidade da síntese.
Recursos
A síntese de fala em tempo real recebe segmentos de texto e retorna áudio progressivamente, permitindo converter o texto em fala enquanto um grande modelo de linguagem o gera.
- Idiomas e dialetos: selecione um modelo e uma voz para o idioma de destino ou especifique um dialeto por instrução. Consulte Dialetos.
- Expressividade: ajuste a interpretação com instruções em linguagem natural ou insira tags de emoção e sons não verbais. Consulte Controle por instruções e Tags de emoção e sons não verbais.
- Vozes personalizadas: crie uma voz a partir de uma amostra de áudio com a clonagem de voz ou de uma descrição com o design de voz.
- Controle detalhado e fórmulas: use SSML e LaTeX para controlar pausas e pronúncia ou converter fórmulas em fala.
- Controle de áudio: ajuste velocidade, tom, volume e taxa de bits, com formatos de áudio comuns, como PCM, WAV, MP3 e Opus, e taxas de amostragem de até 48 kHz. Consulte os parâmetros da API para valores e condições de suporte.
ObservaçãoOs recursos disponíveis variam conforme o modelo e a voz. Verifique o escopo na documentação de cada recurso.
Para enviar o texto completo em uma solicitação HTTP, consulte Síntese de fala não em tempo real.
Primeiros passos
- Obtenha uma chave de API e configure a variável de ambiente
DASHSCOPE_API_KEY. Use uma chave da região indicada no exemplo. - Para um endpoint exclusivo do workspace, substitua
{WorkspaceId}pelo ID do workspace dessa região. - Instale o DashScope SDK e escolha o exemplo em Python ou Java.
ObservaçãoAplicações móveis que precisam de baixa latência e transmissão de áudio estável em redes instáveis podem usar AOQ. Para acesso via AOQ, diferenças entre AOQ, WebRTC e WebSocket e modelos compatíveis, veja a Visão geral da Realtime API.
Qwen-Audio-TTS (recomendado)
Este exemplo usa qwen-audio-3.1-tts-flash e a voz do sistema longanhuan_v3.1 em Beijing. Envia texto em segmentos e salva o áudio recebido em output.mp3.
import os
import dashscope
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo por sua API Key do Model Studio: api_key = "sk-xxx"
# A configuração abaixo refere-se à região Pequim (China). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
api_key=os.environ["DASHSCOPE_API_KEY"],
workspace="{WorkspaceId}",
region="cn-beijing",
)
with open("output.mp3", "wb") as audio:
# Envia o texto em segmentos e recebe o áudio segmento por segmento
with client.audio.tts.connect(
model="qwen-audio-3.1-tts-flash",
voice="longanhuan_v3.1",
format="mp3",
sample_rate=24000,
) as session:
for text in ["你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"]:
session.send_text(text)
session.flush() # Aciona a síntese do texto em buffer (não encerra a entrada)
session.stop() # Encerra a entrada e aguarda o retorno do áudio restante
for chunk in session.audio_chunks():
audio.write(chunk)
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
public class Main {
public static void main(String[] args) throws Exception {
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
try (FileOutputStream audio = new FileOutputStream("output.mp3")) {
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-audio-3.1-tts-flash")
.voice("longanhuan_v3.1")
.format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
.build();
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<>() {
@Override
public void onEvent(SpeechSynthesisResult result) {
ByteBuffer buffer = result.getAudioFrame();
if (buffer != null) {
byte[] bytes = new byte[buffer.remaining()];
buffer.get(bytes);
try { audio.write(bytes); }
catch (Exception e) { throw new RuntimeException(e); }
}
}
@Override
public void onComplete() {}
public void onError(Exception e) { e.printStackTrace(); }
};
SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
try {
for (String text : new String[]{"你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"}) {
synthesizer.streamingCall(text);
}
synthesizer.streamingComplete(60000);
} finally {
synthesizer.getDuplexApi().close(1000, "done");
}
}
}
}
CosyVoice
Este exemplo usa cosyvoice-v3-flash e a voz do sistema longanyang em Beijing. Envia texto em segmentos e salva o áudio recebido em output.mp3.
import os
import dashscope
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo por sua API Key do Model Studio: api_key = "sk-xxx"
client = dashscope.Client(
api_key=os.environ["DASHSCOPE_API_KEY"],
workspace="{WorkspaceId}",
region="cn-beijing",
)
with open("output.mp3", "wb") as audio:
# Envia o texto em segmentos e recebe o áudio segmento por segmento
with client.audio.tts.connect(
model="cosyvoice-v3-flash",
voice="longanyang",
format="mp3",
sample_rate=24000,
) as session:
for text in ["你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"]:
session.send_text(text)
session.flush() # Aciona a síntese do texto em buffer (não encerra a entrada)
session.stop() # Encerra a entrada e aguarda o retorno do áudio restante
for chunk in session.audio_chunks():
audio.write(chunk)
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
public class Main {
public static void main(String[] args) throws Exception {
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
try (FileOutputStream audio = new FileOutputStream("output.mp3")) {
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("cosyvoice-v3-flash")
.voice("longanyang")
.format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
.build();
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<>() {
@Override
public void onEvent(SpeechSynthesisResult result) {
ByteBuffer buffer = result.getAudioFrame();
if (buffer != null) {
byte[] bytes = new byte[buffer.remaining()];
buffer.get(bytes);
try { audio.write(bytes); }
catch (Exception e) { throw new RuntimeException(e); }
}
}
@Override
public void onComplete() {}
public void onError(Exception e) { e.printStackTrace(); }
};
SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
try {
for (String text : new String[]{"你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"}) {
synthesizer.streamingCall(text);
}
synthesizer.streamingComplete(60000);
} finally {
synthesizer.getDuplexApi().close(1000, "done");
}
}
}
}
Melhorar a qualidade da síntese
Idiomas e pronúncia
Escolha a abordagem de acordo com o conteúdo a controlar:
| Necessidade | Abordagem |
|---|---|
Definir o idioma de destino da voz | Use |
Corrigir palavras específicas ou substituir texto | Use |
Controlar pausas, leitura de números ou pronúncia em detalhes | Marque o texto com tags SSML para controlar pausas, regras de leitura e pronúncia. |
Ler fórmulas matemáticas | Use o recurso LaTeX do CosyVoice para converter as fórmulas compatíveis em fala em chinês. |
Para modelos e parâmetros, consulte a API Qwen-Audio-TTS ou a API CosyVoice. Para modelos, vozes, interfaces e uso de SSML e LaTeX, consulte SSML e LaTeX.
ObservaçãoAo usar SSML, envie o texto SSML completo em uma única entrada e receba o áudio gradualmente. A entrada de texto em vários fragmentos não é aceita.
Controle por instruções
Use instruction para especificar o idioma de síntese e descrever a velocidade, a emoção ou o estilo de fala em linguagem natural para controlar a voz sintetizada.
ObservaçãoPara criar uma nova voz com gênero, idade ou características vocais específicas, ou consultar orientações e exemplos de descrições de voz, veja design de voz.
Qwen-Audio-TTS
As vozes do sistema, clonadas e criadas por design de qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus e qwen-audio-3.0-tts-flash aceitam instruções em linguagem natural por meio de instruction nas solicitações de síntese.
Recomendamos especificar o idioma de síntese e o efeito desejado em instruction para melhorar a qualidade da síntese. O idioma especificado na instrução deve corresponder ao idioma do texto a ser sintetizado. Por exemplo, ao sintetizar texto em holandês, defina:
请用荷兰话说,每个字都慢慢说
CosyVoice
ObservaçãoNo CosyVoice, instruction pode ter até 100 caracteres. Caracteres chineses, incluindo simplificados, tradicionais e usados no japonês e no coreano, contam como dois cada. Outros caracteres, incluindo pontuação, letras, números, kana e hangul, contam como um cada.
| Modelo | Vozes aplicáveis | Requisitos das instruções | Idiomas do texto das instruções |
|---|---|---|---|
| Vozes clonadas e criadas por design Não há vozes do sistema. | Instruções em linguagem natural. | Chinês, inglês, francês, alemão, japonês, coreano, russo, português, tailandês, indonésio e vietnamita. |
| Vozes do sistema | Use o formato e o conteúdo fixos da lista de vozes. Vozes clonadas e criadas por design não oferecem controle por instruções. | Use o idioma indicado na lista de vozes. |
| Vozes do sistema | Use o formato e o conteúdo fixos da lista de vozes. | Chinês. |
Vozes clonadas e criadas por design | Instruções em linguagem natural. | Chinês, inglês, francês, alemão, japonês, coreano e russo. |
Dialetos
A síntese de dialetos gera fala em dialetos chineses, como os de Henan ou Sichuan. A seleção do dialeto depende do modelo e do tipo de voz.
Qwen-Audio-TTS
- Vozes do sistema: selecione uma voz compatível com o dialeto de destino na lista Qwen-Audio-TTS. Vozes que oferecem o dialeto diretamente não exigem configurações adicionais. Para vozes compatíveis com instruções de dialeto, use o parâmetro de controle por instruções
instruction. - Vozes clonadas: especifique o dialeto com o parâmetro de controle por instruções
instruction.
Para vozes compatíveis com instruções de dialeto, passe instruction="请讲上海话。" ao inicializar SpeechSynthesizer para sintetizar texto em chinês no dialeto de Xangai.
CosyVoice
- Vozes do sistema: selecione uma voz que ofereça o dialeto diretamente, como
longshange_v3, ou aceite instruções de dialeto, comolonganhuan_v3. Siga o formato da lista de vozes. - Vozes clonadas: use
instructioncom um modelo compatível com controle por instruções para especificar o dialeto. - Vozes criadas por design: dialetos não são compatíveis.
No exemplo inicial de CosyVoice em Python, substitua a inicialização e o envio do texto pelo código a seguir para gerar fala no dialeto de Henan com longanhuan_v3:
with client.audio.tts.connect(
model="cosyvoice-v3-flash",
voice="longanhuan_v3",
parameters={"instruction": "请用河南话表达。"}, # Controle por instruções
format="mp3",
sample_rate=24000,
) as session:
session.send_text("叫你去买盐,你买回来一袋面,这不是弄啥嘞吗!")
session.flush()
Para Qwen3-TTS, selecione uma voz compatível com o dialeto desejado na lista de vozes Qwen3-TTS.
Tags de emoção e sons não verbais
ObservaçãoAplica-se a qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus e qwen-audio-3.0-tts-flash.
As tags de emoção e paralinguísticas controlam a emoção e o estilo da fala e inserem sons, como risadas ou suspiros, em posições específicas. Escreva as tags diretamente no texto a ser sintetizado, text, sem parâmetros adicionais.
Exemplos de uso
Este texto começa com uma interpretação animada, insere uma risada na posição indicada e continua a fala:
[excited]今天的天气真不错![laughing]我们一起出去玩吧!
Este texto muda para uma interpretação animada na segunda frase:
[serious]请注意安全事项。[excited]好了,现在让我们开始吧!
Tags compatíveis
Aplicação em produção
Cancelar tarefa
Com Qwen-Audio-TTS ou CosyVoice, envie uma instrução de cancelamento para interromper a síntese atual. O servidor encerra a tarefa e retorna task-finished.
| Método | Versão necessária | Uso |
|---|---|---|
SDK Python | 2.0.1 ou posterior | Chame |
SDK Java | 2.22.26 ou posterior | Chame |
Protocolo WebSocket direto | Não requer SDK | Envie |
Reutilização de conexões WebSocket
Uma conexão WebSocket pode processar várias sínteses em sequência. Inicie a próxima de acordo com a série do modelo:
| Série de modelos | Evento de conclusão | Iniciar a próxima síntese |
|---|---|---|
Qwen-Audio-TTS, CosyVoice |
| Envie ObservaçãoAo usar o SDK Python, a sessão criada por |
Qwen3-TTS |
| Continue enviando |
Para configurar pools do SDK e consultar exemplos completos, veja Síntese de fala com alta concorrência. Para sessões Qwen3-TTS, veja a API WebSocket.
Para Qwen-Audio-TTS / CosyVoice, a conexão é fechada automaticamente se nenhuma tarefa começar em até 60 segundos após a anterior. Reconecte se a conexão estiver fechada ou o estado da tarefa for inválido.
Limites de taxa
Controle a frequência de solicitações e a concorrência conforme os limites do modelo. Para limites, erros comuns e soluções, veja Limites de taxa.
Melhores práticas para alta concorrência
Use pools para reutilizar objetos e conexões e configure concorrência, aquecimento e erros conforme a carga. Veja Síntese de fala com alta concorrência.
Modelos compatíveis
Singapore
Use uma chave de API e um endpoint desta região para chamar estes modelos:
- Qwen-Audio-TTS: qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash
- CosyVoice: cosyvoice-v3-plus, cosyvoice-v3-flash
- Qwen3-TTS: qwen3-tts-flash-realtime
China (Beijing)
Use uma chave de API e um endpoint desta região para chamar estes modelos:
- Qwen-Audio-TTS: qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash
- CosyVoice: cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash, cosyvoice-v2
- Qwen3-TTS: qwen3-tts-flash-realtime
Para vozes do sistema e amostras de áudio, consulte as listas Qwen-Audio-TTS, CosyVoice e Qwen3-TTS. Uma voz clonada ou criada por design deve ser usada com o modelo de destino definido na criação.
Referência da API
- Real-time speech synthesis - Qwen-Audio-TTS API reference
- Real-time speech synthesis - CosyVoice API reference
- Real-time speech synthesis - Qwen-TTS API reference
- AOQ client SDK (para modelos CosyVoice)
Veja os exemplos WebSocket diretos completos nas páginas abaixo.
FAQ
P: Como solucionar áudio mudo ao usar uma voz clonada?
Verifique se voice é o ID de uma voz criada com sucesso e se seu target_model corresponde ao model de síntese. Para estado, requisitos do áudio de origem e orientações de qualidade, consulte Clonagem de voz.
P: Por que a duração real do áudio sintetizado difere da duração mostrada no arquivo WAV?
No WAV em streaming, o cabeçalho pode não refletir o tamanho final do áudio. Para obter metadados de duração precisos, defina format como pcm, receba todo o áudio e adicione um cabeçalho WAV com o tamanho real.
P: Por que o arquivo de áudio não reproduz?
Faça a solução de problemas com base no seu cenário:
-
Áudio salvo como arquivo completo (como xx.mp3)
- Consistência do formato de áudio: O formato de áudio nos parâmetros da requisição deve corresponder à extensão do arquivo (por exemplo, se o parâmetro for wav, o arquivo deve ser .wav).
- Compatibilidade do player: Confirme se o player suporta o formato de áudio e a taxa de amostragem.
-
Reprodução de áudio em streaming
- Salve o fluxo de áudio como um arquivo completo e tente reproduzi-lo com um media player. Se o arquivo não reproduzir, consulte o cenário 1 acima.
- Se o arquivo reproduzir corretamente, o problema está na implementação da reprodução em streaming. Confirme se o player suporta reprodução em streaming (como ffmpeg, pyaudio, AudioFormat ou MediaSource).
P: Por que a reprodução do áudio está travando?
Faça a solução de problemas seguindo estas etapas:
-
Verifique a taxa de envio de texto: Certifique-se de que o intervalo de envio seja razoável para evitar que o segmento de áudio anterior termine antes da chegada do próximo texto.
-
Verifique o desempenho da função de callback:
- Confirme que não existe lógica de bloqueio na função de callback.
- Os callbacks são executados na thread WebSocket. Operações de bloqueio afetam o recebimento de dados. Escreva os dados de áudio em um buffer separado e processe-os em outra thread.
-
Verifique a estabilidade da rede: Flutuações na rede podem causar interrupções ou atrasos na transmissão de áudio.
P: Por que a síntese de fala está demorando muito?
Na entrada segmentada, intervalos longos entre os envios de texto aumentam o tempo total de síntese. A primeira chamada também inclui o custo da conexão WebSocket. Para aquecimento e medições com alta concorrência, veja Síntese de fala com alta concorrência.
P: Como restringir uma API key apenas ao service de síntese de fala (isolamento de permissões)?
Crie um novo workspace e conceda acesso apenas a modelos específicos. Isso limita o escopo da API key. Para mais detalhes, consulte Manage workspaces.