Skip to main content
Referência da API de conversa por voz em tempo real

Qwen-Audio client events

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.
turn_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.
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.
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.
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.
Configure 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.
Se 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.
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 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.
Nos 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.
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"
}
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
Qwen-Audio client events - Alibaba Cloud Model Studio