Skip to main content

Qwen-Audio-TTS Python SDK

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.
Alternar para a região de Singapore:
import os
import dashscope

# Especifique a região ao construir o Client
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

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

# Síntese em uma etapa: retorna os bytes de áudio completos
audio = client.audio.tts.synthesize(
    text,                      # text é obrigatório (argumento posicional)
    model="qwen-audio-3.0-tts-flash", # O modelo ao qual a voz pertence
    voice="longanhuan_v3.6",   # A voz
    format="mp3",              # Formato de codificação de áudio; padrão "mp3"
    sample_rate=22050,         # Taxa de amostragem; padrão 22050
)

# Síntese em streaming: produz os bytes de áudio bloco a bloco (grave/reproduza durante o recebimento)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
    ...

# Sessão de streaming bidirecional: envie o texto em segmentos; a conexão é estabelecida automaticamente ao entrar no contexto with
with client.audio.tts.connect(model=..., voice=...) as session:
    session.send_text(text)    # Pode ser chamado várias vezes para anexar texto
    session.stop()             # Notifica o servidor de que a entrada terminou
    for chunk in session.audio_chunks():
        ...

synthesize() - sem streaming

Assinatura do método:
def synthesize(self, text: str, *, model: str,
               voice: str, format: str = "mp3",
               sample_rate: int = 22050, volume: int = None,
               rate: float = None, pitch: float = None,
               language_hints: list = None, enable_ssml: bool = None,
               parameters: Dict = None, ...) -> bytes
Parâmetros:
ParâmetroTipoObrigatórioDescrição
textstrSimO texto completo a ser sintetizado. Comprimento máximo: 20.000 caracteres.
Valor de retorno: 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:
def stream(self, text: str, *, model: str, voice: str,
           format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
Parâmetros:
ParâmetroTipoObrigatórioDescrição
textstrSimUm 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.
Valor de retorno: 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:
def send_text(self, text: str) -> None
Parâmetros: 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:
def stop(self) -> None
Descrição: Notifica o servidor de que todo o texto foi enviado. Não bloqueia a thread atual; a thread de recepção deve continuar consumindo 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:
def cancel(self) -> None
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. Após o cancelamento, a sessão atual não pode mais enviar texto; para continuar sintetizando, crie uma nova sessão.

Métricas e resposta da sessão (atributos da sessão)

session.first_package_delay
session.usage
session.last_response
  • 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 chaves header/payload). O request_id da solicitação mais recente pode ser obtido no header de session.last_response e 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âmetroTipoObrigatórioDescrição
modelstrSimO nome do modelo.
voicestrSimA voz utilizada para a síntese de fala.
  • Vozes do sistema: Consulte Qwen-Audio-TTS voice list
  • Vozes clonadas: Vozes personalizadas criadas por meio de clonagem de voz
  • Vozes personalizadas: Vozes personalizadas criadas por meio de design de voz
formatstrNãoFormato 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.
volumeintNãoO nível de volume.Valor padrão: 50.Valores válidos: [0, 100].
ratefloatNãoA velocidade da fala.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
pitchfloatNãoO tom da voz.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
bit_rateintNãoA 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:
audio = client.audio.tts.synthesize(
    "Texto a ser sintetizado",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledboolNãoEspecifica 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:
audio = client.audio.tts.stream(
    "Texto a ser sintetizado",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # Uma voz do sistema ou clonada compatível com timestamps no nível da palavra
    parameters={"word_timestamp_enabled": True},
)
seedintNãoUma 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_hintslist[str]Não
  • Este parâmetro é um array, mas a versão atual processa apenas o primeiro elemento. Passe um único valor.
  • Este parâmetro especifica o idioma alvo para a síntese de fala. Ele não está relacionado ao idioma da amostra de áudio usada na clonagem de voz. Para definir o idioma de origem de uma tarefa de clonagem, consulte a referência da API de clonagem de voz.
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:
  • Pronúncia inesperada de dígitos: "olá, isto é 110" é lido como "olá, isto é um zero" em vez da pronúncia chinesa esperada
  • Pronúncia imprecisa de símbolos: "@" é lido como o equivalente chinês em vez de "at"
  • Baixa qualidade na síntese de idiomas minoritários com resultados pouco naturais
  • zh: Chinês
  • en: Inglês
  • fr: Francês
  • de: Alemão
  • ja: Japonês
  • ko: Coreano
  • ru: Russo
  • pt: Português
  • th: Tailandês
  • id: Indonésio
  • vi: Vietnamita
  • es: Espanhol
  • it: Italiano
  • ms: Malaio
  • fil: Filipino
  • ar: Árabe
  • other: Outros idiomas (compatíveis com qwen-audio-3.1-tts-flash) búlgaro, holandês, húngaro, romeno, dinamarquês, croata, grego, tcheco, norueguês, sueco, hindi, eslovaco, finlandês, urdu, sérvio, espanhol (México), lituano, letão, turco, persa, hebraico, mongol, esloveno, azerbaijano, polonês, catalão, khmer, português (Brasil), laosiano, georgiano, africâner, nepalês, bielorrusso, malaiala, luxemburguês, albanês, tâmil, cingalês, télugo, estoniano, cebuano, bósnio, birmanês, armênio, latim, islandês, maltês, suaíli, cazaque, crioulo francês seichelense, ucraniano.
instructionstrNãoControla características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Instruction control.
enable_aigc_tagboolNãoEspecifica 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:
audio = client.audio.tts.synthesize(
    "Texto a ser sintetizado",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstrNãoDefine 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_idstrNãoDefine 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_fixdictNãoConfigura correções de pronúncia e substituições de texto aplicadas antes da síntese.Parâmetros:
  • pronunciation: Pronúncia personalizada. Especifica anotações de pinyin para palavras a fim de corrigir pronúncias padrão imprecisas.
  • replace: Substituição de texto. Substitui palavras especificadas pelo texto alvo antes da síntese. O texto substituído é usado como entrada real da síntese.
Exemplo:
audio = client.audio.tts.synthesize(
    "Texto a ser sintetizado",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice_id", # A voz
    parameters={
        "hot_fix": {
            "pronunciation": [{"weather": "tian1 qi4"}],
            "replace": [{"today": "gold day"}]
        }
    },
)

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:
def audio_chunks(self) -> Iterator[bytes]
Valor de retorno: 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:
def events(self) -> Generator[Union[Dict, bytes], None, None]
Valor de retorno: Produz simultaneamente os eventos de resposta do servidor (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:
from dashscope.v2 import DashScopeError

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

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 como first_package_delay podem 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:
CampoTipoDescrição
typestrTipo 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_textstrO texto original da frase atual. Retornado nos eventos sentence-begin e sentence-end.
sentencedictInformaçõ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).
Exemplo de mensagem:
{
  "header": {
    "task_id": "xxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "type": "sentence-begin",
      "original_text": "How is the weather today?",
      "sentence": {
        "index": 0,
        "words": []
      }
    }
  }
}
Exemplo de análise:
def handle_event(event):
    output = (event.get('payload') or {}).get('output') or {}
    event_type = output.get('type', '')
    original_text = output.get('original_text', '')
    if event_type:
        print(f'Tipo de evento: {event_type}, Texto original: {original_text}')

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.
synthesize e stream criam a própria sessão a cada chamada; não é necessário reutilizar instâncias.
# coding=utf-8

import os

import dashscope

# A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Modelo
model = "qwen-audio-3.0-tts-flash"
# Voz
voice = "longanhuan_v3.6"

# Envia o texto para síntese e obtém o áudio binário
audio = client.audio.tts.synthesize("How is the weather today?", model=model, voice=voice)

# Salva o áudio em um arquivo local
with open('output.mp3', 'wb') as f:
    f.write(audio)