Converta texto em fala com baixa latência no primeiro pacote. A síntese de fala em tempo real oferece entrada e saída em streaming, clonagem de voz, design de voz e controles de áudio refinados para assistentes de voz, audiolivros e atendimento ao cliente inteligente.
Visão geral
Transforme texto em fala instantaneamente e com baixa latência.
- Entrada e saída em streaming com baixa latência no primeiro pacote
- Controle granular de áudio com ajustes de velocidade da fala, tom, volume e taxa de bits
- Compatibilidade com os principais formatos de áudio (PCM, WAV, MP3, Opus) e taxa de amostragem de até 48 kHz
- Suporte a Instruction control, que permite controlar a expressividade da fala por meio de instruções em linguagem natural
- Recursos de Voice cloning e Voice Design para criação de vozes personalizadas
- Integração com Emotion and rich language tags, possibilitando a inserção de tags de emoção ou efeitos sonoros diretamente no texto
Pré-requisitos
- Configure an API key e set it as an environment variable.
- Caso pretenda chamar a API pelo DashScope SDK, install the latest SDK.
- Para utilizar o protocolo AOQ com modelos CosyVoice, baixe e integre o SDK do cliente AOQ. Para mais detalhes, consulte SDK overview.
Início rápido
Os exemplos a seguir demonstram a síntese de fala para cada modelo. Para ver mais exemplos e detalhes dos parâmetros, acesse API reference.
- Qwen-Audio-TTS
- CosyVoice
- Qwen-TTS
instruction.Configuração de sessão
Modos de interação do Qwen-TTS
A API em tempo real do Qwen-TTS oferece dois modos de interação:
- Modo server_commit: O servidor gerencia automaticamente a segmentação de texto e o tempo de síntese. Ideal para síntese contínua de grandes blocos de texto. O cliente adiciona texto sem precisar gerenciar a segmentação ou o envio.
- Modo commit: O cliente envia explicitamente o buffer de texto para acionar a síntese. Recomendado para cenários que exigem controle preciso sobre o momento da síntese, como a síntese por turno em IA conversacional.
- WebSocket: Defina o campo
modeno eventosession.update.
- SDK Python: Configure o parâmetro
modeno métodoupdate_session.
- SDK Java: Especifique o parâmetro
modepor meio deQwenTtsRealtimeConfig.builder().
Recursos avançados
Controle por instruções
O controle por instruções utiliza descrições em linguagem natural para ajustar o tom, a velocidade, a emoção e as características do timbre da fala, sem a necessidade de configurar parâmetros de áudio complexos.
Especificações de instruções por modelo:
- Qwen-Audio-TTS
- CosyVoice
- Qwen-TTS
- Narração de audiolivros e radionovelas
- Locução para publicidade e vídeos promocionais
- Dublagem de personagens de jogos e animações
- Assistentes de voz com expressividade emocional
- Narração de documentários e telejornais
-
Princípios fundamentais:
- Seja específico, não vago: Utilize termos que descrevam qualidades vocais, como "profundo", "nítido" ou "ritmo levemente acelerado". Evite palavras subjetivas ou imprecisas como "bonito" ou "normal".
- Aborde múltiplas dimensões: Uma boa descrição geralmente abrange vários aspectos (como gênero, idade e emoção). Escrever apenas "voz feminina" é amplo demais para gerar um timbre distinto.
- Mantenha a objetividade: Concentre-se nas características físicas e perceptivas da voz. Por exemplo, use "tom mais agudo com energia" em vez de "minha voz favorita".
- Priorize a originalidade: Descreva as qualidades vocais em vez de solicitar a imitação de pessoas específicas (como celebridades ou atores). O modelo não suporta imitações e isso pode acarretar riscos de direitos autorais.
- Seja conciso: Garanta que cada palavra tenha um propósito. Evite sinônimos repetitivos ou modificadores sem significado.
-
Referência de dimensões de descrição:
Combine as dimensões abaixo para descrever uma voz. Quanto mais dimensões você incluir, mais precisa será a saída.
Dimensão
Exemplos de descrições
Gênero
Masculino, feminino, andrógino
Idade
Criança (5-12), adolescente (13-18), jovem adulto (19-35), meia-idade (36-55), idoso (55+)
Tom
Agudo, médio, grave, levemente agudo, levemente grave
Velocidade
Rápida, moderada, lenta, levemente rápida, levemente lenta
Emoção
Alegre, calmo, gentil, sério, animado, sereno, suave
Características
Magnético, nítido, rouco, aveludado, doce, encorpado, potente
Caso de uso
Telejornal, locução publicitária, audiolivro, personagem de animação, assistente de voz, narração de documentário
-
Exemplos:
- Estilo de transmissão padrão: articulação clara e precisa com pronúncia perfeita
- Uma voz feminina jovem e animada, com ritmo mais rápido e entonação ascendente notável, adequada para apresentações de produtos de moda
- Um homem de meia-idade calmo, ritmo lento, voz profunda e magnética, adequado para leitura de notícias ou narração de documentários
- Uma mulher gentil e intelectual, por volta dos 30 anos, com tom uniforme, adequada para narração de audiolivros
- Uma voz infantil fofa, aproximadamente de uma menina de 8 anos, falando com uma qualidade levemente pueril, adequada para dublagem de personagens de animação
Dialetos
Esta seção descreve como produzir fala em dialetos chineses (como o dialeto de Henan, dialeto de Sichuan e cantonês). Os métodos de configuração variam conforme o modelo e o tipo de voz.
Configuração de dialeto por modelo:
- Qwen-Audio-TTS
- CosyVoice
- Qwen-TTS
-
Vozes do sistema: Selecione um dos seguintes tipos de voz:
- Uma voz do sistema com suporte nativo a dialeto, que gera o dialeto correspondente sem configuração adicional.
- Uma voz compatível com Instruction control, configurável para gerar um dialeto específico por meio de texto de instrução.
-
Vozes clonadas: Configure por meio do recurso Instruction control. Por exemplo, defina o texto da instrução como
请用河南话表达.
Tags de emoção e linguagem rica
Os modelos da série Qwen-Audio-TTS permitem incorporar tags de emoção e linguagem rica diretamente no texto a ser sintetizado (parâmetro text). Essas tags controlam a expressão emocional ou inserem efeitos vocais (como risadas e suspiros) em posições específicas, produzindo uma fala mais expressiva sem a necessidade de configurar parâmetros de áudio complexos.
Tags de controle
As tags de controle definem a emoção ou o estilo da fala. Insira uma tag no texto para afetar todo o conteúdo subsequente até que outra tag de controle apareça ou a frase seja segmentada automaticamente devido ao comprimento.
Tag | Descrição |
|---|---|
| Triste |
| Espantado |
| Grito profundo e alto |
| Trêmulo |
| Com raiva |
| Empolgado |
| Sarcástico |
| Curioso |
| Estilo Drácula (profundo, sombrio) |
| Entediado |
| Cansado |
| Desdenhoso |
| Gritando |
| Sussurro suave ASMR |
| Em pânico |
| Malicioso |
| Empático |
| Sussurro |
| Relutante |
| Chorando |
| Sério |
| Fala muito lenta |
| Fala muito rápida |
Tag | Descrição |
|---|---|
| Arquejo |
| Suspiro |
| Limpeza de garganta |
| Risadinha |
| Risada |
| Tosse |
| Bufada |
text:
[excited]What a beautiful day today![laughing]Let's go out and have fun together!
Neste texto, [excited] é uma tag de controle que aplica emoção de empolgação a todo o texto subsequente. Já [laughing] é uma tag de linguagem rica que insere uma risada naquela posição antes de continuar a síntese do restante do texto.
Também é possível alternar entre diferentes emoções no mesmo texto:
[serious]Please pay attention to the safety precautions.[excited]Alright, let's get started now!
Aqui, [serious] define a primeira frase com um tom sério, enquanto [excited] alterna para um tom empolgado a partir da segunda frase.
Cancelar tarefa
Caso precise interromper a rodada atual de síntese durante a geração de fala em tempo real, envie um comando de cancelamento. Após o cancelamento, o servidor encerra imediatamente a tarefa atual e retorna um evento de conclusão. É possível iniciar uma nova tarefa de síntese na mesma conexão WebSocket sem precisar reconectar.
Uso:
- Python SDK: Versão 1.26.4 ou posterior, chame
SpeechSynthesizer.streaming_cancel(). - Java SDK: Versão 2.22.26 ou posterior, chame
SpeechSynthesizer.streamingCancel(). - Protocolo bruto WebSocket: Envie um evento
finish-taske definadirective=canceleminput.
Chamadas diretas ao protocolo WebSocket
Os exemplos a seguir demonstram como se conectar diretamente ao servidor usando o protocolo nativo do WebSocket, ideal para cenários em que o DashScope SDK não está disponível. Estas são implementações mínimas e executáveis. Para obter detalhes sobre o protocolo WebSocket, consulte a referência da API de cada modelo.
Visualizar exemplos de chamada direta ao protocolo WebSocket
Visualizar exemplos de chamada direta ao protocolo WebSocket
- Qwen-TTS
-
Crie o cliente
- Python
- Java
Crie um arquivo Python chamadotts_realtime_client.pye copie o código a seguir para o arquivo: -
Selecione um modo de síntese de fala
A Realtime API oferece suporte a dois modos:
- Modo server_commit O servidor gerencia automaticamente a segmentação de texto e o tempo de síntese. O cliente apenas envia o texto. Ideal para cenários de baixa latência, como navegação GPS.
- Modo commit O cliente adiciona texto a um buffer e aciona explicitamente a síntese. Recomendado para casos que exigem controle preciso da segmentação de frases, como transmissões de notícias.
- Modo server_commit
- Modo commit
- Python
- Java
No mesmo diretório do arquivotts_realtime_client.py, crie outro arquivo Python chamadoserver_commit.pye copie o código abaixo para ele:Execute o arquivoserver_commit.pypara ouvir em tempo real o áudio gerado pela Realtime API.
Aplicação em produção
Reutilização de conexão (WebSocket)
As conexões WebSocket são reutilizáveis. Após a conclusão de uma tarefa de síntese, inicie a próxima tarefa na mesma conexão sem precisar restabelecê-la.
Processo de reutilização:
- Qwen-Audio-TTS / Qwen-Audio-TTS/CosyVoice: O cliente envia
finish-taske, após o servidor retornartask-finished, o cliente pode enviarrun-taskpara iniciar uma nova tarefa. - Qwen-TTS: O cliente envia
session.finishe, depois que o servidor retornasession.finished, o cliente pode criar uma nova sessão para começar a próxima tarefa.
cancel, também é possível enviar um novo run-task na mesma conexão assim que o servidor retornar task-finished. Para mais detalhes, consulte Cancel task.
Para obter detalhes sobre os eventos de cada modelo, consulte o API reference correspondente.
Limites de taxa
As chamadas aos modelos estão sujeitas a limites de taxa. Quando um limite é excedido, o servidor retorna o erro Requests rate limit exceeded, please try again later. Reduza a taxa de requisições ou a concorrência e tente novamente.
Para verificar os limites de taxa de cada modelo, consulte Rate limiting.
Melhores práticas para alta concorrência
O DashScope SDK possui pooling integrado que reutiliza conexões WebSocket e objetos sintetizadores, eliminando a sobrecarga de criá-los e destruí-los repetidamente.
Visualizar melhores práticas para alta concorrência
Visualizar melhores práticas para alta concorrência
- Qwen-Audio-TTS/CosyVoice
model e voice.Pré-requisitos
- Obtain an API key
-
DashScope SDK instalado e compatível com os requisitos de versão. Recomendamos installing the latest version:
- Python SDK: versão >= 1.25.2
- Java SDK: versão >= 2.16.6
- Python SDK
- Java SDK
SpeechSynthesizerObjectPool para gerenciar e reutilizar objetos SpeechSynthesizer.Esse pool cria um número especificado de instâncias SpeechSynthesizer e estabelece conexões WebSocket durante a inicialização. Ao solicitar um objeto emprestado, ele já está pronto para enviar requisições imediatamente, reduzindo a latência do primeiro pacote. Após a devolução do objeto, a conexão permanece ativa para a próxima tarefa.Etapas de implementação
-
Instale as dependências: Instale a dependência do DashScope (
pip install -U dashscope). - Crie e configure o pool de objetos Defina o tamanho do pool entre 1,5x e 2x a concorrência de pico, sem exceder o limite de QPS da sua conta. Crie um pool singleton global (o estabelecimento da conexão durante a inicialização leva algum tempo):
-
Solicite um objeto
SpeechSynthesizerdo pool Se a quantidade de objetos não devolvidos exceder a capacidade do pool, o sistema criará objetos adicionais. Esses objetos extras precisam estabelecer novas conexões e não se beneficiam do pooling.
-
Execute a síntese de fala
Chame o método call ou streaming_call do objeto
SpeechSynthesizerpara sintetizar a fala. -
Devolva o objeto
SpeechSynthesizerDevolva o objeto após a conclusão da tarefa para disponibilizá-lo para reutilização. Não devolva objetos com tarefas incompletas ou falhas.
Código completo
Gerenciamento de recursos e tratamento de erros
-
Tarefa bem-sucedida: Após a conclusão normal de uma tarefa de síntese, chame
connectionPool.return_synthesizer(speech_synthesizer)para devolver o objetoSpeechSynthesizerao pool para reutilização. -
Falha na tarefa: Se um erro interno do SDK ou uma exceção de lógica de negócio causar a interrupção da tarefa, feche a conexão WebSocket subjacente:
speech_synthesizer.close() -
Após a conclusão de todas as tarefas de síntese, encerre o pool:
connectionPool.shutdown() - Quando ocorrer um erro TaskFailed no lado do servidor, nenhum tratamento adicional é necessário.
Modelos e regiões suportados
- Singapore
- China (Beijing)
- Qwen-Audio-TTS: qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash
- Qwen-Audio-TTS/CosyVoice: cosyvoice-v3-plus, cosyvoice-v3-flash
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash-Realtime: qwen3-tts-instruct-flash-realtime (estável, atualmente equivalente a qwen3-tts-instruct-flash-realtime-2026-01-22), qwen3-tts-instruct-flash-realtime-2026-01-22 (snapshot mais recente)
- Qwen3-TTS-VD-Realtime: qwen3-tts-vd-realtime-2026-01-15 (snapshot mais recente), qwen3-tts-vd-realtime-2025-12-16 (snapshot)
- Qwen3-TTS-VC-Realtime: qwen3-tts-vc-realtime-2026-01-15 (snapshot mais recente), qwen3-tts-vc-realtime-2025-11-27 (snapshot)
- Qwen3-TTS-Flash-Realtime: qwen3-tts-flash-realtime (estável, atualmente equivalente a qwen3-tts-flash-realtime-2025-11-27), qwen3-tts-flash-realtime-2025-11-27 (snapshot mais recente), qwen3-tts-flash-realtime-2025-09-18 (snapshot)
Vozes suportadas
Diferentes modelos suportam diferentes vozes. Defina o parâmetro de requisição voice com o valor indicado na coluna parâmetro voice da lista de vozes correspondente.
Referência da API
- Real-time speech synthesis - Qwen-Audio-TTS/CosyVoice API reference
- Real-time speech synthesis - Qwen-TTS API reference
- AOQ client SDK (para modelos CosyVoice)
FAQ
P: Como corrigir pronúncia incorreta na síntese de fala? Como controlar a pronúncia de caracteres polifônicos?
- Substitua o caractere polifônico por um homófono para corrigir rapidamente o problema de pronúncia.
- Use marcação SSML para controlar a pronúncia .
P: Como solucionar áudio mudo ao usar uma voz clonada?
-
Verifique o status da voz
Chame a interface Voice cloning/design API e confirme se o
statusda voz éOK. -
Verifique a consistência da versão do modelo
Certifique-se de que o parâmetro
target_modelusado durante a clonagem de voz corresponda ao parâmetromodelusado para a síntese de fala. Por exemplo:- A clonagem utilizou
cosyvoice-v3-plus - A síntese também deve utilizar
cosyvoice-v3-plus
- A clonagem utilizou
-
Verifique a qualidade do áudio de origem
Confira se o áudio de origem usado para clonagem de voz atende aos requisitos em Voice cloning/design API:
- Duração do áudio: 10-20 segundos
- Qualidade de áudio nítida
- Sem ruído de fundo
-
Verifique os parâmetros da requisição
Confirme se o parâmetro
voicena requisição de síntese de fala está definido com o ID da voz clonada.
P: O que fazer se o áudio sintetizado de uma voz clonada estiver instável ou incompleto?
Se o áudio sintetizado de uma voz clonada apresentar algum dos problemas a seguir:
- Reprodução de áudio incompleta, com apenas parte do texto falado
- Qualidade de síntese inconsistente
- Áudio contém pausas anormais ou segmentos silenciosos
P: Por que a duração real do áudio sintetizado difere da duração mostrada no arquivo WAV?
A síntese de fala utiliza um mecanismo de streaming que retorna dados à medida que são gerados. A duração no cabeçalho do arquivo WAV salvo é uma estimativa e pode ser imprecisa. Para obter a duração exata, defina o formato como pcm, aguarde o resultado completo da síntese e adicione o cabeçalho do arquivo WAV manualmente.
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?
Faça a solução de problemas seguindo estas etapas:
- Verifique os intervalos de entrada Para síntese em streaming, verifique se o intervalo de envio de texto está muito longo. Intervalos longos aumentam o tempo total de síntese.
-
Analise as métricas de desempenho
- Latência do primeiro pacote: normalmente em torno de 500 ms.
- RTF (Fator de Tempo Real = tempo total de síntese / duração do áudio): deve ser menor que 1,0.