Client events for the Qwen-Audio Realtime API - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Referência de eventos do cliente para a Qwen-Audio Realtime API.

Guia do usuário: Chat de áudio em tempo real (Qwen-Audio-Realtime). Para sequências de interação de eventos, consulte API WebSocket.

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 sejam válidos, o servidor aplica as alterações e retorna a configuração completa.

Observaçãoturn_detection só pode ser modificado antes do envio do primeiro áudio (estado IDLE).

typestring(obrigatório)

Tipo de evento. Valor fixo: session.update.

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Function Calling:

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get weather for a specified city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "title": "City"
                            }
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Registro de voiceprint (voiceprint_audio_urls):

{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

sessionobject (opcional)

Configuração da sessão.

Propriedades

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. Padrão: longanqian. Dois tipos são suportados. Defina apenas no primeiro session.update; chamadas subsequentes ignoram este campo.

Vozes do sistema: Valores disponíveis: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
Vozes clonadas: criadas via Voice Cloning API. Passe o voice_id retornado como valor deste parâmetro. Para mais detalhes, consulte Configuração de voz.

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

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.

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.

Propriedades

typestring(obrigatório)

Valor fixo: function.

function.namestring(obrigatório)

Nome da função da ferramenta.

function.descriptionstring (opcional)

Descrição da função da ferramenta. O modelo usa esta informação para determinar se deve chamar a ferramenta.

function.parametersobject (opcional)

Descrição dos parâmetros de entrada da função da ferramenta. O modelo utiliza isso para extrair os parâmetros necessários. Omita este campo se a função não aceitar parâmetros.

Propriedades

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)

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, confirme o áudio manualmente e acione a inferência manualmente. Se este campo não for fornecido, o VAD será ativado com seus parâmetros padrão.

Propriedades

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

thresholdfloat (opcional)

Sensibilidade do VAD. Efetivo apenas no modo server_vad (ignorado no modo smart_turn). 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 no modo smart_turn). 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 no modo smart_turn. 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 foca 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.

ImportanteConfigure este parâmetro apenas no primeiro evento session.update. Ele é ignorado em eventos session.update subsequentes.

input_audio_buffer.append

Descrição: Adiciona dados de áudio ao buffer de entrada. Envie este evento continuamente em alta frequência — por exemplo, um bloco a cada 20–40 ms. O servidor não envia confirmação para este evento.

typestring(obrigatório)

Tipo de evento. Valor fixo: input_audio_buffer.append.

{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

audiostring(obrigatório)

Dados de áudio codificados em Base64.

input_audio_buffer.commit

Descrição: Apenas modo push-to-talk. Confirma o áudio armazenado no 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 e smart_turn.

typestring(obrigatório)

Tipo de evento. Valor fixo: input_audio_buffer.commit.

{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Descrição: Apenas modo push-to-talk. Limpa o áudio não confirmado do buffer. Este evento é ignorado nos modos server_vad e smart_turn. 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.

ObservaçãoSe item.id já existir na conversa, o servidor retorna um erro e não cria o item.

typestring(obrigatório)

Tipo de evento. Valor fixo: conversation.item.create.

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"
            }
        ]
    }
}

Retornar um resultado de Function Calling:

{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"sunny\"}"
    }
}

previous_item_idstring (opcional)

Especifica o item de conversa após o qual inserir o novo item. Se não fornecido, o item será anexado ao final da conversa.

itemobject(obrigatório)

O item de conversa a ser criado.

Propriedades

idstring (opcional)

Identificador exclusivo para o item de conversa. Se não fornecido, o servidor gera um automaticamente. O servidor retorna um erro se o ID especificado já existir na conversa.

typestring(obrigatório)

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

Tipos de conteúdo suportados por função

system

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

assistant

output_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 para a 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.

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.

{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

item_idstring(obrigatório)

ID do item de conversa a recuperar. O servidor retorna o resultado em um evento 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)

Tipo de evento. Valor fixo: conversation.item.delete.

{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

item_idstring(obrigatório)

ID do item de conversa a excluir.

response.create

Descrição: Aciona a inferência do modelo. O comportamento varia conforme o modo:

Modo push-to-talk: Chame manualmente. Confirme o áudio no buffer com input_audio_buffer.commit primeiro, ou retorne um resultado function_call_output antes de acionar. Não chame 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 chame enquanto uma resposta estiver sendo gerada.
Modo smart_turn: Pode ser chamado enquanto se aguarda o próximo turno do usuário. Não chame 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.

ObservaçãoNos modos server_vad e smart_turn, inferências acionadas manualmente ainda podem ser interrompidas por nova fala.

typestring(obrigatório)

Tipo de evento. Valor fixo: response.create.

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

responseobject (opcional)

Substitui os padrões da sessão para a rodada de inferência atual. Se não fornecido, a configuração atual da sessão será usada.

Propriedades

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.

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.

O servidor retorna um erro se nenhuma inferência estiver em andamento.

typestring(obrigatório)

Tipo de evento. Valor fixo: response.cancel.

{
    "type": "response.cancel"
}