Utilize o DashScope Python SDK para integrar a síntese de fala em tempo real do Qwen-Audio-TTS à sua aplicação por meio dos modos sem streaming, streaming unidirecional ou streaming bidirecional.
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.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.
Parâmetros da solicitação
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 | 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.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:
|
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ção DashScopeError 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). |
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 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.