Eventos do cliente para a API Qwen-Omni-Realtime.
Esta página é a referência de eventos do Qwen-Omni-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
Após abrir a conexão WebSocket, você pode enviar session.update para configurar a sessão. Se precisar alterar a configuração depois, envie apenas os ajustes desejados; as demais configurações manterão seus valores atuais.
O servidor valida os parâmetros enviados. Se a validação for bem-sucedida, retorna a configuração completa atualizada em session.updated. Se houver falha na validação, retorna um evento error.
typestring(obrigatório)Tipo de evento. O valor deve ser session.update. | |
sessionobject(opcional)Configuração da sessão.
Propriedades modalities array(opcional)Modalidades de saída do modelo. Valores válidos:
string(opcional)Voz usada na saída de áudio do modelo. Para ver as vozes compatíveis, consulte Voice list.Vozes padrão:
string(opcional)Formato do áudio de entrada do usuário. Atualmente, há suporte apenas para pcm. O áudio de entrada deve ser um fluxo PCM com taxa de amostragem de 16 kHz.output_audio_formatstring(opcional)Formato do áudio de saída do modelo. Atualmente, há suporte apenas para pcm. O áudio de saída é um fluxo PCM com taxa de amostragem de 24 kHz.audioobject(opcional)Configuração do áudio de entrada e de saída. Os campos omitidos mantêm os valores padrão existentes.As configurações aninhadas de formato e taxa de amostragem abaixo aplicam-se apenas a qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime.audio.inputobject(opcional)Configuração do áudio de entrada do usuário.audio.input.formatobject(opcional)Formato e taxa de amostragem do áudio de entrada. Configure esses parâmetros enquanto a sessão estiver no estado IDLE, antes de enviar o primeiro segmento de áudio. Eles não podem ser alterados após o início da entrada de áudio.audio.input.format.typestring(opcional)Formato do áudio de entrada: pcm (padrão, PCM bruto mono de 16 bits) ou wav (PCM mono de 16 bits em um contêiner WAV).audio.input.format.sample_rateinteger(opcional)Taxa de amostragem do áudio de entrada em Hz: 8000, 16000 (padrão), 24000 ou 48000.audio.outputobject(opcional)Configuração do áudio de saída do modelo.audio.output.formatobject(opcional)Formato e taxa de amostragem do áudio de saída. Configure esses parâmetros no início da sessão, antes de iniciar a interação por áudio.audio.output.format.typestring(opcional)Formato do áudio de saída: pcm (padrão, PCM bruto mono de 16 bits) ou wav (PCM mono de 16 bits em um contêiner WAV).audio.output.format.sample_rateinteger(opcional)Taxa de amostragem do áudio de saída em Hz: 8000, 16000, 24000 (padrão) ou 48000.smooth_outputboolean | null(opcional)Aplica-se apenas a qwen3-omni-flash-realtime-2025-09-15.Define se o estilo de resposta coloquial está ativado. Valores válidos:
string(opcional)Mensagem do sistema que define a função ou o objetivo do modelo. Um novo valor de instructions substitui por completo o valor anterior de instructions, em vez de acrescentar conteúdo. Para manter a função, envie sua configuração existente junto com os novos requisitos.turn_detectionobject(opcional)Configuração de detecção de atividade de voz (VAD). Na primeira configuração da sessão, omitir este campo ativa o VAD com os parâmetros padrão. Defina-o como null para desativar o VAD e permitir que o cliente acione as respostas do modelo manualmente.
Propriedades type string(opcional)Tipo de VAD. Valores válidos:
float(opcional)Sensibilidade do VAD. Um valor menor torna o VAD mais sensível, aumentando a probabilidade de detectar sons fracos como fala, incluindo ruídos de fundo. Um valor maior exige uma fala mais clara e alta para disparar a detecção.Intervalo válido: [-1,0, 1,0]. Padrão: 0,5.silence_duration_msinteger(opcional)Duração mínima de silêncio após o término da fala, em milissegundos. Quando esse limite é excedido, o modelo gera uma resposta. Um valor menor acelera as respostas, mas pode causar disparos falsos durante pausas breves.Padrão: 800. Intervalo válido: [200, 6000].idle_timeout_msinteger(opcional)Aplica-se apenas aos modelos qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime no modo server_vad.Tempo limite de ociosidade em milissegundos. Depois que o servidor termina a reprodução de áudio e o usuário permanece em silêncio além dessa duração (sem disparar speech.started), o modelo gera proativamente uma resposta para incentivar o usuário a continuar a conversa com base no contexto atual. O tempo limite começa após o término da reprodução do último áudio de resposta do modelo.Intervalo válido: [5000, 30000].boolean(opcional)Aplica-se aos modelos Qwen3.8-Omni-Flash-Realtime e Qwen3.5-Omni-Realtime.Define se a pesquisa na web está ativada. Padrão: false. Quando ativado, o modelo decide autonomamente se deve pesquisar para responder a perguntas em tempo real.tools e enable_search são incompatíveis. Não ative ambos simultaneamente.search_options object(opcional)Configuração de pesquisa na web. Entra em vigor apenas quando enable_search está ativado.
Propriedades enable_source boolean(opcional)Define se a lista de fontes dos resultados da pesquisa deve ser retornada. Defina como true para ativar.array(opcional)Lista de definições de ferramentas. O modelo decide se deve chamar uma ferramenta com base na entrada do usuário. No Qwen3.8-Omni-Flash-Realtime, Function Calling e ferramentas MCP podem ser configurados na mesma sessão. Os elementos do array são diferenciados por type; tools e enable_search não podem ser ativados ao mesmo tempo.
Function Calling (type=function) type string (obrigatório)O valor deve ser function.functionobject (obrigatório)Definição da função personalizada.
Propriedades name string (obrigatório)Nome da função da ferramenta, correspondente ao nome real da função, como get_current_weather ou get_current_time.descriptionstring (opcional)Descrição do que a função faz. O modelo a usa para decidir se deve chamar a ferramenta.parametersobject (opcional)Parâmetros de entrada da função. O modelo os usa para extrair os valores dos parâmetros. Omita este campo se a função não tiver entrada.
Propriedades type string (obrigatório)O valor deve ser object.propertiesobject (opcional)Define cada parâmetro de entrada por nome. No exemplo à direita, location é um nome de parâmetro personalizado; seus campos type e description descrevem o tipo de dados e a finalidade.requiredarray (opcional)Lista os parâmetros obrigatórios.
MCP (type=mcp) Para o fluxo de configuração e chamada MCP do Qwen3.8-Omni-Flash-Realtime, consulte Fluxo de interação.Os campos obrigatórios devem ser fornecidos quando este elemento MCP estiver presente no array. Toda inclusão ou atualização exige server_label e server_url; apenas o rótulo não permite reutilizar uma configuração existente. Atualize a configuração MCP somente quando não houver uma Response ativa. As conexões, a descoberta e as chamadas estão sujeitas a cotas e tempos limite. Consulte Limites de chamadas MCP.typestring (obrigatório)Deve ser mcp.server_labelstring (obrigatório)Rótulo único do servidor MCP na sessão. Comprimento: de 1 a 64 caracteres; apenas letras, dígitos, sublinhados e hífens.server_urlstring (obrigatório)Endpoint MCP Streamable HTTP. Deve ser um endereço HTTPS público na porta 443, com até 4096 caracteres, sem nome de usuário, senha ou fragmento. Seu domínio deve resolver para endereços públicos.authorizationstring (opcional)Valor de Authorization de saída, com até 8192 caracteres ASCII imprimíveis.headersobject (opcional)Cabeçalhos HTTP adicionais de saída, com até 16 pares de strings. Os nomes devem ter de 1 a 128 caracteres válidos para nomes de cabeçalhos HTTP padrão. Os valores devem ser ASCII imprimível e ter no máximo 8192 caracteres.Os nomes não podem começar com mcp-, proxy- ou x-forwarded-, nem ser iguais a host, authorization, connection, content-length, transfer-encoding, accept, content-type, forwarded, cookie, origin, upgrade, te ou trailer.allowed_toolsarray of strings (opcional)Filtro aplicado após a descoberta. Quando omitido, permite todas as ferramentas; um array vazio não expõe nenhuma. Cada nome deve ter de 1 a 64 caracteres, usando apenas letras, dígitos, sublinhados, pontos e hífens.require_approvalstring (opcional)Política de aprovação: always (padrão) ou never.server_url, authorization e headers são usados apenas na conexão do lado do servidor e não são retornados em session.updated. Não reconstrua configurações sensíveis a partir desse evento. | |
temperaturefloat(opcional)Temperatura de amostragem, que controla a diversidade da saída. Um valor maior produz conteúdo mais variado; um valor menor gera uma saída mais determinística.Intervalo válido: [0, 2).Como temperature e top_p controlam a diversidade, defina apenas um deles.Valores padrão:
| |
top_pfloat(opcional)Limiar de probabilidade de amostragem nuclear, que controla a diversidade da saída. Um valor maior produz conteúdo mais variado; um valor menor gera uma saída mais determinística.Intervalo válido: (0, 1,0].Como temperature e top_p controlam a diversidade, defina apenas um deles.Valores padrão:
| |
top_kinteger(opcional)Tamanho do conjunto de candidatos para amostragem. Por exemplo, um valor de 50 limita cada etapa de geração aos 50 tokens com maior pontuação. Um valor maior aumenta a aleatoriedade; um valor menor aumenta o determinismo. Defina como null ou um valor maior que 100 para desativar o top_k; nesse caso, apenas o top_p será aplicado.Valor mínimo: 0.Valores padrão:
| |
max_tokensinteger(opcional)Número máximo de tokens a serem retornados.A configuraçãoOs valores padrão e máximo correspondem ao comprimento máximo de saída do modelo. Consulte Model list.Use max_tokens para limitar o comprimento da saída em tarefas como resumo, extração de palavras-chave, controle de custos ou redução de latência. | |
repetition_penaltyfloat(opcional)Controla a repetição na saída do modelo. Um valor maior reduz a repetição; 1,0 significa nenhuma penalidade. Deve ser maior que 0.Valores padrão:
| |
presence_penalty float(opcional)Controla a repetição de conteúdo na saída do modelo.Intervalo válido: [-2,0, 2,0]. Um valor positivo reduz a repetição; um valor negativo a aumenta.Valores padrão:
| |
seedinteger(opcional)Torna a geração mais determinística. Passe o mesmo valor de seed com parâmetros inalterados para obter resultados consistentes entre execuções.Intervalo válido: 0 a 231−1. Padrão: -1. |
Exemplo de configuração de ferramentas
Substitua o endpoint, a credencial e o nome da ferramenta pelos dados do seu servidor MCP.
response.create
O evento response.create instrui o servidor a gerar uma resposta do modelo. No modo VAD, o servidor normalmente inicia as respostas a partir da atividade de fala; as continuações de ferramentas seguem o fluxo explícito abaixo. Para Function Calling, envie este evento após retornar o resultado da ferramenta por conversation.item.create para continuar a geração. Para ferramentas MCP do Qwen3.8-Omni-Flash-Realtime, o servidor executa a chamada. Se for necessária uma continuação pelo modelo, envie um único response.create após o response.done da Response que contém esta chamada MCP, sem incluir resultados MCP.
O servidor responde com um evento response.created, seguido por um ou mais eventos de item e conteúdo — como conversation.item.created e response.content_part.added — e finalmente um evento response.done.
typestring(obrigatório)Tipo de evento. O valor deve ser response.create. |
response.cancel
Envie este evento para cancelar uma resposta em andamento. Se nenhuma resposta estiver em progresso, o servidor retornará um erro.
typestring(obrigatório)Tipo de evento. O valor deve ser response.cancel. |
input_audio_buffer.append
No acesso por WebSocket, adiciona bytes de áudio ao buffer de áudio de entrada.
typestring(obrigatório)Tipo de evento. O valor deve ser input_audio_buffer.append. | |
audiostring(obrigatório)Dados de áudio codificados em Base64. |
input_audio_buffer.commit
Confirma o buffer de áudio de entrada, criando um novo item de mensagem do usuário na conversa. Se o buffer estiver vazio, o servidor retornará um erro.
- VAD mode: O cliente não precisa enviar este evento. O servidor confirma o buffer de áudio automaticamente.
- Manual mode: O cliente deve confirmar o buffer de áudio para criar um item de mensagem do usuário.
input_audio_buffer.committed.
Se o cliente enviou um evento input_image_buffer.append , o evento input_audio_buffer.commit também confirma o buffer de imagem.
typestring(obrigatório)Tipo de evento. O valor deve ser input_audio_buffer.commit. |
input_audio_buffer.clear
Limpa os bytes de áudio do buffer. O servidor responde com um evento input_audio_buffer.cleared.
typestring(obrigatório)Tipo de evento. O valor deve ser input_audio_buffer.clear. |
input_image_buffer.append
No acesso por WebSocket, adiciona dados de imagem ao buffer de imagens. As imagens podem vir de um arquivo local ou ser capturadas em tempo real de um fluxo de vídeo.
Os seguintes limites se aplicam às entradas de imagem:
- Formato: JPG ou JPEG. Resolução recomendada: 480p ou 720p; máxima: 1080p.
- Uma única imagem após a codificação Base64 não deve exceder 256 KB. Recomendamos manter o tamanho da imagem bruta abaixo de 190 KB antes da codificação.
- Os dados da imagem devem estar codificados em Base64.
- Frequência de envio recomendada: 1 imagem por segundo.
- Envie pelo menos um evento
input_audio_buffer.appendantes de enviar um eventoinput_image_buffer.append.
O buffer de imagem é confirmado junto com o buffer de áudio usando o evento input_audio_buffer.commit .
typestring(obrigatório)Tipo de evento. O valor deve ser input_image_buffer.append. | |
imagestring(obrigatório)Dados da imagem codificados em Base64. |
conversation.item.create
Envie este evento para criar um item de conversa: um resultado de Function Calling ou, para Qwen3.8-Omni-Flash-Realtime, uma resposta de aprovação MCP. Para Function Calling, execute a ferramenta localmente, retorne o resultado como function_call_output e envie response.create. O servidor executa as ferramentas MCP; use mcp_approval_response para a aprovação e siga a sequência de continuação em Resposta de aprovação.
event_idstring (opcional)ID de evento gerado pelo cliente para rastreamento.typestring(obrigatório)Tipo de evento. O valor deve ser conversation.item.create. | |
itemobject(obrigatório)Item de conversa a criar. Não pode estar vazio.
Propriedades id string (opcional)ID do item de conversa. Especifique-o para alinhá-lo ao estado local; caso contrário, o servidor gera um ID.typestring (obrigatório)Use function_call_output para um resultado de Function Calling ou mcp_approval_response para uma resposta de aprovação MCP do Qwen3.8-Omni-Flash-Realtime.call_idstring (obrigatório conforme as condições)Obrigatório apenas para function_call_output. Use o call_id retornado em response.function_call_arguments.done.outputstring (obrigatório conforme as condições)Obrigatório apenas para function_call_output. Resultado da execução da função da ferramenta.approval_request_idstring (obrigatório conforme as condições)Obrigatório apenas para mcp_approval_response. Deve corresponder exatamente ao item.id de uma solicitação mcp_approval_request ainda não processada.approveboolean (obrigatório conforme as condições)Obrigatório apenas para mcp_approval_response. true permite a execução; false rejeita a chamada, que passa ao estado failed. |
Resposta de aprovação MCP (Qwen3.8-Omni-Flash-Realtime)
Quando require_approval for always ou omitido, o servidor poderá enviar mcp_approval_request. Responda com os campos de conversation.item.create acima e item.type="mcp_approval_response". O servidor executa a ferramenta MCP. Se for necessária uma continuação pelo modelo, aguarde response.done da Response que contém esta chamada MCP e envie um único response.create sem resultados MCP.
Os IDs de solicitação de aprovação, de item e de evento retornados pelo servidor são strings opacas. Não dependa de seu comprimento, prefixo ou regra de geração.
Consulte Qwen-Omni-Realtime.