Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Qwen3-TTS SDK Python em tempo real

SDK Python TTS em tempo real

Guia: consulte Conversão de texto em fala em tempo real - Qwen ou Conversão de texto em fala - Qwen para detalhes do modelo.

Pré-requisitos

Requer DashScope Python SDK 1.25.11 ou posterior.

Primeiros passos

Dois modos de interação estão disponíveis: server commit (o servidor decide o tempo de síntese) e commit (o cliente aciona a síntese manualmente). Para exemplos completos e tutoriais, consulte Conversão de texto em fala em tempo real.

Parâmetros de solicitação

Defina-os no QwenTtsRealtime construtor.

Parâmetro	Tipo	Obrigatório	Descrição
modelo		Sim	Nome do modelo.
url		Sim	`wss://maas.qwencloudapi.com/api-ws/v1/realtime`

Defina-os com update_session.

Parâmetro	Tipo	Obrigatório	Descrição
voz		Sim	Voz para síntese. Vozes do sistema: disponíveis para Qwen3-TTS-Flash-Realtime série. Vozes personalizadas: vozes personalizadas criadas por meio de clonagem ou design de voz.
idioma_tipo		Não	Idioma de áudio de saída. Padrão: `Auto`. Usar `Auto` quando o idioma é incerto ou o texto mistura idiomas. Suportado: `Chinese`, `English`, `German`, `Italian`, `Portuguese`, `Spanish`, `Japanese`, `Korean`, `French`, `Russian`. Definir um idioma específico melhora a qualidade.
modo		Não	Modo de interação. `server_commit` (padrão): o servidor decide o tempo de síntese, equilibrando latência e qualidade. Melhor para a maioria dos casos de uso. `commit`: o cliente aciona a síntese manualmente com menor latência, mas você deve gerenciar os limites das frases.
formato		Não	Formato de áudio. Suportado: `pcm` (padrão), `wav`, `mp3`, `opus`. Qwen3-TTS-Flash-Realtime suporta apenas `pcm`.
amostra_taxa	interno	Não	Taxa de amostragem em Hz. Suportado: 8.000, 16.000, 24.000 (padrão), 48.000. Qwen3-TTS-Flash-Realtime suporta apenas 24.000.
fala_taxa	flutuar	Não	Multiplicador de taxa de fala. Padrão: 1,0 (normal). Faixa: [0,5, 2,0]. Não suportado por Qwen3-TTS-Flash-Realtime.
volume	interno	Não	Volume. Padrão: 50. Faixa: [0, 100]. Não suportado por Qwen3-TTS-Flash-Realtime.
pitch_taxa	flutuar	Não	Multiplicador de passo. Padrão: 1.0. Faixa: [0,5, 2,0]. Não suportado por Qwen3-TTS-Flash-Realtime.
bit_taxa	interno	Não	Taxa de bits em kbps. Valores mais altos melhoram a qualidade, mas aumentam o tamanho do arquivo. Somente para `opus` formato. Padrão: 128. Faixa: [6, 510]. Não suportado por Qwen3-TTS-Flash-Realtime.
instruções		Não	Instruções de controle de síntese. Consulte TTS de streaming em tempo real para obter detalhes. Padrão: Nenhum. Máx.: 1600 fichas. Suporta chinês e inglês. O controle de instrução migrou para CosyVoice modelos. Consulte Controle de instruções.
otimizar_instruções	bool	Não	Quando True, reescreve `instructions` para melhor naturalidade e expressividade. Padrão: Falso. Recomendado para controle de voz refinado. Requer `instructions` a ser definido. O controle de instrução migrou para CosyVoice modelos. Consulte Controle de instruções.

Interfaces principais

QwenTtsRealtime aula

Importar com from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime.

Assinatura do método	Eventos de resposta do servidor (via retorno de chamada)	Descrição
`def connect(self) -> None`	sessão.criada - Sessão criada. sessão.atualizada - Configuração da sessão atualizada.	Conecte-se ao servidor.
`def update_session(self, voice: str, response_format: AudioFormat = AudioFormat.PCM_24000HZ_MONO_16BIT, mode: str = 'server_commit', language_type: str = "Chinese", **kwargs) -> None`	sessão.atualizada - Configuração da sessão atualizada.	Atualize a configuração da sessão. Consulte Parâmetros de solicitação para obter detalhes. Ligue imediatamente após conectar para substituir os padrões. Parâmetros inválidos retornam um erro; parâmetros válidos atualizam a configuração.
`def append_text(self, text: str) -> None`	Nenhum	Anexe texto ao buffer de entrada da nuvem. Em `server_commit` modo, o servidor decide quando sintetizar o texto em buffer. Em `commit` modo, chamada `commit` para desencadear a síntese.
`def clear_appended_text(self) -> None`	entrada_text_buffer.cleared - Buffer limpo.	Limpe todo o texto no buffer da nuvem.
`def commit(self) -> None`	input_text_buffer.comprometido - Texto enviado. response.output_item.added - Item de saída adicionado. response.content_part.added - Parte de conteúdo adicionada. response.audio.delta - Dados de áudio incrementais. response.audio.done - Geração de áudio concluída. response.content_part.done - Streaming de conteúdo concluído. resposta.saída_item.done - Item de saída concluído. resposta.concluído - Resposta concluída.	Envie texto em buffer e sintetize imediatamente. Retorna um erro se o buffer estiver vazio. Não é necessário em `server_commit` modo. Obrigatório em `commit` modo para acionar a síntese.
`def finish(self) -> None`	sessão.terminada - Sessão finalizada.	Termine a tarefa.
`def close(self) -> None`	Nenhum	Feche a conexão.
`def get_session_id(self) -> str`	Nenhum	Obtenha o ID da sessão atual.
`def get_last_response_id(self) -> str`	Nenhum	Obtenha o último ID de resposta.
`def get_first_audio_delay(self)`	Nenhum	Obtenha o atraso antes do primeiro pacote de áudio.

Interface de retorno de chamada (QwenTtsRealtimeCallback)

Lide com as respostas do servidor implementando métodos de retorno de chamada.

Importar com from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback.

Método	Parâmetros	Valor de retorno	Descrição
`def on_open(self) -> None`	Nenhum	Nenhum	Chamado quando a conexão é estabelecida.
`def on_event(self, message: str) -> None`	mensagem: Evento de resposta do servidor.	Nenhum	Chamado para respostas de API e texto/áudio gerado por modelo. Consulte Eventos do servidor.
`def on_close(self, close_status_code, close_msg) -> None`	close_status_code: código de fechamento do WebSocket. close_msg: mensagem de fechamento do WebSocket.	Nenhum	Chamado quando o servidor fecha a conexão.