Qwen-Omni-Realtime Acesso por WebSocket
Escopo de aplicação
Este documento se aplica ao Qwen-Omni-Realtime. O exemplo usa qwen3.8-omni-flash-realtime; as configurações de qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime estão na referência de eventos. Para os parâmetros do modelo legado qwen3-omni-flash-realtime-2025-09-15, consulte SDK para Python.
- Use a chave de API e o ID do workspace correspondentes à região e ao workspace selecionados.
- domínio de Singapura:
{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. - Armazene as chaves de API permanentes no servidor. Não as inclua em navegadores nem em aplicações móveis.
Endereços e autenticação
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtimeqwen3.8-omni-flash-realtime exige o domínio específico do workspace. Os modelos anteriores podem continuar usando os domínios originais: wss://dashscope.aliyuncs.com em Pequim e wss://dashscope-intl.aliyuncs.com em Singapura. Para mais detalhes, consulte SDK para Python.
Defina Authorization: Bearer <API_KEY> no cabeçalho da solicitação de handshake do WebSocket. Substitua o ID do workspace e o nome real do modelo. Não inclua chaves de API permanentes em navegadores nem em aplicações móveis.
O cabeçalho opcional user-agent identifica o cliente. A documentação geral de integração WebSocket também lista X-DashScope-WorkSpace (ID do workspace) e X-DashScope-DataInspection (configuração de inspeção de conformidade dos dados). Use esses cabeçalhos conforme os requisitos do modelo.
Para gerar chaves de API temporárias e consultar suas permissões, consulte Gerar uma chave de API temporária.
Os URLs de workspace a seguir usam qwen3.5-omni-plus-realtime como modelo de exemplo.
- China (Pequim)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime - Singapura
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
Substitua {WorkspaceId} pelo ID do workspace da região selecionada.
Configuração da sessão
Depois de estabelecer a conexão e receber session.created, envie session.update. Envie a entrada somente após receber a confirmação session.updated; trate os erros pelos eventos error.
Os exemplos a seguir se aplicam a qwen3.8-omni-flash-realtime. Outras versões devem usar as configurações das respectivas referências de eventos, sem misturar os níveis dos campos.
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "Tina",
"turn_detection": {
"type": "server_vad"
}
}
}
Entrada, resultados e encerramento
O áudio é enviado por input_audio_buffer.append. Os formatos de entrada, as condições de envio e os limites de entrada de imagem estão em Eventos do cliente. Processe os resultados, os estados e os erros em Eventos do servidor. O estabelecimento da conexão não significa que a solicitação da aplicação foi concluída.
A sequência dos turnos automáticos, do modo Manual, do Function Calling e do MCP está em Fluxo de interação. Após receber os resultados necessários, feche a conexão WebSocket.
Fluxo de interação
Modo VAD
Para ativar o modo VAD, defina session.turn_detection.type do evento de eventos do cliente como "server_vad". No modo VAD, o servidor executa a detecção de atividade de voz no áudio recebido e responde quando detecta fala. Esse modo é adequado para quando o cliente envia áudio continuamente ao servidor e é o modo padrão atual.
- O servidor envia o evento
input_audio_buffer.speech_startedao detectar o início da fala. - O cliente pode adicionar áudio ao buffer a qualquer momento enviando um evento
input_audio_buffer.append. - O servidor envia o evento
input_audio_buffer.speech_stoppedao detectar o fim da fala. - O servidor confirma o buffer de áudio de entrada enviando um evento
input_audio_buffer.committed. - O servidor envia um evento
conversation.item.createdcontendo o item de mensagem do usuário criado a partir do buffer de áudio.
Fluxo de chamada de ferramenta
No modo VAD, quando uma resposta gerada pelo servidor exige uma chamada de ferramenta, ocorre o seguinte fluxo de interação:
- Após detectar o fim da fala e gerar uma resposta, o servidor determina que uma chamada de ferramenta é necessária.
- O servidor envia um evento
response.function_call_arguments.deltacom dados incrementais dos argumentos da chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.donepara indicar que todos os argumentos da chamada de ferramenta foram enviados. - O cliente executa a chamada de ferramenta e obtém o resultado.
- O cliente envia um evento
conversation.item.createcontendo o resultado da chamada de ferramenta. - O cliente envia um evento
response.createpara acionar o servidor a gerar uma resposta com base no resultado da chamada de ferramenta.
Modo Manual
Para ativar o modo Manual, defina o parâmetro session.turn_detection do evento do cliente como null. Nessa configuração, o cliente solicita uma resposta do servidor enviando explicitamente os eventos input_audio_buffer.commit e response.create. Esse modo é adequado para cenários de "pressionar para falar", como o envio de mensagens de voz em aplicativos de chat.
- O cliente pode adicionar áudio ao buffer enviando um evento
input_audio_buffer.append. - O cliente confirma o buffer de áudio de entrada enviando um evento
input_audio_buffer.commit. Essa confirmação cria um novo item de mensagem do usuário na conversa. - O servidor responde enviando um evento
input_audio_buffer.committed. - O cliente envia um evento
response.createpara acionar o modelo e gerar a resposta final. - O servidor responde enviando um evento
conversation.item.created.
Fluxo de chamada de ferramenta
No modo Manual, quando uma resposta gerada pelo servidor exige uma chamada de ferramenta, ocorre o seguinte fluxo de interação:
- Após o cliente enviar um evento
response.create, o servidor gera uma resposta e detecta a necessidade de uma chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.deltacontendo dados incrementais dos argumentos da chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.donepara sinalizar que a transferência dos argumentos da chamada de ferramenta foi concluída. - O cliente executa a chamada de ferramenta e obtém o resultado.
- O cliente envia o resultado da chamada de ferramenta utilizando um evento
conversation.item.create. - O cliente envia um evento
response.createpara acionar o modelo e gerar a resposta final. - O servidor gera uma resposta baseada no resultado da chamada de ferramenta e a envia ao cliente por meio de eventos
response.audio.deltaouresponse.text.delta.
Chamadas de ferramentas MCP
O fluxo a seguir se aplica ao Qwen3.8-Omni-Flash-Realtime e pode ser usado em conjunto com o modo VAD ou Manual descrito acima.
Function Calling e MCP podem ser configurados em session.tools na mesma sessão e não podem ser ativados junto com a busca na Web (enable_search). O Model Studio não cobra taxas adicionais pelas chamadas de ferramentas MCP; a inferência do modelo continua sendo cobrada pelo preço do modelo.
Com o MCP, as ferramentas são executadas pelo servidor, enquanto no fluxo de Function Calling descrito acima as ferramentas são executadas pelo cliente; os dois diferem na forma de devolver os resultados.
Descoberta de ferramentas
Depois que o cliente configura os serviços MCP via session.update, o serviço Realtime descobre as ferramentas de forma assíncrona. O fluxo de interação é o seguinte:
Nos diagramas de sequência desta seção, opt indica execução quando uma condição é atendida; alt indica ramificações alternativas escolhidas por condição; par indica processamento paralelo.
session.updatedindica apenas que a configuração MCP foi aceita, não que as ferramentas já estão disponíveis.mcp_list_tools.in_progresspode chegar antes desession.updated.- O cliente pode continuar enviando áudio ou
response.createantes do término da descoberta de ferramentas; no entanto, apenas Responses criadas após a conclusão da descoberta podem usar as ferramentas MCP correspondentes. - Quando a descoberta de ferramentas é bem-sucedida, o servidor envia primeiro
conversation.item.createdcontendo a lista final de ferramentas e, em seguida, enviamcp_list_tools.completed. - Quando a descoberta de ferramentas falha, o servidor envia primeiro
conversation.item.createdcontendo um erro e, em seguida, enviamcp_list_tools.failed.
Chamadas MCP e continuação
Depois que o modelo seleciona uma ferramenta MCP, o serviço Realtime executa a chamada da ferramenta; quando a aprovação é necessária, o cliente responde primeiro com o resultado da aprovação. O fluxo de interação é o seguinte:
Uma aprovação rejeitada ou expirada aciona diretamente response.mcp_call.failed, sem executar a ferramenta e sem passar por response.mcp_call.in_progress. Quando a aprovação não é necessária ou é concedida, a sequência típica de eventos é a seguinte:
response.output_item.added(mcp_call)
→ response.mcp_call_arguments.delta
→ response.mcp_call_arguments.done
→ 可选:conversation.item.created(mcp_approval_request)
→ 可选:conversation.item.create(mcp_approval_response)
→ response.mcp_call.in_progress
→ response.mcp_call.completed 或 response.mcp_call.failed
→ response.output_item.done(最终 mcp_call)
→ response.done(父 Response)
O servidor envia response.done depois que todos os itens MCP da mesma Response pai atingem um estado terminal. O response.output já contém o snapshot final do mcp_call: itens bem-sucedidos ficam como completed e contêm output; itens com falha ficam como failed e contêm error.
Se for necessário que o modelo continue gerando uma resposta com base no resultado do MCP, o cliente deve enviar um único response.create, sem anexar o resultado do MCP, após receber o response.done pai.
Consulte Configuração de ferramentas MCP do cliente, Resposta de aprovação, Eventos MCP do servidor e Itens de conversa MCP.
Limites de uso
As seguintes restrições MCP padrão se aplicam a cada sessão:
| Item | Valor padrão |
|---|---|
| Servidores MCP | 8 |
| Ferramentas MCP | 128 |
| Tempo limite de descoberta de ferramentas | 30 segundos |
| Tempo limite de aprovação | 60 segundos |
| Tempo limite de execução de ferramentas | 30 segundos |
| Tamanho de uma única resposta upstream | 2 MB |
| Tamanho acumulado dos resultados das ferramentas | 8 MB |
| Número acumulado de chamadas de ferramentas | 256 |
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. Depois de estabelecer a conexão, localize o problema pelo evento error e consulte Códigos de erro. Guarde o ID do evento para facilitar a investigação. A ausência de resposta não basta para concluir que o protocolo não é compatível.