Skip to main content

SDK Python

Este tópico descreve as principais interfaces e os parâmetros de solicitação para chamar os modelos da série Qwen-TTS-Realtime com o DashScope Python SDK.

Pré-requisitos

Requer o DashScope Python SDK 2.0.1 ou posterior.

Primeiros passos

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo por: api_key = "sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # A configuração abaixo refere-se à região Pequim (China). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Thread de recebimento: itera sobre os eventos do servidor e grava o áudio no arquivo de forma incremental
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Cria uma sessão de síntese de fala em tempo real: entrar no contexto with estabelece a conexão automaticamente
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Notifica o servidor de que a entrada foi concluída (no modo server_commit o servidor decide quando sintetizar)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

# As API Keys das regiões Singapura e China (Pequim) não são intercambiáveis. Obtenha sua API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo por: api_key = "sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 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.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Thread de recebimento: itera sobre os eventos do servidor e grava o áudio no arquivo de forma incremental
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Cria uma sessão de síntese de fala em tempo real: entrar no contexto with estabelece a conexão automaticamente
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Notifica o servidor de que a entrada foi concluída (no modo server_commit o servidor decide quando sintetizar)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
Acesse o GitHub para baixar mais códigos de exemplo.

Parâmetros de solicitação

Os parâmetros de solicitação a seguir podem ser definidos no método connect de client.audio.realtime:

Parâmetro

Tipo

Obrigatório

Descrição

model

str

Sim

Nome do modelo (consulte Modelos compatíveis).

ws_url

str

Não

Endpoint da sessão. Quando omitido, é derivado automaticamente dos parâmetros de construção workspace/region do Client (região China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime; região Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime).

Os parâmetros de solicitação a seguir podem ser configurados por meio do método update_session da sessão (os parâmetros nomeados são passados diretamente e os demais são repassados ao objeto session do evento session.update):

Parâmetro

Tipo

Obrigatório

Descrição

voice

str

Sim

Voz usada na síntese de fala. Para mais informações, consulte Lista de vozes do Qwen-TTS.

language_type

str

Não

Define o idioma do áudio sintetizado. O valor padrão é Auto.

  • Auto: Use este valor quando o idioma do texto for incerto ou houver vários idiomas. O modelo ajusta automaticamente a pronúncia para diferentes segmentos de idioma no texto, mas não garante precisão total.

  • Idioma específico: Use esta opção para textos em um único idioma. Especificar um idioma melhora significativamente a qualidade da síntese e geralmente produz resultados melhores que Auto. Os valores válidos incluem:

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

Não

Modo de interação. Valores válidos:

  • server_commit (padrão): O servidor determina automaticamente quando sintetizar a fala, equilibrando latência e qualidade. Recomendado para a maioria dos cenários.

  • commit: O cliente aciona manualmente a síntese. Este modo oferece a menor latência, mas exige que você gerencie a integridade das frases por conta própria.

response_format

str

Não

Formato da saída de áudio do modelo.

Formatos compatíveis:

  • pcm (padrão)

  • wav

  • mp3

  • opus

sample_rate

int

Não

Taxa de amostragem da saída de áudio do modelo, em Hz.

Taxas de amostragem compatíveis:

  • 8000

  • 16000

  • 24000 (padrão)

  • 48000

speech_rate

float

Não

Velocidade da fala do áudio. O valor 1,0 representa a velocidade normal. Valores menores que 1,0 tornam a fala mais lenta; valores maiores que 1,0 a tornam mais rápida.

Valor padrão: 1,0.

Intervalo válido: [0,5, 2,0].

volume

int

Não

Volume do áudio.

Intervalo válido: [0, 100].

pitch_rate

float

Não

Tom do áudio sintetizado.

Valor padrão: 1,0.

Intervalo válido: [0,5, 2,0].

bit_rate

int

Não

Define a taxa de bits do áudio em kbps. Uma taxa de bits maior resulta em melhor qualidade de áudio e tamanho de arquivo maior. Este parâmetro está disponível apenas quando o formato de áudio (response_format) está definido como opus.

Valor padrão: 128.

Intervalo válido: [6, 510].

Principais interfaces

Sessão (RealtimeSession)

A sessão de síntese de fala em tempo real é criada por meio de client.audio.realtime.connect(model=...); a conexão é estabelecida automaticamente ao entrar no contexto with (também é possível chamar o método connect() da sessão para estabelecê-la manualmente).
Assinatura do métodoEventos de resposta do servidor (entregues por iteração via events())Descrição
def connect(self) -> "RealtimeSession"
session.created
Sessão criada
session.updated
Configuração da sessão atualizada
Cria a conexão com o servidor. Chamado automaticamente ao entrar no contexto with.
def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **kwargs) -> None
session.updated
Configuração da sessão atualizada
Atualiza as configurações padrão desta sessão. Para detalhes dos parâmetros, consulte Parâmetros de solicitação.Ao estabelecer a conexão, o servidor retorna prontamente as configurações padrão de entrada e saída desta sessão. Se você precisar atualizar as configurações padrão, recomendamos chamar este método imediatamente após estabelecer a conexão.Ao receber um evento session.update, o servidor valida os parâmetros; se forem inválidos, retorna um erro; caso contrário, atualiza a configuração da sessão no lado do servidor.
def send_event(self,
               event: Dict[str, Any]) -> None
NenhumEnvia um evento bruto. A entrada de texto é feita por meio da série de eventos input_text_buffer: anexe trechos de texto ao buffer de texto de entrada na nuvem ({"type": "input_text_buffer.append", "text": ...}). O buffer é um armazenamento temporário no qual você grava e que pode ser confirmado posteriormente.
  • No modo "server_commit", o servidor decide quando confirmar e sintetizar o texto no buffer.
  • No modo "commit", o cliente deve enviar ativamente o evento input_text_buffer.commit para acionar a síntese de fala.
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.cleared
Limpa o texto recebido pelo servidor
Envia o evento {"type": "input_text_buffer.clear"} para excluir o texto atual do buffer na nuvem.
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.committed
Envia o texto e aciona a síntese de fala
response.output_item.added
Novo conteúdo de saída adicionado
response.content_part.added
Novo conteúdo adicionado à mensagem do assistente
response.audio.delta
Áudio incremental gerado pelo modelo
response.audio.done
Geração de áudio concluída
response.content_part.done
Streaming de conteúdo de áudio para mensagem do assistente concluído
response.output_item.done
Streaming de todo o item de saída para mensagem do assistente concluído
response.done
Resposta concluída
Envia o evento {"type": "input_text_buffer.commit"} para confirmar o texto adicionado anteriormente ao buffer na nuvem por meio de append e sintetizar imediatamente todo o texto. Um erro será gerado se o buffer de texto estiver vazio.
  • No modo "server_commit", o cliente não precisa enviar este evento; o servidor confirma o buffer de texto automaticamente.
  • No modo "commit", o cliente deve acionar a síntese de fala por meio de commit.
def end_session(self) -> None
session.finished
Resposta concluída
Envia o evento session.finish para encerrar a tarefa. Em seguida, continue consumindo events() até receber o evento session.finished.
def close(self, ) -> None
NoneFecha a conexão. Chamado automaticamente ao sair do contexto with.
session.session_id
NenhumObtém o session_id da tarefa atual.
session.last_response_id
NenhumObtém o response_id da resposta mais recente.
session.last_first_audio_delay
NenhumObtém o atraso do primeiro pacote de áudio.

Iteração de eventos (events())

O servidor retorna os eventos e dados de resposta ao cliente por meio de eventos. Na thread de recebimento, itere sobre events() da sessão para processar os eventos do servidor; a iteração termina após o evento session.finished; eventos de error são lançados como exceções DashScopeError e podem ser capturados com try/except.
MétodoParâmetrosValor de retornoDescrição
def events(self) -> Iterator[Dict]
event: evento de resposta do servidor (dict).IteradorInclui as respostas às chamadas de interface e o texto e o áudio gerados pelo modelo; a iteração termina após o evento session.finished. Para mais detalhes, consulte Eventos do servidor.
def recv_event(self) -> Optional[Dict]
event: evento de resposta do servidor (dict).Evento ou NoneLê um evento do servidor; retorna None após um fechamento normal.