Eventos do cliente para a API Realtime - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Eventos do cliente para a API Qwen-Omni-Realtime.

Consulte Qwen-Omni-Realtime .

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.

{
    "event_id": "event_ToPZqeobitzUJnt3QqtWg",
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "Chelsie",
        "input_audio_format": "pcm",
        "output_audio_format": "pcm",
        "instructions": "You are an AI customer service specialist for a five-star hotel. Accurately and friendly answer customer inquiries about room types, facilities, prices, and booking policies. Always respond with a professional and helpful attitude. Do not provide unverified information or information outside the scope of hotel services.",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        },
        "enable_search": true,
        "search_options": {
            "enable_source": true
        },
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_current_weather",
                    "description": "Useful for querying the weather in a specific city.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The city or district, such as Beijing, Hangzhou, or Yuhang District."
                            }
                        },
                        "required": ["location"]
                    }
                }
            }
        ],
        "seed": 1314,
        "max_tokens": 16384,
        "repetition_penalty": 1.05,
        "presence_penalty": 0.0,
        "top_k": 50,
        "top_p": 1.0,
        "temperature": 0.9
    }
}

sessionobject(opcional)

Configuração da sessão.

Propriedades

modalitiesarray(opcional)

Modalidades de saída do modelo. Valores válidos:

["text"]

Apenas texto.
["text","audio"] (padrão)

Texto e áudio.

voicestring(opcional)

Voz usada na saída de áudio do modelo. Para ver as vozes compatíveis, consulte Voice list.

Vozes padrão:

Série Qwen3.5-Omni-Realtime: Tina
qwen3-omni-flash-realtime-2025-09-15: Cherry

input_audio_formatstring(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:

true (padrão): Respostas coloquiais.
false: Respostas formais e escritas.

Conteúdos difíceis de ler em voz alta podem não ter bom desempenho.
null: O modelo seleciona automaticamente entre o estilo coloquial e o formal.

instructionsstring(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

typestring(opcional)

Tipo de VAD. Valores válidos:

server_vad (padrão): Detecta o fim da fala com base em características acústicas.
semantic_vad: Detecta o fim da fala com base na validade semântica, filtrando backchannels e ruídos de fundo. Compatível apenas com a série Qwen3.5-Omni-Realtime.

thresholdfloat(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].

enable_searchboolean(opcional)

Aplica-se apenas à série 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_optionsobject(opcional)

Configuração de pesquisa na web. Entra em vigor apenas quando enable_search está ativado.

Propriedades

enable_sourceboolean(opcional)

Define se a lista de fontes dos resultados da pesquisa deve ser retornada. Defina como true para ativar.

toolsarray(opcional)

Lista de definições de ferramentas. Quando fornecida, o modelo decide se deve chamar uma ferramenta com base na entrada do usuário.

Propriedades

typestring (obrigatório)

O valor deve ser function.

function.namestring (obrigatório)

Nome da função da ferramenta, correspondente ao nome real da função, como get_current_weather ou get_current_time.

function.descriptionstring (opcional)

Descrição do que a ferramenta faz. O modelo usa essa informação para decidir se deve chamá-la.

function.parametersobject (opcional)

Descrição dos parâmetros de entrada da ferramenta. O modelo usa isso para extrair valores de parâmetros da entrada do usuário. Omita este campo se a ferramenta não aceitar entradas.

Propriedades

typestring (obrigatório)

O valor deve ser object.

propertiesobject (opcional)

Descreve cada parâmetro de entrada por nome, tipo de dados e descrição. A chave é o nome do parâmetro; o valor é um objeto com type e description.

requiredarray (opcional)

Lista quais parâmetros de entrada são obrigatórios.

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:

Série Qwen3.5-Omni-Realtime: 0,7
qwen3-omni-flash-realtime-2025-09-15: 0,9

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:

Série Qwen3.5-Omni-Realtime: 0,8
qwen3-omni-flash-realtime-2025-09-15: 1,0

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:

Série Qwen3.5-Omni-Realtime: 20
qwen3-omni-flash-realtime-2025-09-15: 50

max_tokensinteger(opcional)

Número máximo de tokens a serem retornados.

A configuração max_tokens não afeta o processo de geração do modelo. Se a saída gerada exceder max_tokens, a resposta será truncada.

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

Série Qwen3.5-Omni-Realtime: 1,0
qwen3-omni-flash-realtime-2025-09-15: 1,05

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:

Série Qwen3.5-Omni-Realtime: 1,5
qwen3-omni-flash-realtime-2025-09-15: 0,0

Quando usar:

Valores mais altos são adequados para tarefas criativas, como contar histórias ou brainstorming, onde a diversidade e o interesse da saída são importantes.

Valores mais baixos são ideais para conteúdo técnico ou formal, onde a consistência e a terminologia precisa são necessárias.

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 2³¹−1. Padrão: -1.

response.create

O evento response.create instrui o servidor a gerar uma resposta do modelo. No modo VAD, o servidor gera respostas automaticamente, portanto, esse evento não é necessário. Em cenários de chamada de ferramenta, envie este evento após retornar o resultado da ferramenta via conversation.item.create para acionar a resposta final do modelo.

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.

{
    "type": "response.create",
    "event_id": "event_1718624400000"
}

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.

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "response.cancel"
}

input_audio_buffer.append

Adiciona bytes de áudio ao buffer de áudio de entrada.

typestring(obrigatório)

Tipo de evento. O valor deve ser input_audio_buffer.append.

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_audio_buffer.append",
    "audio": "UklGR..."
}

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.

Confirmar o buffer não aciona uma resposta do modelo. O servidor responde com um evento 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.

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "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.

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.clear"
}

input_image_buffer.append

Adiciona dados de imagem ao buffer de imagem. As imagens podem vir de arquivos locais ou de um fluxo de vídeo ao vivo.

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.append antes de enviar um evento input_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.

{
    "event_id": "event_xxx",
    "type": "input_image_buffer.append",
    "image": "xxx"
}

imagestring(obrigatório)

Dados da imagem codificados em Base64.

conversation.item.create

Envie este evento para retornar o resultado da execução de uma função de ferramenta ao servidor. Depois que o modelo acionar uma chamada de ferramenta, execute a ferramenta localmente e envie o resultado de volta usando este evento. Em seguida, envie um evento response.create para acionar a resposta final do modelo.

ObservaçãoAtualmente, há suporte apenas para itens do tipo function_call_output.

typestring(obrigatório)

Tipo de evento. O valor deve ser conversation.item.create.

{
    "event_id": "event_55099cddb51b4f208cb95d1a994eef80",
    "type": "conversation.item.create",
    "item": {
        "id": "item_2a80d7682b4e473c9c2154da135041e9",
        "type": "function_call_output",
        "call_id": "call_62c24725afdb4c2680ac54",
        "output": "The weather in Beijing today is changing from haze to clear, with a temperature of 4/-4°C and a light breeze."
    }
}

itemobject(obrigatório)

Item de conversa a ser criado. Não pode estar vazio.

Propriedades

idstring (opcional)

ID do item de conversa. Especifique um para alinhar com o estado local; caso contrário, o servidor gerará um.

typestring (obrigatório)

Tipo de item de conversa. Atualmente, há suporte apenas para function_call_output.

call_idstring (obrigatório)

O call_id retornado no evento response.function_call_arguments.done.

outputstring (obrigatório)

Resultado da execução da função da ferramenta.