Skip to main content

Qwen-Audio-Realtime Acesso por WebSocket

Qwen-Audio-Realtime Acesso por WebSocket

Guia do usuário: Conversa por voz em tempo real (Qwen-Audio-Realtime). Para as definições detalhadas dos eventos, consulte Eventos do cliente e Eventos do servidor. Modelos compatíveis: 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.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo ID do workspace. Os domínios existentes continuam disponíveis.

Endpoint

Utilize a seguinte URL WebSocket. O parâmetro de consulta model especifica o modelo. Substitua <model_name> pelo nome do modelo desejado:
  • China (Pequim)
  • Singapura
WebSocketwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Ao chamar a API, substitua {WorkspaceId} pelo ID do workspace.

A URL deve usar wss://. Defina Authorization nos cabeçalhos da solicitação e informe o modelo pelo parâmetro de consulta model.

Cabeçalhos da solicitação

Inclua as seguintes informações nos cabeçalhos da 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.

user-agent

string

Não

Identificador do cliente usado para rastrear a origem da solicitação.

X-DashScope-WorkSpace

string

Não

ID do workspace do Alibaba Cloud Model Studio.

Authorization é validado durante o handshake do WebSocket. Se a chave de API estiver ausente ou for inválida, o handshake falhará com HTTP 401/403. Armazene chaves permanentes no servidor, e não em navegadores ou aplicações móveis. Para gerar chaves temporárias e consultar suas permissões, consulte Gerar uma chave de API temporária.
A referência geral do WebSocket também lista o cabeçalho X-DashScope-DataInspection para inspeção de dados. Use-o conforme os requisitos do modelo. O exemplo de qwen-audio-3.1-realtime-plus usa x-dashscope-dataInspection: disable.

Conceitos fundamentais

  • Sessão: Uma conexão WebSocket corresponde a uma sessão, que mantém a configuração e o contexto da conversa.
  • Item da conversa: Cada mensagem da conversa, organizada como uma lista encadeada.
  • Resposta: Saída de uma inferência do modelo. Uma resposta contém um ou mais itens de saída, que podem ser mensagens do assistente ou chamadas de função.
  • Chamada de função: Uma solicitação do modelo para o cliente executar uma ferramenta. Após executar a função, o cliente envia o resultado como function_call_output, depois envia response.create para acionar a próxima inferência.
  • Detecção de turnos: Controla quando a inferência é acionada.

Modos de interação

A Realtime API do Qwen-Audio oferece três modos de interação, configurados por session.turn_detection no evento session.update. Para detecção automática, defina type dentro do objeto. Para push-to-talk, defina todo o campo turn_detection como null:

Modo

Valor de session.turn_detection

Descrição

Casos de uso

server_vad

Objeto. Defina type como server_vad.

O servidor usa VAD para detectar o início e o fim da fala e acionar a inferência automaticamente.

Conversa sem usar as mãos e assistentes de voz

Detecção semântica inteligente de turnos

Objeto. Defina type como smart_turn ou smart_turn_v2 (recomendado).

Combina percepção acústica e compreensão semântica para detectar os limites dos turnos, em vez de depender apenas de sinais de voz. Sons sem significado semântico, como "uh" e "ah", não acionam um turno nem interrompem a reprodução do modelo.

Conversa natural com baixa latência e tratamento preciso de interrupções

push-to-talk

null

O cliente confirma o áudio e aciona a inferência manualmente.

Push-to-talk e controle preciso

Fluxo de interação

Para as definições detalhadas dos eventos, consulte Eventos do cliente e Eventos do servidor.

Modo server_vad

O servidor detecta a atividade de voz no áudio recebido e aciona a inferência automaticamente ao detectar o fim da fala. Ativar este modo: Defina turn_detection.type como server_vad nos session.update event.
  • Um turno completo de conversa
  • Interrupção pelo usuário
O diagrama a seguir mostra uma sequência típica de interação no modo server_vad:
111
O cliente e o servidor interagem na seguinte ordem:
  1. O cliente estabelece uma conexão WebSocket. O servidor retorna session.created.
  2. O cliente envia session.update para configurar a sessão. O servidor retorna session.updated.
  3. O cliente envia continuamente input_audio_buffer.append para adicionar dados de áudio.
  4. Ao detectar o início da fala, o servidor retorna input_audio_buffer.speech_started e transmite as transcrições ASR incrementais em conversation.item.input_audio_transcription.delta.
  5. Ao detectar o fim da fala, o servidor retorna input_audio_buffer.speech_stopped, input_audio_buffer.committed e conversation.item.created.
  6. O servidor gera uma resposta automaticamente, transmite incrementos de texto e áudio (response.audio_transcript.delta e response.audio.delta) e retorna response.done.

Modo smart_turn / smart_turn_v2

Este modo combina percepção acústica e compreensão semântica para detectar o fim da fala. Ele pode filtrar sons sem significado, como confirmações breves e áudio de fundo. Sons sem significado semântico são repassados nos eventos conversation.item.ambient_audio_transcription.delta e não acionam um turno de conversa. Ativar este modo: Defina turn_detection.type como smart_turn ou smart_turn_v2 nos session.update event. smart_turn_v2 (recomendado): amplia o smart_turn com maior compreensão do contexto da conversa para identificar melhor a intenção de interação em cenários com várias pessoas. Reduz respostas e interrupções indesejadas causadas por outras pessoas ou comentários não relacionados.
  • Um turno completo de conversa
  • Interrupção pelo usuário
  • Turno inválido
O diagrama a seguir mostra uma sequência típica de interação no modo smart_turn / smart_turn_v2:
111
As principais diferenças em relação ao modo server_vad são:
  • Sons sem significado semântico, como "uh" e "ah", não acionam a inferência. Eles são retornados pelos eventos ambient_audio_transcription.
  • Uma fala identificada anteriormente como válida pode ser invalidada: 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.

Fluxo de configuração do aprimoramento de falante

No modo smart_turn / smart_turn_v2, se o primeiro session.update incluir voiceprint_audio_urls, o servidor registrará as impressões vocais de forma assíncrona, carregando as características de áudio dos falantes de destino. Os eventos informam o progresso do registro. Uma falha no registro não impede a conversa normal. O registro das impressões vocais segue esta ordem:
  1. O cliente estabelece uma conexão WebSocket. O servidor retorna session.created.
  2. O cliente envia seu primeiro session.update, informando as URLs dos áudios de impressão vocal em turn_detection.voiceprint_audio_urls.
  3. O servidor inicia imediatamente o registro assíncrono das impressões vocais. Antes de retornar session.updated, envia voiceprint_audio_list.in_progress com o identificador exclusivo da tarefa de registro item_id.
  4. O servidor retorna session.updated para confirmar que a configuração da sessão entrou em vigor.
  5. Ao terminar o registro das impressões vocais, o servidor envia um evento de estado final. Seu item_id corresponde ao valor da etapa 3:
    • Registro bem-sucedido: voiceprint_audio_list.completed.
    • Falha no registro: voiceprint_audio_list.failed, com um campo reason que explica a falha, como uma URL de áudio que não pode ser baixada.
voiceprint_audio_urls só entra em vigor no primeiro session.update. O campo é ignorado nas atualizações seguintes.

Modo push-to-talk

O cliente controla manualmente quando confirmar o áudio e acionar a inferência. Este modo é adequado para interações push-to-talk. Ativar este modo: Defina turn_detection como null nos session.update event.
  • Um turno completo de conversa
  • Interrupção pelo usuário
O diagrama a seguir mostra uma sequência típica de interação no modo push-to-talk:
111
O cliente e o servidor interagem na seguinte ordem:
  1. O cliente envia continuamente input_audio_buffer.append para adicionar dados de áudio.
  2. Depois que o usuário termina de falar, o cliente envia input_audio_buffer.commit para confirmar o buffer.
  3. O cliente envia response.create para acionar a inferência manualmente.
  4. O servidor gera uma resposta e transmite texto e áudio em streaming.

Restrições de operação por modo

Operação

push-to-talk

server_vad

smart_turn / smart_turn_v2

session.update

Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados

Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados

Todos os campos podem ser alterados em IDLE; alguns têm restrições nos demais estados

input_audio_buffer.append

Permitido

Permitido

Permitido

input_audio_buffer.commit

Permitido

Ignorado

Ignorado

input_audio_buffer.clear

Permitido

Ignorado

Ignorado

response.create

Permitido após confirmar o áudio armazenado no buffer com input_audio_buffer.commit; não acione outra resposta enquanto uma estiver sendo gerada

Permitido quando nenhuma resposta está sendo gerada; não acione outra resposta durante a geração

Permitido enquanto aguarda a próxima entrada do usuário; não acione outra resposta dentro de um turno ativo, de input_audio_buffer.speech_started como 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

turn_detection e input_audio_format só podem ser alterados antes do primeiro envio de áudio, enquanto a sessão estiver em IDLE.

Tratamento de erros

Se o handshake falhar, verifique o domínio, a região, o workspace, a chave de API, o nome do modelo, seu estado de ativação e as permissões. Para descrições completas dos erros, consulte Códigos de erro.

Tipo

Comportamento

Exemplo

Erro do cliente (invalid_request_error)

A conexão permanece aberta; o erro é informado

Parâmetros inválidos, operações não permitidas no estado atual ou item_id duplicado

Erro do servidor (server_error)

A conexão é encerrada

Falha na conexão com o LLM ou no armazenamento

SDKs e referências