Referência de eventos do cliente para a API Qwen-Audio-Realtime.
Guia do usuário: Conversa por voz em tempo real (Qwen-Audio-Realtime). Para a sequência de interação dos eventos, consulte Acesso por WebSocket.
Para usar os SDKs de WebSocket, consulte SDK para Android, SDK para iOS e SDK para HarmonyOS. Para selecionar um modelo e um protocolo, consulte Visão geral.
Descrição: Após estabelecer a conexão, envie este evento para atualizar a configuração padrão da sessão. Inclua apenas os campos que deseja alterar; os campos omitidos mantêm seus valores atuais. Se algum parâmetro for inválido, o servidor retorna um erro. Caso todos os parâmetros sejam válidos, o servidor aplica as alterações e retorna a configuração completa.
Tipo de evento. Valor fixo: Configuração da sessão.
Modalidades de saída do modelo. Valores válidos:Nome da voz TTS. O padrão é Controla a velocidade de fala da saída de áudio do modelo. Intervalo: Especifica se o aprimoramento de emoção da fala deve ser ativado. Quando ativado, a voz da resposta apresenta variações emocionais mais pronunciadas. Padrão: Instruções do sistema que definem a função do modelo, o estilo de resposta e as preferências comportamentais. Aplica-se a toda a sessão.Formato de áudio de entrada. Atualmente, apenas Formato de áudio de saída. Atualmente, apenas Configuração da transcrição do áudio de entrada.
O idioma de origem do áudio de entrada. Aplica-se a Configuração de palavras-chave instantâneas para a transcrição do áudio de entrada. Aplica-se a
Um objeto que mapeia palavras-chave para pesos inteiros. Palavras-chave comuns recebem pesos de 1 a 5. Quanto maior o peso, maior a probabilidade de a transcrição usar a palavra. Um peso de 50 marca uma super palavra-chave. Você pode incluir até 50 super palavras-chave e até 2.000 palavras-chave no total por atualização.O envio de outro objeto Configuração do áudio de saída. Aplica-se a
O idioma de destino do áudio de saída.Este parâmetro aplica-se à síntese de voz (TTS). O modelo faz o possível para gerar a fala no idioma de destino, mas isso não é garantido, e o idioma do texto da resposta não é alterado. Para gerar texto no idioma de destino, declare o requisito explicitamente no prompt, por exemplo especificando o idioma da resposta em Número máximo de turnos de conversa (pares pergunta-resposta) incluídos em uma única solicitação. Valores válidos: 1 a 50. Padrão: 20.Aplica-se aos modelos qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.Especifica se a pesquisa na web deve ser ativada. Padrão: A configuração da pesquisa na web. Este parâmetro só tem efeito quando
Especifica se as fontes dos resultados da pesquisa devem ser retornadas. Defina este parâmetro como Definições de ferramentas para Function Calling. Após a configuração, o modelo decide se deve chamar uma ferramenta com base na entrada do usuário.
Valor fixo:
Nome da função da ferramenta.Descrição da função da ferramenta. O modelo usa esta informação para determinar se deve chamar a ferramenta.Descrição dos parâmetros de entrada da função da ferramenta. O modelo usa isso para extrair os parâmetros necessários. Omita este campo se a função não aceitar parâmetros.
Valor fixo: Descreve o nome, o tipo de dados e a descrição de cada parâmetro.Especifica quais parâmetros são obrigatórios.Os campos de detecção de turno descritos abaixo aplicam-se a
Tipo de VAD. Valores válidos:Sensibilidade do VAD. Aplica-se a Duração mínima do silêncio (em milissegundos) após o término da fala antes de acionar uma resposta do modelo. Efetivo apenas no modo server_vad (ignorado nos modos smart_turn / smart_turn_v2). Valores menores produzem respostas mais rápidas, mas podem causar acionamentos falsos durante pausas breves.Intervalo: [200, 6000]. Padrão: 800. Intervalo recomendado para conversas: 400-800.Efetivo apenas nos modos smart_turn / smart_turn_v2. Uma lista de URLs publicamente acessíveis que apontam para amostras de áudio pré-gravadas do usuário-alvo, usadas para aprimoramento do falante. Após o registro, o modelo fixa no falante-alvo durante conversas duplex, ignorando efetivamente outras vozes e ruídos de fundo. Máximo de 5 URLs. Requisitos de formato de áudio: PCM ou WAV de 16 kHz.
Descrição: No acesso por WebSocket, adiciona dados de áudio ao buffer de entrada. Envie os dados continuamente em intervalos curtos, como um quadro a cada 20~40 ms. O servidor não confirma o recebimento deste evento.
Tipo de evento. Valor fixo: Dados de áudio codificados em Base64.
Descrição: Apenas modo push-to-talk. Confirma o áudio armazenado em buffer como uma mensagem do usuário. Isso não aciona a inferência automaticamente. Envie Tipo de evento. Valor fixo:
Descrição: No acesso por WebSocket, este evento só tem efeito no modo push-to-talk. Ele limpa do buffer o áudio ainda não confirmado. Este evento é ignorado nos modos server_vad / smart_turn / smart_turn_v2. O servidor responde com um evento Tipo de evento. Valor fixo:
Descrição: Insere um item de conversa no contexto da conversa. Use este evento para injetar contexto histórico, adicionar conteúdo de texto ou retornar resultados de Function Calling.
Tipo de evento. Valor fixo: Especifica o item de conversa após o qual o novo item será inserido. Se não for fornecido, o item será anexado ao final da conversa.O item de conversa a ser criado.
Identificador exclusivo do item de conversa. Se não for fornecido, o servidor gera um automaticamente. Um erro é retornado se o ID especificado já existir na conversa.Tipo do item de conversa. Valores válidos:Função da mensagem. Valores válidos: Lista de elementos de conteúdo da mensagem. Cada elemento contém um campo
Identificador exclusivo da chamada de função, usado para correlacionar solicitações e resultados.Nome da função a ser chamada.Parâmetros da chamada de função no formato de string JSON.Resultado da execução da ferramenta no formato de string JSON.
Descrição: Recupera um item de conversa armazenado no servidor. O conteúdo do tipo áudio na resposta contém apenas a transcrição (Tipo de evento. Valor fixo: ID do item de conversa a recuperar. O servidor retorna o resultado em um evento
Descrição: Exclui um item de conversa do contexto da conversa. O servidor confirma a exclusão com um evento Tipo de evento. Valor fixo: ID do item de conversa a excluir.
Descrição: Aciona a inferência do modelo. O comportamento varia conforme o modo:
Tipo de evento. Valor fixo: Substitui os padrões da sessão para a rodada de inferência atual. Se não for fornecido, a configuração atual da sessão será usada.
Substitui as modalidades de saída para a rodada atual. Os valores válidos são os mesmos de Substitui a voz TTS para a rodada atual.
Descrição: Cancela a inferência atual. Qualquer texto gerado até o momento é salvo na lista de itens. O servidor então retorna um evento Tipo de evento. Valor fixo:
Esta página é a referência de eventos do Qwen-Audio-Realtime. As definições dos eventos são baseadas no acesso por WebSocket. O AOQ e o WebRTC usam seus respectivos canais de dados para enviar e receber eventos do modelo, e trilhas de mídia para transmitir mídia. Primeiro, leia Acesso por WebSocket, Acesso por WebRTC ou Acesso por AOQ.
session.update
Descrição: Após estabelecer a conexão, envie este evento para atualizar a configuração padrão da sessão. Inclua apenas os campos que deseja alterar; os campos omitidos mantêm seus valores atuais. Se algum parâmetro for inválido, o servidor retorna um erro. Caso todos os parâmetros sejam válidos, o servidor aplica as alterações e retorna a configuração completa.
turn_detection só pode ser modificado antes do envio do primeiro áudio (estado IDLE).typestring(obrigatório)session.update.sessionobject(opcional)Propriedades
Propriedades
modalitiesarray(opcional)-
["text"]Apenas texto. -
["audio", "text"](padrão) Texto e áudio.
voicestring(opcional)longanqian_v3.1 para 3.1 Plus/Flash e longanqian para 3.0 Plus/Flash. Vozes do sistema e vozes clonadas são suportadas. Só pode ser definido no primeiro session.update; ignorado em chamadas subsequentes.- Vozes do sistema para 3.1 Plus/Flash: Suporta
longanqian_v3.1e a união das listas de vozes do 3.1 TTS Plus e Flash. Para a faixa completa, consulte Configuração de voz. - Vozes do sistema para 3.0 Plus/Flash: Valores disponíveis:
longanqian,longanlingxin,longanlingxi,longanxiaoxin,longanlufeng. - Vozes clonadas: Crie uma voz pela API de clonagem de voz e defina este parâmetro como o
voice_idretornado. Para mais detalhes, consulte Configuração de voz.
qwen-audio-3.1-realtime-plus ou qwen-audio-3.1-realtime-flash, defina a voz no primeiro session.update, por exemplo:speech_ratefloat(opcional)[0.5, 2.0]. Padrão: 1.0. Valores menores deixam a fala mais lenta; valores maiores a aceleram. Suportado por qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash.enable_speech_emotionboolean(opcional)true. Valores válidos: true e false.instructionsstring(opcional)input_audio_formatstring(opcional)pcm (16 kHz, 16 bits, mono) é suportado e corresponde ao padrão. Só pode ser modificado antes do envio do primeiro áudio (estado IDLE).output_audio_formatstring(opcional)pcm (24 kHz, 16 bits, mono) é suportado e corresponde ao padrão.input_audio_transcriptionobject(opcional)Propriedades
Propriedades
languagestring(opcional)qwen-audio-3.1-realtime-plus e qwen-audio-3.1-realtime-flash. As palavras-chave instantâneas também funcionam quando este campo é omitido.Valores válidos:zh: chinêsen: inglêsja: japonêsko: coreanovi: vietnamitath: tailandêsid: indonésioar: árabefr: francêsde: alemãoes: espanholpt: portuguêsru: russoit: italiano
corpusobject(opcional)qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, qwen-audio-3.1-realtime-plus e qwen-audio-3.1-realtime-flash.Propriedades
Propriedades
vocabularyobjectvocabulary na mesma sessão substitui toda a lista anterior. Envie um objeto vazio {} para limpar as palavras-chave.output_audioobject(opcional)qwen-audio-3.1-realtime-plus e qwen-audio-3.1-realtime-flash.Propriedades
Propriedades
languagestring(opcional)instructions.Valores válidos:zh: chinêsen: inglêsfr: francêsde: alemãoja: japonêsko: coreanoru: russopt: portuguêsth: tailandêsid: indonésiovi: vietnamitaes: espanholit: italianoar: árabe
max_history_turnsinteger(opcional)enable_searchboolean(opcional)false. Quando ativada, o modelo decide se deve pesquisar na web com base na consulta em tempo real.Você pode definir enable_search como true e configurar ferramentas de Function Calling por meio de tools na mesma sessão.search_optionsobject(opcional)enable_search está definido como true.Propriedades
Propriedades
enable_sourceboolean(opcional)true para retornar as fontes.toolsarray(opcional)Propriedades
Propriedades
typestring(obrigatório)function.functionobjectPropriedades
Propriedades
namestring(obrigatório)descriptionstring(opcional)parametersobject(opcional)Propriedades
Propriedades
typestring(obrigatório)object.propertiesobject(opcional)requiredarray(opcional)turn_detectionobject|null(opcional)qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus e qwen-audio-3.0-realtime-flash.Configuração de detecção de turno. Para alternar para o modo push-to-talk, defina este campo como null. No modo push-to-talk, o áudio deve ser confirmado manualmente e a inferência acionada manualmente. Se este campo não for fornecido, o VAD é ativado com seus parâmetros padrão.Propriedades
Propriedades
typestring(opcional)server_vad(padrão): Detecta o início e o fim da fala com base em características acústicas e aciona a inferência automaticamente.smart_turn: Um modo inteligente de detecção de turno que combina percepção acústica e compreensão semântica para determinar os limites do turno. Sons de preenchimento como "hum" ou "é" não acionam um novo turno nem interrompem a reprodução do modelo.smart_turn_v2(recomendado): Baseia-se nosmart_turnpara compreender melhor o contexto da conversa e a intenção de interação em cenários com vários falantes. Reduz respostas ou interrupções involuntárias causadas por observadores ou intervenções não relacionadas.
thresholdfloat(opcional)server_vad, smart_turn e smart_turn_v2. Valores menores aumentam a sensibilidade do VAD, facilitando a detecção de sons fracos (incluindo ruído de fundo) como fala. Valores maiores diminuem a sensibilidade, exigindo uma fala mais clara e alta para acionar a detecção.Intervalo: [-1.0, 1.0]. Padrão: 0.5.silence_duration_msinteger(opcional)voiceprint_audio_urlsarray(opcional)- Configuração básica
- Configuração de idiomas
- Palavras-chave instantâneas
- Function Calling
- Registro de voiceprint
Os exemplos abaixo aplicam-se a
qwen-audio-3.1-realtime-plus e qwen-audio-3.1-realtime-flash e selecionam explicitamente a voz do sistema longanqian_v3.1.input_audio_buffer.append
Descrição: No acesso por WebSocket, adiciona dados de áudio ao buffer de entrada. Envie os dados continuamente em intervalos curtos, como um quadro a cada 20~40 ms. O servidor não confirma o recebimento deste evento.
typestring(obrigatório)input_audio_buffer.append.audiostring(obrigatório)input_audio_buffer.commit
Descrição: Apenas modo push-to-talk. Confirma o áudio armazenado em buffer como uma mensagem do usuário. Isso não aciona a inferência automaticamente. Envie response.create para acionar a inferência manualmente.
Este evento é ignorado nos modos server_vad, smart_turn e smart_turn_v2.
typestring(obrigatório)input_audio_buffer.commit.input_audio_buffer.clear
Descrição: No acesso por WebSocket, este evento só tem efeito no modo push-to-talk. Ele limpa do buffer o áudio ainda não confirmado. Este evento é ignorado nos modos server_vad / smart_turn / smart_turn_v2. O servidor responde com um evento input_audio_buffer.cleared.
typestring(obrigatório)input_audio_buffer.clear.conversation.item.create
Descrição: Insere um item de conversa no contexto da conversa. Use este evento para injetar contexto histórico, adicionar conteúdo de texto ou retornar resultados de Function Calling.
Se
item.id já existir na conversa, o servidor retorna um erro e o item não é criado.typestring(obrigatório)conversation.item.create.previous_item_idstring(opcional)itemobject(obrigatório)Propriedades
Propriedades
idstring(opcional)typestring(obrigatório)message: Uma mensagem de conversa regular.function_call: Uma solicitação de chamada de função. Geralmente gerada pelo servidor, mas os clientes também podem usá-la para injetar contexto histórico.function_call_output: Resultado da execução de uma ferramenta. Após receber umfunction_call, o cliente executa a ferramenta e retorna o resultado usando este tipo.
rolestring(obrigatório para o tipo message)system, user, assistant.contentarray(obrigatório para o tipo message)type e os campos de dados correspondentes.Tipos de conteúdo suportados por função
Tipos de conteúdo suportados por função
system
input_text: Mensagem do sistema. Campo obrigatório: text.userinput_text: Entrada de texto do usuário. Campo obrigatório:text.input_audio: Entrada de áudio do usuário. Campo obrigatório:audio(codificado em Base64).
output_text: Saída de texto do assistente. Campo obrigatório: text.call_idstring(obrigatório para o tipo function_call / function_call_output)namestring(obrigatório para o tipo function_call)argumentsstring(obrigatório para o tipo function_call)outputstring(obrigatório para o tipo function_call_output)- Mensagem de texto do usuário
- Resultado de Function Calling
Injetar uma mensagem de texto do usuário:
conversation.item.retrieve
Descrição: Recupera um item de conversa armazenado no servidor. O conteúdo do tipo áudio na resposta contém apenas a transcrição (transcript), não os dados de áudio originais.
typestring(obrigatório)conversation.item.retrieve.item_idstring(obrigatório)conversation.item.retrieved.conversation.item.delete
Descrição: Exclui um item de conversa do contexto da conversa. O servidor confirma a exclusão com um evento conversation.item.deleted.
typestring(obrigatório)conversation.item.delete.item_idstring(obrigatório)response.create
Descrição: Aciona a inferência do modelo. O comportamento varia conforme o modo:
- Modo push-to-talk: Deve ser chamado manualmente. Confirme o áudio em buffer com
input_audio_buffer.commitprimeiro, ou retorne um resultadofunction_call_outputantes de acionar. Não pode ser chamado enquanto uma resposta estiver sendo gerada. - Modo server_vad: Normalmente acionado automaticamente pelo servidor. Os clientes também podem chamá-lo manualmente quando nenhuma resposta estiver sendo gerada. Não pode ser chamado enquanto uma resposta estiver sendo gerada.
- Modos smart_turn / smart_turn_v2: Pode ser chamado enquanto se aguarda o próximo turno do usuário. Não pode ser chamado durante um turno ativo (entre
input_audio_buffer.speech_startederesponse.done).
response substitui os padrões da sessão para a rodada de inferência atual. Em cenários de Function Calling, após o cliente retornar um function_call_output, este evento aciona a segunda rodada de inferência.
Nos modos server_vad, smart_turn e smart_turn_v2, inferências acionadas manualmente ainda podem ser interrompidas por nova fala.
typestring(obrigatório)response.create.responseobject(opcional)Propriedades
Propriedades
modalitiesarray(opcional)session.update modalities.voicestring(opcional)response.cancel
Descrição: Cancela a inferência atual. Qualquer texto gerado até o momento é salvo na lista de itens. O servidor então retorna um evento response.done com status=cancelled.
Um erro é retornado se nenhuma inferência estiver em andamento.
typestring(obrigatório)response.cancel.