Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Real-time speech synthesis

Última atualização: Oct 29, 2026

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

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:

NecessidadeAbordagem

Definir o idioma de destino da voz

Use language_hints para definir o idioma geral da síntese, orientar a leitura de números, abreviações e símbolos e melhorar a síntese em idiomas menos difundidos.

Corrigir palavras específicas ou substituir texto

Use hot_fix para atribuir pinyin a palavras específicas ou substituir palavras antes da síntese, por exemplo, para corrigir nomes próprios de forma consistente.

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.

ModeloVozes aplicáveisRequisitos das instruçõesIdiomas do texto das instruções

cosyvoice-v3.5-plus, cosyvoice-v3.5-flash

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.

cosyvoice-v3-plus

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.

cosyvoice-v3-flash

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, como longanhuan_v3. Siga o formato da lista de vozes.
  • Vozes clonadas: use instruction com 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

Tags de controle

Uma tag de controle define a emoção ou o estilo do texto seguinte até a próxima tag de controle. Se frases longas forem segmentadas automaticamente, o efeito ficará restrito ao segmento resultante.

TagDescrição

[sad]

Triste

[amazed]

Surpreso

[deep and loud shouting]

Grito grave e forte

[trembling]

Trêmulo

[angry]

Irritado

[excited]

Animado

[sarcastic]

Sarcástico

[curious]

Curioso

[like dracula]

Interpretação de Drácula

[bored]

Entediado

[tired]

Cansado

[scornful]

Desdenhoso

[shouting]

Grito

[asmr]

Voz suave de ASMR

[panicked]

Em pânico

[mischievously]

Travesso

[empathetic]

Empático

[whispers]

Sussurro

[reluctantly]

Relutante

[crying]

Choro

[serious]

Sério

[very slowly]

Muito lento

[very fast]

Muito rápido

Tags de sons não verbais

Uma tag de som não verbal insere um som na posição indicada, sem mudar o estilo emocional do texto ao redor.

TagDescrição

[gasp]

Inspiração de surpresa

[sighing]

Suspiro

[clears throat]

Pigarro

[giggles]

Risadinha

[laughing]

Risada

[cough]

Tosse

[snorts]

Bufada

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étodoVersão necessáriaUso

SDK Python

2.0.1 ou posterior

Chame session.cancel() do objeto de sessão (a sessão retornada por client.audio.tts.connect).

SDK Java

2.22.26 ou posterior

Chame SpeechSynthesizer.streamingCancel().

Protocolo WebSocket direto

Não requer SDK

Envie finish-task com directive=cancel em input.

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 modelosEvento de conclusãoIniciar a próxima síntese

Qwen-Audio-TTS, CosyVoice

task-finished

Envie run-task com um novo task_id em cada síntese e depois envie o texto conforme o fluxo da série. A regra também se aplica após o cancelamento.

ObservaçãoAo usar o SDK Python, a sessão criada por client.audio.tts.connect fecha por padrão a conexão subjacente quando a tarefa termina ou é cancelada. Para reutilizar a conexão, crie primeiro uma conexão WebSocket compartilhada por meio de client.ws_connection() e a informe em client.audio.tts.connect por meio de connection=, permitindo executar várias rodadas de síntese em sequência na mesma conexão; a conexão deve ser fechada pelo chamador por meio de WsConnection.close.

Qwen3-TTS

response.done

Continue enviando input_text_buffer.append na mesma sessão. A síntese é automática ou acionada por input_text_buffer.commit, conforme o modo. Envie session.finish somente depois de todo o texto.

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

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:

  1. Áudio salvo como arquivo completo (como xx.mp3)

    1. 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).
    2. Compatibilidade do player: Confirme se o player suporta o formato de áudio e a taxa de amostragem.
  2. Reprodução de áudio em streaming

    1. 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.
    2. 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:

  1. 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.

  2. 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.
  3. 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.