Pré-requisitos
Qwen-Audio-TTS
Endpoint do service
O endpoint do SDK é determinado pelos parâmetros de construção workspace/region do Client (correspondente ao endereço abaixo, incluindo o WorkspaceId). Para alternar para outra região, altere os parâmetros de construção do Client para os valores da região desejada.
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSubstitua {WorkspaceId} pelo seu workspace ID real.CosyVoice
Endpoint do service
O endpoint do SDK é determinado pelos parâmetros workspace e region do construtor do Client (correspondem aos endereços abaixo, que incluem o WorkspaceId). Para alternar para outra região, altere os parâmetros de construção do Client para os valores da região desejada.
- Singapore
- China (Beijing)
- CLI dashscope
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSubstitua {WorkspaceId} pelo seu ID do workspace real.Início rápido
Qwen-Audio-TTS
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 recebe os dados de áudio (possivelmente em fragmentos) por meio da iteração dos fragmentos retornados por
stream. 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 recebe o áudio sintetizado incrementalmente em tempo real por meio da iteração de
audio_chunks()/events()da sessão. Mais adequado para cenários de texto longo que exigem baixa latência.
- Sem streaming
- Streaming unidirecional
- Streaming bidirecional
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite causa um erro.
CosyVoice
O SDK fornece as interfaces principais da síntese de fala e suporta os seguintes modos de chamada:
- 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 recebe os dados iterando os blocos de áudio retornados por
stream. Mais adequado para cenários de texto curto que exigem alta capacidade de resposta em tempo real. - Streaming bidirecional: uma chamada não bloqueante que envia texto em vários segmentos e recebe em tempo real o fluxo de áudio sintetizado incrementalmente por meio da iteração de
audio_chunks()/events()da sessão. Mais adequado para cenários de texto longo que exigem alta capacidade de resposta em tempo real.
- Sem streaming
- Streaming unidirecional
- Streaming bidirecional
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite dispara uma exceção
DashScopeError.Parâmetros da solicitação
Qwen-Audio-TTS
Os parâmetros a seguir são definidos por meio dos métodos synthesize/stream/connect de client.audio.tts, para controlar o modelo, a voz, o formato e as características do áudio (model, voice, format, sample_rate, volume, rate, pitch, language_hints e enable_ssml são parâmetros nomeados; os demais são passados por meio do dicionário parameters).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
voice | str | Sim | A voz utilizada para a síntese de fala.
|
format | str | Não | Formato de codificação de áudio.Padrão: mp3.Aceita mp3, wav, pcm e outros formatos; a taxa de amostragem é definida por meio do parâmetro sample_rate, cujo padrão é 22050. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
rate | float | Não | A velocidade da fala.Valor padrão: 1,0.Valores válidos: [0,5, 2,0]. |
pitch | 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 dicionário parameters: |
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 clonadas são suportadas. Para as vozes do sistema compatíveis, consulte Qwen-Audio-TTS voice list.Defina word_timestamp_enabled por meio do dicionário parameters: |
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 | Para as vozes multilíngues e dialetais do qwen-audio-3.1-tts-flash, este parâmetro define o idioma ou dialeto. Para mais detalhes, consulte a seção de configuração de vozes multilíngues e dialetais.
Valores válidos
|
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.Defina enable_aigc_tag, aigc_propagator e aigc_propagate_id por meio do dicionário parameters: |
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.Defina por meio do dicionário parameters; 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.Defina por meio do dicionário parameters; 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.Parâmetros:
|
CosyVoice
Os parâmetros a seguir são definidos por meio dos métodos synthesize/stream/connect de client.audio.tts, para controlar o modelo, a voz, o formato e as características do áudio (model, voice, format, sample_rate, volume, rate, pitch, language_hints e enable_ssml são parâmetros nomeados; os demais parâmetros são passados por meio do dicionário parameters).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
voice | str | Sim | A voz utilizada para a síntese de fala.
|
format | str | Não | Formato de codificação de áudio.Padrão: mp3.Suporta mp3, wav, pcm e outros formatos; a taxa de amostragem é definida pelo parâmetro sample_rate, com valor padrão de 22050. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
rate | float | Não | A velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | 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 dicionário parameters: |
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 cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, além de vozes do sistema marcadas como suportadas em CosyVoice Voice list. Vozes clonadas de outros modelos não suportam este recurso.Defina word_timestamp_enabled por meio do dicionário parameters: |
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:
Valores válidos
|
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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. enable_aigc_tag, aigc_propagator e aigc_propagate_id por meio do dicionário parameters: |
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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. parameters. 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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. parameters. 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 cosyvoice-v2.
|
enable_markdown_filter | bool | Não | Apenas vozes clonadas de cosyvoice-v3-flash suportam este recurso.
enable_markdown_filter por meio do dicionário parameters: |
Referência da API
Qwen-Audio-TTS
Consulte a referência atual de Qwen-Audio-TTS Python SDK.
Recurso principal (client.audio.tts)
Caminho do recurso: client.audio.tts
Funcionalidade: síntese de fala baseada em WebSocket, com três formas de chamada: síntese em uma etapa (synthesize), síntese em streaming (stream) e sessão de streaming bidirecional (connect).
Pontos de entrada de chamada
synthesize() - 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: Chamada sem streaming: bloqueia e retorna todos os dados de áudio de uma só vez. É mais adequada para textos curtos em que não há requisitos rígidos de tempo real. synthesize e stream criam a própria sessão a cada chamada; não é necessário reutilizar instâncias.
stream() - 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. |
Iterator[bytes], dados de áudio produzidos bloco a bloco.
Descrição: Síntese em streaming: envia o texto completo de uma só vez e produz o áudio bloco a bloco (Iterator[bytes]). É adequada para cenários de síntese de textos curtos com altos requisitos de tempo real. Para enviar o texto em segmentos, use a sessão de streaming bidirecional (connect).
send_text() - entrada em streaming (método da sessão)
Envie o texto em segmentos na sessão de streaming bidirecional (client.audio.tts.connect(...)).
Assinatura do método:
text é o segmento de texto a ser sintetizado. O método send_text pode ser chamado várias vezes para anexar texto: no máximo 20.000 caracteres por chamada e no máximo 200.000 caracteres acumulados. O envio do texto e o recebimento do áudio devem ocorrer de forma concorrente (use em conjunto com audio_chunks()/events() e stop).
stop() - finalizar a entrada em streaming (método da sessão)
Assinatura do método:audio_chunks()/events() 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.
cancel() - cancelar a síntese em streaming (método da sessão)
Assinatura do método:Métricas e resposta da sessão (atributos da sessão)
first_package_delay:float, tempo de atraso (em milissegundos) entre o envio do texto e o recebimento do primeiro bloco de dados de áudio. Deve ser lido após a conclusão da síntese.usage:dict, informações de uso da tarefa de síntese mais recente.last_response:dict, mensagem de resposta da tarefa de síntese mais recente (contém as chavesheader/payload). O request_id da solicitação mais recente pode ser obtido noheaderdesession.last_responsee usado para solução de problemas e correlação de logs.
Iteração de sessão e eventos
A síntese em streaming não usa mais interfaces de callback: o áudio e os eventos do servidor são recebidos por meio dos métodos de iteração da sessão. stream()/synthesize() não exigem gerenciamento de sessão; o ciclo de vida da sessão de streaming bidirecional (client.audio.tts.connect(...)) é: entrar no contexto with (a conexão é estabelecida automaticamente) → vários send_text() → stop() → ler todos os resultados → sair do contexto (a conexão é fechada automaticamente).
audio_chunks() - iterar dados de áudio
Assinatura do método:Iterator[bytes], fragmentos de dados binários de áudio produzidos bloco a bloco, no formato especificado pelo parâmetro format.
Descrição: Itere na thread de recepção para receber os dados de áudio bloco a bloco; vários blocos são produzidos durante a síntese. Os dados podem ser gravados em um arquivo ou enviados a um dispositivo de reprodução. Cada sessão permite apenas um leitor de events() ou audio_chunks().
events() - iterar eventos do servidor
Assinatura do método:dict, contendo header (informações da solicitação) e payload (informações de saída)) e os bytes de áudio. O campo payload.output contém o tipo de evento, o texto original e outras informações; consulte o campo output nos eventos de events().
Descrição: Itere na thread de recepção as respostas do servidor, que contêm as informações de saída dos eventos de síntese (tipo de evento, texto original, informações da frase etc.); acesse payload.output diretamente para obter detalhes.
Tratamento de erros
Quando ocorre um erro durante a síntese, a camada ws lança uma exceçãoDashScopeError e a conexão é fechada automaticamente. Capture a exceção com try/except no envio/recebimento e registre o log de erros para facilitar a solução de problemas:
Ciclo de vida da sessão
- Ao entrar no contexto
with, a conexão é estabelecida automaticamente (antes disso, é possível inicializar fluxos de saída de áudio ou abrir arquivos e outros recursos). - Após todo o texto ser sintetizado e todos os dados de áudio produzidos, a iteração de
events()/audio_chunks()termina; a partir daí, métricas de desempenho comofirst_package_delaypodem ser lidas. - Ao sair do contexto
with, a conexão é fechada automaticamente (após isso, é possível liberar recursos, como dispositivos de reprodução de áudio).
Campo output nos eventos de events()
No dict de evento produzido pela iteração events() da sessão, o campo payload.output contém as informações de saída do 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: sentence-begin (síntese da frase iniciada), sentence-synthesis (síntese da frase em andamento) ou sentence-end (síntese da frase concluída). |
original_text | str | O texto original da frase atual. Retornado nos eventos sentence-begin e sentence-end. |
sentence | dict | Informações da frase. Contém index (número sequencial da frase) e words (lista de palavras com informações de carimbo de data/hora quando word_timestamp_enabled está ativado). |
CosyVoice
Consulte a referência atual de CosyVoice Python SDK.
Recurso principal (client.audio.tts)
Caminho do recurso: client.audio.tts
Função: síntese de fala baseada em WebSocket, com três formas de chamada: síntese em uma etapa (synthesize), síntese em streaming (stream) e sessão com streaming bidirecional (connect).
Ponto de entrada de chamada
synthesize() - 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, todos os dados de áudio.
Descrição: chamada sem streaming, bloqueia e retorna todos os dados de áudio de uma só vez. Adequada para textos curtos sem requisitos estritos de tempo real. synthesize e stream criam a própria sessão a cada chamada; não é necessário reutilizar instâncias.
stream() - com 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. |
Iterator[bytes], dados de áudio produzidos bloco a bloco.
Descrição: síntese em streaming que envia o texto completo de uma só vez e produz o áudio bloco a bloco (Iterator[bytes]). Adequada para cenários de síntese de fala de textos curtos que exigem alta capacidade de resposta em tempo real. Para enviar o texto em segmentos, use a sessão com streaming bidirecional (connect).
send_text() - entrada em streaming (método da sessão)
Envia o texto em segmentos em uma sessão com streaming bidirecional (client.audio.tts.connect(...)).
Assinatura do método:
text é o segmento de texto atual a ser sintetizado. Chame send_text várias vezes para anexar texto; máximo por chamada: 20.000 caracteres, máximo cumulativo: 200.000 caracteres. O envio de texto e o recebimento de áudio devem ocorrer de forma concorrente (use em conjunto com audio_chunks()/events() e stop).
stop() - finalizar entrada em streaming (método da sessão)
Assinatura do método:audio_chunks()/events() 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.
cancel() - cancelar síntese em streaming (método da sessão)
Assinatura do método:Métricas e respostas da sessão (atributos da sessão)
first_package_delay:float, a latência em milissegundos entre o envio do texto e o recebimento do primeiro bloco de dados de áudio. Deve ser lido após a conclusão da síntese.usage:dict, informações de uso da tarefa de síntese mais recente.last_response:dict, mensagem de resposta da tarefa de síntese mais recente (com as chavesheader/payload). O request_id da solicitação mais recente pode ser obtido noheaderdesession.last_response, útil para solução de problemas e correlação de logs.
Sessão e iteração de eventos
A síntese em streaming não usa mais interfaces de callback: o áudio e os eventos do servidor são recebidos por meio dos métodos de iteração da sessão. stream()/synthesize() não exigem gerenciamento de sessão; o ciclo de vida de uma sessão com streaming bidirecional (client.audio.tts.connect(...)) é: entrada no contexto with com conexão estabelecida automaticamente → múltiplas chamadas de send_text() → stop() → leitura de todos os resultados → saída do contexto com fechamento automático da conexão.
audio_chunks() - iterar dados de áudio
Assinatura do método:Iterator[bytes], fragmentos de dados binários de áudio produzidos bloco a bloco, no formato especificado pelo parâmetro format.
Descrição: Itere na thread receptora para receber os dados de áudio bloco a bloco; durante a síntese, vários blocos são produzidos. Grave os dados em um arquivo ou envie-os a um dispositivo de reprodução. A mesma sessão permite apenas um leitor de events() ou audio_chunks().
events() - iterar eventos do servidor
Assinatura do método:dict, contendo header (informações da solicitação) e payload (informações de saída)) e bytes de áudio. O campo payload.output contém o tipo de evento, o texto original e outros detalhes. Consulte campo output nas mensagens de events().
Descrição: Itere as respostas do servidor na thread receptora; elas contêm as informações de saída dos eventos de síntese (tipo de evento, texto original, informações da frase etc.). Acesse diretamente payload.output para obter detalhes.
Tratamento de erros
Quando ocorre um erro durante a síntese, a camada WebSocket lança uma exceçãoDashScopeError e a conexão é fechada automaticamente após a exceção ser lançada. Use try/except no envio/recebimento para capturar e registrar os erros para solução de problemas:
Ciclo de vida da sessão
- A conexão é estabelecida automaticamente na entrada do contexto
with(inicialize fluxos de saída de áudio ou abra recursos de arquivo antes disso). - Após todo o texto ser sintetizado e todos os dados de áudio serem produzidos, a iteração de
events()/audio_chunks()termina; depois disso é possível ler métricas de desempenho comofirst_package_delay. - A conexão é fechada automaticamente na saída do contexto
with(libere dispositivos de reprodução de áudio e outros recursos em seguida).
Campo output nas mensagens de events()
O evento dict produzido pela iteração de events() da sessão 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: sentence-begin (síntese da frase iniciada), sentence-synthesis (síntese da frase em andamento) ou sentence-end (síntese da frase concluída). |
original_text | str | O texto original da frase atual. Retornado nos eventos sentence-begin e sentence-end. |
sentence | dict | Informações da frase. Contém index (número sequencial da frase) e words (lista de palavras com informações de carimbo de data/hora quando word_timestamp_enabled está ativado). |