Qwen-Audio-Realtime Acesso por WebSocket
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.
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
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>{WorkspaceId} pelo ID do workspace.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 |
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. |
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 enviaresponse.createpara 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 | 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 | 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 |
| 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 cliente estabelece uma conexão WebSocket. O servidor retorna
session.created. - O cliente envia
session.updatepara configurar a sessão. O servidor retornasession.updated. - O cliente envia continuamente
input_audio_buffer.appendpara adicionar dados de áudio. - Ao detectar o início da fala, o servidor retorna
input_audio_buffer.speech_startede transmite as transcrições ASR incrementais emconversation.item.input_audio_transcription.delta. - Ao detectar o fim da fala, o servidor retorna
input_audio_buffer.speech_stopped,input_audio_buffer.committedeconversation.item.created. - O servidor gera uma resposta automaticamente, transmite incrementos de texto e áudio (
response.audio_transcript.deltaeresponse.audio.delta) e retornaresponse.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
- 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_stoppedretornareason=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.createpara 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:
-
O cliente estabelece uma conexão WebSocket. O servidor retorna
session.created. -
O cliente envia seu primeiro
session.update, informando as URLs dos áudios de impressão vocal emturn_detection.voiceprint_audio_urls. -
O servidor inicia imediatamente o registro assíncrono das impressões vocais. Antes de retornar
session.updated, enviavoiceprint_audio_list.in_progresscom o identificador exclusivo da tarefa de registroitem_id. -
O servidor retorna
session.updatedpara confirmar que a configuração da sessão entrou em vigor. -
Ao terminar o registro das impressões vocais, o servidor envia um evento de estado final. Seu
item_idcorresponde ao valor da etapa 3:- Registro bem-sucedido:
voiceprint_audio_list.completed. - Falha no registro:
voiceprint_audio_list.failed, com um camporeasonque explica a falha, como uma URL de áudio que não pode ser baixada.
- Registro bem-sucedido:
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 cliente envia continuamente
input_audio_buffer.appendpara adicionar dados de áudio. - Depois que o usuário termina de falar, o cliente envia
input_audio_buffer.commitpara confirmar o buffer. - O cliente envia
response.createpara acionar a inferência manualmente. - 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 | 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 |
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 ( | 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 ( | A conexão é encerrada | Falha na conexão com o LLM ou no armazenamento |