Skip to main content

Eventos do cliente do Qwen-Audio-Realtime

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.
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.
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.

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)
Tipo de evento. Valor fixo: session.update.
sessionobject(opcional)
Configuração da sessão.
modalitiesarray(opcional)
Modalidades de saída do modelo. Valores válidos:
  • ["text"] Apenas texto.
  • ["audio", "text"] (padrão) Texto e áudio.
voicestring(opcional)
Nome da voz TTS. O padrão é 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.1 e 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_id retornado. Para mais detalhes, consulte Configuração de voz.
Após conectar-se a qwen-audio-3.1-realtime-plus ou qwen-audio-3.1-realtime-flash, defina a voz no primeiro session.update, por exemplo:
{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}
speech_ratefloat(opcional)
Controla a velocidade de fala da saída de áudio do modelo. Intervalo: [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)
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: true. Valores válidos: true e false.
instructionsstring(opcional)
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.
input_audio_formatstring(opcional)
Formato de áudio de entrada. Atualmente, apenas 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)
Formato de áudio de saída. Atualmente, apenas pcm (24 kHz, 16 bits, mono) é suportado e corresponde ao padrão.
input_audio_transcriptionobject(opcional)
Configuração da transcrição do áudio de entrada.
languagestring(opcional)
O idioma de origem do áudio de entrada. Aplica-se a 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ês
  • en: inglês
  • ja: japonês
  • ko: coreano
  • vi: vietnamita
  • th: tailandês
  • id: indonésio
  • ar: árabe
  • fr: francês
  • de: alemão
  • es: espanhol
  • pt: português
  • ru: russo
  • it: italiano
corpusobject(opcional)
Configuração de palavras-chave instantâneas para a transcrição do áudio de entrada. Aplica-se a 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.
vocabularyobject
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 vocabulary na mesma sessão substitui toda a lista anterior. Envie um objeto vazio {} para limpar as palavras-chave.
output_audioobject(opcional)
Configuração do áudio de saída. Aplica-se a qwen-audio-3.1-realtime-plus e qwen-audio-3.1-realtime-flash.
languagestring(opcional)
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 instructions.Valores válidos:
  • zh: chinês
  • en: inglês
  • fr: francês
  • de: alemão
  • ja: japonês
  • ko: coreano
  • ru: russo
  • pt: português
  • th: tailandês
  • id: indonésio
  • vi: vietnamita
  • es: espanhol
  • it: italiano
  • ar: árabe
max_history_turnsinteger(opcional)
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.
enable_searchboolean(opcional)
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: 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)
A configuração da pesquisa na web. Este parâmetro só tem efeito quando enable_search está definido como true.
enable_sourceboolean(opcional)
Especifica se as fontes dos resultados da pesquisa devem ser retornadas. Defina este parâmetro como true para retornar as fontes.
toolsarray(opcional)
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.
typestring(obrigatório)
Valor fixo: function.
functionobject
namestring(obrigatório)
Nome da função da ferramenta.
descriptionstring(opcional)
Descrição da função da ferramenta. O modelo usa esta informação para determinar se deve chamar a ferramenta.
parametersobject(opcional)
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.
typestring(obrigatório)
Valor fixo: object.
propertiesobject(opcional)
Descreve o nome, o tipo de dados e a descrição de cada parâmetro.
requiredarray(opcional)
Especifica quais parâmetros são obrigatórios.
turn_detectionobject|null(opcional)
Os campos de detecção de turno descritos abaixo aplicam-se a 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.
typestring(opcional)
Tipo de VAD. Valores válidos:
  • 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 no smart_turn para 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)
Sensibilidade do VAD. Aplica-se a 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)
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.
voiceprint_audio_urlsarray(opcional)
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.
Este parâmetro só pode ser configurado no primeiro evento session.update. Ele é ignorado em eventos session.update subsequentes.
  • 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.
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian_v3.1",
        "speech_rate": 1.2,
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

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)
Tipo de evento. Valor fixo: input_audio_buffer.append.
audiostring(obrigatório)
Dados de áudio codificados em Base64.
{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

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)
Tipo de evento. Valor fixo: input_audio_buffer.commit.
{
    "type": "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)
Tipo de evento. Valor fixo: input_audio_buffer.clear.
{
    "type": "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)
Tipo de evento. Valor fixo: conversation.item.create.
previous_item_idstring(opcional)
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.
itemobject(obrigatório)
O item de conversa a ser criado.
idstring(opcional)
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.
typestring(obrigatório)
Tipo do item de conversa. Valores válidos:
  • 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 um function_call, o cliente executa a ferramenta e retorna o resultado usando este tipo.
rolestring(obrigatório para o tipo message)
Função da mensagem. Valores válidos: system, user, assistant.
contentarray(obrigatório para o tipo message)
Lista de elementos de conteúdo da mensagem. Cada elemento contém um campo type e os campos de dados correspondentes.
systeminput_text: Mensagem do sistema. Campo obrigatório: text.user
  • input_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).
assistantoutput_text: Saída de texto do assistente. Campo obrigatório: text.
call_idstring(obrigatório para o tipo function_call / function_call_output)
Identificador exclusivo da chamada de função, usado para correlacionar solicitações e resultados.
namestring(obrigatório para o tipo function_call)
Nome da função a ser chamada.
argumentsstring(obrigatório para o tipo function_call)
Parâmetros da chamada de função no formato de string JSON.
outputstring(obrigatório para o tipo function_call_output)
Resultado da execução da ferramenta no formato de string JSON.
  • Mensagem de texto do usuário
  • Resultado de Function Calling
Injetar uma mensagem de texto do usuário:
{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Please summarize our last conversation"
            }
        ]
    }
}

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)
Tipo de evento. Valor fixo: conversation.item.retrieve.
item_idstring(obrigatório)
ID do item de conversa a recuperar. O servidor retorna o resultado em um evento conversation.item.retrieved.
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

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)
Tipo de evento. Valor fixo: conversation.item.delete.
item_idstring(obrigatório)
ID do item de conversa a excluir.
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

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.commit primeiro, ou retorne um resultado function_call_output antes 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_started e response.done).
O campo opcional 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)
Tipo de evento. Valor fixo: response.create.
responseobject(opcional)
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.
modalitiesarray(opcional)
Substitui as modalidades de saída para a rodada atual. Os valores válidos são os mesmos de session.update modalities.
voicestring(opcional)
Substitui a voz TTS para a rodada atual.
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

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)
Tipo de evento. Valor fixo: response.cancel.
{
    "type": "response.cancel"
}