Utilize o DashScope Python SDK para integrar a síntese de fala em tempo real do Qwen-Audio-TTS/CosyVoice à sua aplicação por meio dos modos sem streaming, streaming unidirecional ou streaming bidirecional.
Guia do usuário: Para descrições de modelos e recomendações de seleção, consulte Speech synthesis.
O SDK utiliza o endpoint da região de Beijing por padrão. Para alterar para outra região, modifique
Alternar para a região de Singapore:
Caminho do pacote:
Assinatura do método:
Parâmetros:
Valor de retorno:
Assinatura do método:
Parâmetros:
Descrição: Esta chamada de streaming bidirecional aceita texto em segmentos e entrega o áudio sintetizado por meio de callbacks em tempo real. É ideal para integração com grandes modelos de linguagem, onde o texto é gerado progressivamente. Chame streaming_complete() após enviar todo o texto.
Assinatura do método:
Descrição: Notifica o servidor de que todo o texto foi enviado. Bloqueia a thread atual até que o texto restante seja sintetizado e todos os dados de áudio sejam retornados. A falha ao chamar este método pode resultar na não conversão do texto final em fala.
Assinatura do método:
Parâmetros:
Descrição: Cancela a rodada atual de síntese de fala em streaming. Após chamar este método, o SDK encerra imediatamente a tarefa atual. É possível iniciar uma nova tarefa de síntese na mesma conexão sem reinicializar a instância do
Assinatura do método:
Valor de retorno:
Assinatura do método:
Valor de retorno:
Assinatura do método:
Valor de retorno:
Os parâmetros a seguir são definidos por meio do construtor do SpeechSynthesizer para controlar o modelo, a voz, o formato e as características do áudio.
Caminho do pacote:
Assinatura do método:
Acionado quando: A conexão WebSocket é estabelecida com sucesso. Utilize este callback para inicializar fluxos de saída de áudio ou abrir recursos de arquivo.
Assinatura do método:
Parâmetros:
Acionado quando: Uma resposta do servidor é recebida. A mensagem é uma string JSON contendo a saída do evento de síntese (tipo de evento, texto original, informações da frase). Analise com
Assinatura do método:
Acionado quando: Todo o texto foi sintetizado e todos os dados de áudio foram entregues por meio de on_data. Utilize este callback para chamar get_first_package_delay() e obter métricas de desempenho.
Assinatura do método:
Parâmetros:
Acionado quando: Um fragmento de dados de áudio é recebido. Este callback é invocado várias vezes durante a síntese. Utilize-o para gravar dados em um arquivo ou alimentá-los em um dispositivo de reprodução.
Assinatura do método:
Parâmetros:
Acionado quando: Ocorre um erro durante a síntese. A conexão é fechada automaticamente após o disparo deste callback. Registre o erro para solução de problemas.
Assinatura do método:
Acionado quando: A conexão WebSocket é fechada (seja normalmente ou devido a um erro). Utilize este callback para liberar recursos, como dispositivos de reprodução de áudio.
A mensagem JSON recebida pelo callback
Exemplo de mensagem:
Exemplo de análise:
O SDK suporta os seguintes modos de síntese:
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite causa um erro.
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite causa um erro.
O texto enviado por chamada não deve exceder 20.000 caracteres. O texto cumulativo não deve exceder 200.000 caracteres.
Endpoint do service
O SDK utiliza o endpoint da região de Beijing por padrão. Para alterar para outra região, modifique dashscope.base_websocket_api_url antes da inicialização.
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSubstitua {WorkspaceId} pelo seu workspace ID real.SpeechSynthesizer
Caminho do pacote: dashscope.audio.tts_v2.SpeechSynthesizer
Construtor
call() - sem streaming
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | str | Sim | O texto completo a ser sintetizado. Comprimento máximo: 20.000 caracteres. |
bytes contendo os dados de áudio completos.
Descrição: Esta chamada bloqueante retorna todos os dados de áudio de uma só vez. É mais adequada para textos curtos em que o streaming em tempo real não é necessário. Reinicialize a instância do SpeechSynthesizer antes de cada chamada.
streaming_call() - com streaming
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | str | Sim | Um segmento de texto para sintetizar. Chame este método várias vezes para anexar texto. Máximo por chamada: 20.000 caracteres. Máximo cumulativo: 200.000 caracteres. |
streaming_complete() - finalizar streaming
Assinatura do método:
streaming_cancel() - cancelar síntese em streaming
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
complete_timeout_millis | int | Não | Tempo limite em milissegundos para aguardar o retorno do evento de tarefa concluída pelo servidor. Valor padrão: 10000. |
SpeechSynthesizer.
get_last_request_id() - obter ID da solicitação
Assinatura do método:
str contendo o ID da solicitação mais recente. Utilize-o para solução de problemas e rastreamento.
get_first_package_delay() - obter latência do primeiro pacote
Assinatura do método:
int representando o atraso em milissegundos entre o envio do texto e o recebimento do primeiro fragmento de áudio. Chame este método após a conclusão da síntese.
get_response() - obter mensagem de resposta
Assinatura do método:
str contendo a mensagem de resposta formatada em JSON da tarefa de síntese mais recente, incluindo o status da solicitação e informações de saída.
Parâmetros do construtor
Os parâmetros a seguir são definidos por meio do construtor do SpeechSynthesizer para controlar o modelo, a voz, o formato e as características do áudio.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | str | Sim | O nome do modelo. |
| voice | str | Sim | voicestring(obrigatório)A voz utilizada para a síntese de fala.
|
| format | enum | Não | Formato de codificação de áudio e taxa de amostragem.Padrão: AudioFormat.MP3_22050HZ_MONO_256KBPS.O enum AudioFormat está localizado em dashscope.audio.tts_v2 e suporta MP3, WAV, PCM e outros formatos. |
| volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
| speech_rate | float | Não | A velocidade da fala.Valor padrão: 1,0.Valores válidos: [0,5, 2,0]. |
| pitch_rate | float | Não | O tom da voz.Valor padrão: 1,0.Valores válidos: [0,5, 2,0]. |
| bit_rate | int | Não | A taxa de bits de áudio em kbps. Quando o formato de áudio for mp3 ou opus, utilize bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510].Defina bit_rate por meio do parâmetro additional_params: |
| word_timestamp_enabled | bool | Não | Especifica se os carimbos de data/hora no nível da palavra devem ser ativados.Valor padrão: false.Disponível apenas no modo de saída com streaming. Vozes suportadas: vozes clonadas de qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus e cosyvoice-v2, além de vozes do sistema marcadas como suportadas em Qwen-Audio-TTS voice list, CosyVoice Voice list. Vozes clonadas de outros modelos não suportam este recurso. Defina word_timestamp_enabled por meio do parâmetro additional_params: |
| seed | int | Não | Uma semente aleatória para controlar a variação na saída da síntese. Quando a versão do modelo, o texto, a voz e outros parâmetros permanecem inalterados, o uso da mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535]. |
| language_hints | list[str] | Não | Especifica o idioma alvo para a síntese de fala a fim de melhorar a qualidade da saída.Quando a pronúncia de dígitos, expansão de abreviações, leitura de símbolos ou síntese de idiomas minoritários não atender às expectativas, utilize este parâmetro. Por exemplo:
|
| instruction | str | Não | Controla características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Instruction control. |
| enable_aigc_tag | bool | Não | Especifica se uma marca d'água AIGC deve ser incorporada ao áudio gerado. Quando definido como true, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).Valor padrão: false.Apenas qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus e cosyvoice-v2 suportam este recurso. Defina enable_aigc_tag, aigc_propagator e aigc_propagate_id por meio do parâmetro additional_params: |
| aigc_propagator | str | Não | Define o campo ContentPropagator na marca d'água AIGC, identificando o propagador do conteúdo. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud.Apenas qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus e cosyvoice-v2 suportam este recurso.Defina por meio do parâmetro additional_params. Consulte o exemplo de enable_aigc_tag. |
| aigc_propagate_id | str | Não | Define o campo PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: O ID da solicitação de síntese de fala atual.Apenas qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus e cosyvoice-v2 suportam este recurso.Defina por meio do parâmetro additional_params. Consulte o exemplo de enable_aigc_tag. |
| hot_fix | dict | Não | Configura correções de pronúncia e substituições de texto aplicadas antes da síntese.This feature isn't supported by qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, or cosyvoice-v2.Parâmetros:
|
| enable_markdown_filter | bool | Não | Especifica se a filtragem de Markdown deve ser ativada. Quando ativado, o sistema remove automaticamente os símbolos de marcação Markdown do texto de entrada antes da síntese, evitando que sejam lidos em voz alta.Valor padrão: false.Valores válidos:
Defina enable_markdown_filter por meio do parâmetro additional_params: |
| callback | ResultCallback | Não | Uma instância de callback para receber áudio sintetizado e notificações de eventos de forma assíncrona. Quando definido, call() executa no modo de streaming e entrega o áudio por meio do callback on_data. Quando não definido, call() executa no modo sem streaming e retorna o áudio completo como bytes. |
ResultCallback
Caminho do pacote: dashscope.audio.tts_v2.ResultCallback
on_open() - conexão estabelecida
Assinatura do método:
on_event() - receber resposta do servidor
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
message | str | Sim | Um evento de resposta do servidor em formato JSON contendo |
json.loads(message) e acesse payload.output para obter detalhes.
on_complete() - síntese concluída
Assinatura do método:
on_data() - receber dados de áudio
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data | bytes | Sim | Um fragmento de dados binários de áudio no formato especificado pelo parâmetro format do construtor. |
on_error() - erro ocorrido
Assinatura do método:
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
message | str | Sim | Uma descrição do erro contendo o código de erro e o motivo detalhado. |
on_close() - conexão fechada
Assinatura do método:
Campo output nas mensagens on_event
A mensagem JSON recebida pelo callback on_event contém um campo payload.output com informações sobre o evento de síntese. Utilize este campo para acompanhar o progresso da síntese e recuperar detalhes por frase. A estrutura do campo output é a seguinte:
Campo | Tipo | Descrição |
|---|---|---|
type | str | Tipo de evento. Valores: |
original_text | str | O texto original da frase atual. Retornado nos eventos |
sentence | dict | Informações da frase. Contém |
Exemplos de código
O SDK suporta os seguintes modos de síntese:
- Sem streaming: Uma chamada bloqueante que envia o texto completo de uma só vez e retorna o áudio integral diretamente. Mais adequado para síntese de fala de textos curtos.
- Streaming unidirecional: Uma chamada não bloqueante que envia o texto completo de uma só vez e entrega dados de áudio (potencialmente em fragmentos) por meio de uma função de callback. Mais adequado para cenários de texto curto que exigem baixa latência.
- Streaming bidirecional: Uma chamada não bloqueante que envia texto em vários segmentos e entrega áudio sintetizado incrementalmente por meio de uma função de callback em tempo real. Mais adequado para cenários de texto longo que exigem baixa latência.
Sem streaming
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite causa um erro.
Streaming unidirecional
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite causa um erro.
Streaming bidirecional
O texto enviado por chamada não deve exceder 20.000 caracteres. O texto cumulativo não deve exceder 200.000 caracteres.
-
Durante a entrada em streaming, chame
streaming_callvárias vezes para enviar segmentos de texto em sequência. O servidor realiza automaticamente a segmentação de frases no texto recebido:- Frases completas são sintetizadas imediatamente
- Frases incompletas são armazenadas em buffer até serem concluídas
streaming_completeé chamado, o servidor força a síntese de todo o texto recebido, mas ainda não processado (incluindo frases incompletas). -
O intervalo entre segmentos de texto não deve exceder 23 segundos. Caso contrário, uma exceção "request timeout after 23 seconds" será gerada.
Se não houver texto para enviar, chame
streaming_completeprontamente para encerrar a tarefa.O servidor impõe um tempo limite de 23 segundos. Este valor não pode ser modificado no lado do cliente.