Skip to main content
Referência da API de síntese de fala em tempo real (Qwen-TTS-Realtime)

Eventos do cliente

Os eventos do cliente são mensagens JSON enviadas por uma conexão WebSocket para controlar a sessão da Qwen-TTS Realtime API. Eles permitem configurar definições de voz, transmitir texto para síntese e sinalizar a conclusão do processo.

Para obter uma visão geral completa da API, consulte Síntese de fala em tempo real - Qwen .

Resumo dos eventos

Evento do cliente

Resposta do servidor

Descrição

session.update

session.updated

Define a voz, o formato de áudio, o modo de interação e outros parâmetros da sessão

input_text_buffer.append

--

Adiciona texto ao buffer de síntese

input_text_buffer.commit

input_text_buffer.committed

Confirma o texto armazenado no buffer para iniciar a síntese

input_text_buffer.clear

input_text_buffer.cleared

Descarta todo o texto presente no buffer

session.finish

--

Encerra a sessão; o servidor envia o áudio restante e fecha a conexão

session.update

Configure a sessão. Envie este evento como a primeira mensagem após estabelecer a conexão WebSocket. Caso omitido, todos os parâmetros assumirão valores padrão. O servidor confirma o recebimento com um evento session.updated.

Corpo da requisição 

{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "voice": "Cherry",
        "mode": "server_commit",
        "language_type": "Chinese",
        "response_format": "pcm",
        "sample_rate": 24000,
        "instructions": "",
        "optimize_instructions": false
    }
}

Parâmetros

Parâmetro

Tipo

Obrigatório

Descrição

event_id

string

Sim

Identificador único do evento gerado pelo cliente (recomenda-se UUID). Deve ser exclusivo dentro da sessão WebSocket.

type

string

Sim

Defina como session.update.

session

object

Não

Configuração da sessão. Consulte as subseções a seguir.

voice

Tipo: string | Obrigatório: SimA voz utilizada na síntese de fala. Para ouvir amostras, consulte Vozes suportadas.
  • Vozes do sistema: Disponíveis apenas para as séries de modelos Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime e Qwen-TTS-Realtime.
  • Vozes personalizadas:
    • Vozes criadas via Clonagem de voz (Qwen): Disponíveis exclusivamente para a série Qwen3-TTS-VC-Realtime.
    • Vozes criadas via Design de voz (Qwen): Disponíveis exclusivamente para a série Qwen3-TTS-VD-Realtime.

mode

Tipo: string | Obrigatório: Não | Padrão: server_commitModo de interação que determina quando o texto em buffer será sintetizado.

Valor

Comportamento

server_commit

O servidor decide o momento da síntese, equilibrando latência e qualidade. Recomendado para a maioria dos casos de uso.

commit

Aciona a síntese manualmente mediante o envio de input_text_buffer.commit. Oferece menor latência, mas exige que você gerencie a integridade das frases.

language_type

Tipo: string | Obrigatório: Não | Padrão: AutoIdioma do áudio sintetizado.
  • Auto -- Indicado para textos desconhecidos ou com mistura de idiomas. O modelo ajusta automaticamente a pronúncia por segmento, porém sem garantia total de precisão.
  • Para textos em um único idioma, especificar o idioma melhora significativamente a qualidade. Valores suportados:

Valor

Valor

Valor

Chinese

English

German

Italian

Portuguese

Spanish

Japanese

Korean

French

Russian

response_format

Tipo: string | Obrigatório: Não | Padrão: pcmFormato de saída do áudio.

Valor

Observações

pcm

Padrão. Único formato suportado pela série Qwen-TTS-Realtime. Consulte Modelos suportados.

wav

mp3

opus

Permite configurar a taxa de bits por meio do parâmetro bit_rate.

sample_rate

Tipo: integer | Obrigatório: Não | Padrão: 24000Taxa de amostragem da saída de áudio, em Hz.Valores suportados: 8000, 16000, 24000, 48000.
Nota: A série Qwen-TTS-Realtime suporta apenas 24000 . Consulte Modelos suportados .

speech_rate

Tipo: float | Obrigatório: Não | Padrão: 1,0 | Intervalo: 0,5--2,0Velocidade de reprodução. Valores abaixo de 1,0 tornam o áudio mais lento; valores acima de 1,0 o aceleram.
Nota: Não suportado pela série Qwen-TTS-Realtime. Consulte Modelos suportados .

volume

Tipo: integer | Obrigatório: Não | Padrão: 50 | Intervalo: 0--100Volume do áudio.
Nota: Não suportado pela série Qwen-TTS-Realtime. Consulte Modelos suportados .

pitch_rate

Tipo: float | Obrigatório: Não | Padrão: 1,0 | Intervalo: 0,5--2,0Tom do áudio sintetizado.
Nota: Não suportado pela série Qwen-TTS-Realtime. Consulte Modelos suportados .

bit_rate

Tipo: integer | Obrigatório: Não | Padrão: 128 | Intervalo: 6--510Taxa de bits do áudio em kbps. Valores mais altos resultam em melhor qualidade, mas geram arquivos maiores. Aplica-se somente quando response_format for opus.
Nota: Não suportado pela série Qwen-TTS-Realtime. Consulte Modelos suportados .

instructions

Tipo: string | Obrigatório: Não | Padrão: Nenhum | Comprimento máximo: 1600 tokensControla o estilo e a expressividade da fala sintetizada. Para mais detalhes, consulte Síntese de fala em tempo real - Qwen.Idiomas suportados: Apenas chinês e inglês.
Nota: Disponível apenas para a série Qwen3-TTS-Instruct-Flash-Realtime.

optimize_instructions

Tipo: boolean | Obrigatório: Não | Padrão: falseQuando definido como true, reescreve as instructions para aprimorar a naturalidade e a expressividade. Ative esta opção para casos de uso que exigem controle vocal refinado.Não surte efeito se instructions estiver vazio.
Nota: Disponível apenas para a série Qwen3-TTS-Instruct-Flash-Realtime.

input_text_buffer.append

Adiciona texto ao buffer de síntese.
  • No modo server_commit, o texto é anexado ao buffer do lado do servidor.
  • No modo commit, o texto é anexado ao buffer do lado do cliente.

Corpo da requisição 

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_text_buffer.append",
    "text": "Hello, I am Qwen."
}

Parâmetros

Parâmetro

Tipo

Obrigatório

Descrição

event_id

string

Sim

Identificador único do evento gerado pelo cliente (recomenda-se UUID). Deve ser exclusivo dentro da sessão WebSocket.

type

string

Sim

Defina como input_text_buffer.append.

text

string

Sim

Texto a ser sintetizado.

input_text_buffer.commit

Confirma o texto em buffer e cria um item de mensagem do usuário. O servidor responde com um evento input_text_buffer.committed. Retorna erro se o buffer estiver vazio. O comportamento varia conforme o modo:
  • Modo server_commit: Todo o texto em buffer é sintetizado imediatamente. O servidor interrompe o cache e processa todo o conteúdo de uma só vez.
  • Modo commit: Cria um item de mensagem do usuário a partir do texto em buffer.
Nota: Confirmar o buffer aciona apenas a síntese, não gerando uma resposta do modelo.

Corpo da requisição 

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_text_buffer.commit"
}

Parâmetros

Parâmetro

Tipo

Obrigatório

Descrição

event_id

string

Sim

Identificador único do evento gerado pelo cliente (recomenda-se UUID). Deve ser exclusivo dentro da sessão WebSocket.

type

string

Sim

Defina como input_text_buffer.commit.

input_text_buffer.clear

Limpa o texto do buffer. O servidor responde com um evento input_text_buffer.cleared.

Corpo da requisição 

{
    "event_id": "event_2728",
    "type": "input_text_buffer.clear"
}

Parâmetros

Parâmetro

Tipo

Obrigatório

Descrição

event_id

string

Sim

Identificador único do evento gerado pelo cliente (recomenda-se UUID). Deve ser exclusivo dentro da sessão WebSocket.

type

string

Sim

Defina como input_text_buffer.clear.

session.finish

Sinaliza que nenhum outro texto será enviado. O servidor retorna o áudio restante e encerra a conexão.

Corpo da requisição 

{
    "event_id": "event_2239",
    "type": "session.finish"
}

Parâmetros

Parâmetro

Tipo

Obrigatório

Descrição

event_id

string

Sim

Identificador único do evento gerado pelo cliente (recomenda-se UUID). Deve ser exclusivo dentro da sessão WebSocket.

type

string

Sim

Defina como session.finish.

Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais