Alibaba Cloud Model Studio:Referência da API WebSocket em tempo real do Qwen-Audio

A API Qwen-Audio Realtime oferece recursos de conversa por voz em tempo real via protocolo WebSocket. Os clientes interagem com o servidor enviando e recebendo eventos JSON. A API suporta entrada de áudio, entrada de texto, detecção de atividade de voz (VAD) e saída de áudio e texto em streaming.

Guia do usuário: Realtime Audio Chat (Qwen-Audio-Realtime). Para descrições detalhadas sobre eventos do cliente e do servidor, consulte Client events e Server events.

Endpoint do service

A URL WebSocket é fixa conforme abaixo. Especifique o nome do modelo usando o parâmetro de consulta model (substitua <model_name> pelo nome real do modelo):

China (Beijing)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

Substitua {WorkspaceId} (incluindo as chaves) pelo seu workspace ID real.

Cabeçalhos da solicitação

Inclua os seguintes cabeçalhos na sua solicitação:

Parâmetro	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
user-agent	string	Não	Identificador do cliente para rastreamento de solicitações no lado do servidor.
X-DashScope-WorkSpace	string	Não	ID do workspace do Alibaba Cloud Model Studio.

Conceitos principais

• Sessão: Uma única conexão WebSocket corresponde a uma sessão, que mantém a configuração e o contexto da conversa.
• Item de conversa: Uma mensagem individual em uma conversa, mantida em sequência.
• Resposta: A saída gerada por uma única inferência do modelo, contendo um ou mais itens de saída. Um item de saída pode ser uma mensagem do assistente ou uma chamada de função.
• Chamada de função: Um item de saída produzido pelo modelo quando ele precisa que o cliente execute uma função de ferramenta. Após executar a ferramenta, o cliente envia o resultado de volta em function_call_output e aciona a próxima inferência com response.create.
• Detecção de turno: Controla quando acionar a inferência do modelo.

Modos de interação

A API Qwen-Audio Realtime suporta três modos de interação, configurados por meio do parâmetro turn_detection.type do evento session.update:

Modo	turn_detection.type	Descrição	Casos de uso
server_vad	server_vad	O VAD no lado do servidor detecta o início e o fim da fala, acionando automaticamente a inferência.	Conversa com mãos livres, assistentes de voz
smart_turn	smart_turn	Detecção inteligente de turnos que combina análise acústica e semântica para determinar os limites do turno, não apenas sinais de voz. Sons não semânticos (como "uh" e "ah") não acionam um turno nem interrompem a reprodução.	Conversa natural de baixa latência, interrupção de alta qualidade
push-to-talk	null	O cliente envia áudio manualmente e aciona a inferência.	Push-to-talk, controle preciso

Fluxo de interação

Para descrições detalhadas sobre eventos do cliente e do servidor, consulte Eventos do cliente e Eventos do servidor.

Modo server_vad

O servidor executa a detecção de atividade de voz no áudio recebido e aciona automaticamente a inferência após detectar o fim da fala.

Como ative: Defina o turn_detection.type do evento session.update como server_vad.

Complete conversation turn

O diagrama a seguir ilustra a sequência típica de interação no modo server_vad:

A interação ocorre da seguinte forma:

1. O cliente estabelece uma conexão WebSocket e o servidor retorna um evento session.created.
2. O cliente envia session.update para configure os parâmetros da sessão, e o servidor retorna session.updated.
3. O cliente envia continuamente input_audio_buffer.append para transmitir dados de áudio em streaming.
4. O servidor detecta o início da fala e retorna input_audio_buffer.speech_started. Ele também transmite deltas de transcrição ASR via conversation.item.input_audio_transcription.delta.
5. O servidor detecta o fim da fala e retorna input_audio_buffer.speech_stopped, input_audio_buffer.committed e conversation.item.created.
6. O servidor gera automaticamente uma resposta, transmitindo deltas de texto e áudio em streaming (response.audio_transcript.delta, response.audio.delta) e, finalmente, retorna response.done.

User barge-in

Se o VAD detectar que o usuário começou a falar enquanto o modelo está reproduzindo uma resposta, o servidor cancele a resposta atual (retorna response.done com status cancelled) e inicia uma nova rodada de entrada de voz e resposta. O diagrama a seguir ilustra a sequência de interação de interrupção pelo usuário:

Modo smart_turn

O modo smart_turn detecta o fim da fala combinando percepção acústica e compreensão semântica, filtrando respostas de backchannel, ruído de fundo e outros sons não semânticos. Sons não semânticos são transmitidos como eventos conversation.item.ambient_audio_transcription.delta sem acionar um turno de conversa.

Como ative: Defina o turn_detection.type do evento session.update como smart_turn.

Complete conversation turn

O diagrama a seguir ilustra a sequência típica de interação no modo smart_turn:

Principais diferenças em relação ao modo server_vad:

• Sons não semânticos ("uh", "ah", etc.) não acionam inferência. Em vez disso, são retornados por meio de eventos ambient_audio_transcription.
• Falas validadas anteriormente podem ser revogadas (input_audio_buffer.speech_stopped retorna reason=turn_invalid); nesse caso, a inferência não é acionada.
• Enquanto aguarda a próxima entrada do usuário, o cliente pode enviar explicitamente response.create para acionar a inferência.

User barge-in

O tratamento de interrupções é praticamente o mesmo do modo server_vad. O diagrama a seguir ilustra a sequência de interação de interrupção pelo usuário:

Invalid turn

Falas validadas anteriormente podem ser revogadas (input_audio_buffer.speech_stopped retorna reason=turn_invalid); nesse caso, a inferência não é acionada. O cliente deve continuar enviando áudio e aguardar a próxima fala válida. O diagrama a seguir ilustra a sequência de interação de turno inválido:

Fluxo de configuração de aprimoramento de locutor

No modo smart_turn, quando voiceprint_audio_urls é incluído no primeiro session.update, o servidor executa assincronamente o registro de voiceprint (carregando os recursos de áudio do locutor alvo) e notifica o cliente sobre o progresso do registro por meio de eventos. Uma falha no registro de voiceprint não bloqueia o fluxo normal da conversa.

A sequência de interação do registro de voiceprint é a seguinte:

1. O cliente envia session.update com URLs de áudio de voiceprint em turn_detection.voiceprint_audio_urls. O servidor retorna session.created.

2. O servidor inicia imediatamente o registro de voiceprint de forma assíncrona e envia voiceprint_audio_list.in_progress antes de retornar session.updated. Este evento carrega o item_id que identifica exclusivamente a tarefa de registro.

3. O servidor retorna session.updated para confirme que a configuração da sessão entrou em vigor.

4. Após a conclusão do registro, o servidor envia um evento terminal (o item_id corresponde ao da etapa 2):

   • Registro bem-sucedido: voiceprint_audio_list.completed.
   • Falha no registro: voiceprint_audio_list.failed, com um campo reason descrevendo a falha (por exemplo, a URL de áudio não pôde ser baixada).

Modo push-to-talk

O cliente controla manualmente o envio de áudio e o acionamento da inferência. Utilize este modo quando precisar de controle preciso sobre quando o áudio é enviado e a inferência começa.

Como ative: Defina o turn_detection do evento session.update como null.

Complete conversation turn

O diagrama a seguir ilustra a sequência típica de interação no modo push-to-talk:

A interação ocorre da seguinte forma:

1. O cliente envia continuamente input_audio_buffer.append para transmitir dados de áudio em streaming.
2. Após o usuário terminar de falar, o cliente envia input_audio_buffer.commit para confirme o buffer.
3. O cliente envia response.create para acionar manualmente a inferência.
4. O servidor gera uma resposta, transmitindo texto e áudio em streaming.

User barge-in

O cliente envia response.cancel para cancele a resposta atual, e o servidor retorna response.done (com status cancelled e motivo client_cancelled). O diagrama a seguir ilustra a sequência de interação de interrupção pelo usuário:

Restrições operacionais dos modos

Operação	push-to-talk	server_vad	smart_turn
session.update	Todos os parâmetros podem ser alterados no estado IDLE; alguns são restritos no estado não-IDLE	Todos os parâmetros podem ser alterados no estado IDLE; alguns são restritos no estado não-IDLE	Todos os parâmetros podem ser alterados no estado IDLE; alguns são restritos no estado não-IDLE
input_audio_buffer.append	Permitido	Permitido	Permitido
input_audio_buffer.commit	Permitido	Ignorado	Ignorado
input_audio_buffer.clear	Permitido	Ignorado	Ignorado
response.create	Permitido. O áudio deve ser confirmado primeiro via input_audio_buffer.commit. Não permitido durante a geração de uma resposta.	Permitido quando nenhuma resposta está sendo gerada; não permitido durante a geração de uma resposta	Permitido enquanto aguarda a próxima entrada do usuário; não permitido durante um turno ativo (de input_audio_buffer.speech_started a response.done)
response.cancel	Permitido (durante a inferência)	Permitido (durante a inferência)	Permitido (durante a inferência)
conversation.item.create/delete/retrieve	Permitido	Permitido	Permitido

Tratamento de erros

Tipo	Comportamento	Exemplos
Erro do cliente (invalid_request_error)	A conexão permanece aberta; o cliente recebe um evento de erro	Parâmetros inválidos, estado não permitido, item_id duplicado
Erro do servidor (server_error)	Conexão encerrada	Falha na conexão LLM, falha de armazenamento