Qwen-Omni-Realtime Acesso por WebRTC
O WebRTC transporta áudio e vídeo em faixas de mídia, e eventos do modelo e texto por DataChannels. Aplicações Web podem usar APIs nativas do navegador; outras plataformas podem usar bibliotecas WebRTC padrão. O Model Studio não fornece um SDK WebRTC dedicado.
Este documento descreve o procedimento de integração deste modelo pelo WebRTC e inclui um exemplo completo para o navegador.
Este documento se aplica ao Qwen-Omni-Realtime. A documentação de integração existente abrange qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime. O exemplo usa
O navegador envia um Offer SDP ao AppServer da aplicação. O AppServer encaminha a solicitação a seguir com a chave de API e devolve o Answer SDP ao navegador sem alterações. As chaves de API permanentes não chegam ao frontend.
O exemplo a seguir é uma implementação completa para o navegador. Primeiro, implemente a interface
O AppServer configura a troca SDP para o modelo de destino, a região e o espaço de trabalho. Os parâmetros a seguir se aplicam a conexões Realtime padrão. Para parâmetros específicos de uma aplicação, siga a prática recomendada correspondente.
Os detalhes completos de regiões, endereços e autenticação estão em Autenticação e troca de SDP. A interface do AppServer é implementada pela aplicação e não faz parte da API do SDK do Model Studio.
No cliente web, crie um
As direções são relativas ao cliente. Os transceptores WebRTC negociam envio e recepção:
Conversas por voz normalmente exigem áudio bidirecional; entrada visual exige também vídeo de saída. O Offer SDP deve incluir uma seção de mídia
Esta tabela descreve as direções de mídia necessárias à aplicação; não garante que todas as combinações possam ser negociadas independentemente. A configuração depende do modelo de destino e dos recursos de negociação do servidor.
Negocie as direções necessárias antes de criar o Offer. Para modelos que exigem confirmação de inicialização, reserve a capacidade de envio sem anexar as faixas capturadas. Quando o modelo estiver pronto, use
O exemplo a seguir mostra voz bidirecional com envio de vídeo opcional. Os três controles em
Crie um DataChannel antes de criar o Offer para que o SDP inclua a negociação do canal de dados. Consulte Enviar e receber eventos pelo canal Data para saber como cliente e servidor tratam a criação dos canais.
Os DataChannels transportam inicialização do modelo, texto e eventos de controle, e retornam resultados, estados e erros. As faixas de mídia transportam áudio e vídeo.
O exemplo completo cria o canal de eventos do cliente e registra o callback do canal do servidor antes de criar um Offer.
Estabeleça a conexão nesta ordem:
Monitore
Quando a conexão e o canal de eventos estiverem disponíveis, inicialize o modelo de destino conforme seu protocolo. Armazene os eventos de inicialização do servidor e combine-os com o estado do canal para avançar no fluxo; não presuma uma ordem fixa de chegada dos callbacks.
Por exemplo, ao configurar um modelo com
O exemplo a seguir mostra o fluxo
Quando o modelo estiver pronto, anexe as faixas de áudio e vídeo necessárias para transmissão. Trate a saída do modelo no callback da faixa remota e continue analisando os eventos DataChannel.
Quando a conexão não for mais necessária, pare as faixas locais de captura da aplicação, feche os DataChannels e o
Verifique se o canal está
Use a mesma função de associação para canais criados pelo cliente e pelo servidor. Ela trata o transporte e a análise JSON;
Siga também estas regras:
Escopo de aplicação
Este documento se aplica ao Qwen-Omni-Realtime. A documentação de integração existente abrange qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime. O exemplo usa qwen3.8-omni-flash-realtime.
- 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 aplicações para navegadores ou dispositivos móveis. Para gerar chaves de API temporárias e consultar suas permissões, consulte Gerar uma chave de API temporária.
Autenticação e troca de SDP
O navegador envia um Offer SDP ao AppServer da aplicação. O AppServer encaminha a solicitação a seguir com a chave de API e devolve o Answer SDP ao navegador sem alterações. As chaves de API permanentes não chegam ao frontend.
- Método:
POST
POST
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime- Cabeçalhos da solicitação:
Authorization: Bearer <API_KEY>,Content-Type: application/sdp - Corpo da solicitação: string do Offer SDP.
- Resposta de sucesso: HTTP 200, com o Answer SDP no corpo. Em caso de falha, retorna 4xx.
/api/realtime/sdp é uma interface personalizada implementada pelo AppServer da aplicação para fazer o encaminhamento descrito acima; essa URL não é fornecida pelo Model Studio.
Fluxo de trabalho

- Prepare a chave de API e os parâmetros do modelo de destino no AppServer.
- Crie o objeto de conexão do cliente e registre os callbacks.
- Configure as direções de mídia e os DataChannels sem anexar as faixas de mídia de saída.
- Troque SDP pelo AppServer e aguarde a conexão e o canal de eventos ficarem prontos.
- Configure o modelo conforme seu protocolo. Anexe as faixas de mídia de saída necessárias após a confirmação.
- Pare a captura, feche a conexão e libere os recursos ao concluir a interação.
- As faixas de mídia WebRTC transportam áudio e vídeo. Sua aplicação obtém as faixas locais, associa players remotos e troca mensagens DataChannel conforme as definições de eventos do modelo de destino.
- A autenticação WebRTC ocorre durante a troca SDP; não é necessário obter um token AOQ. Intermedeie autenticação e SDP pelo AppServer para manter a chave de API de longo prazo fora do código frontend.
-
Uma conexão bem-sucedida indica que o canal de transporte foi estabelecido, mas não que o modelo concluiu a inicialização. Ao usar
qwen3.8-omni-flash-realtimenesta página, enviesession.updatee ative o envio da mídia necessária somente após recebersession.updated.
Exemplo completo
O exemplo a seguir é uma implementação completa para o navegador. Primeiro, implemente a interface /api/realtime/sdp do AppServer conforme Autenticação e troca de SDP. Em seguida, abra esta página HTML na mesma origem do AppServer, com o mesmo protocolo, host e porta. Por exemplo, a página e /api/realtime/sdp podem ser servidos por http://localhost:3000. O servidor armazena a chave de API e encaminha o SDP; não inclua chaves permanentes na página. Clique em “Start” para estabelecer a conexão e em “End” para liberar os recursos ao concluir a interação. Este exemplo estabelece uma conexão por vez; recarregue a página para iniciar outra sessão.
1. Preparar autenticação e parâmetros de conexão
O AppServer configura a troca SDP para o modelo de destino, a região e o espaço de trabalho. Os parâmetros a seguir se aplicam a conexões Realtime padrão. Para parâmetros específicos de uma aplicação, siga a prática recomendada correspondente.
| Setting | Value |
|---|---|
| Método | POST |
| URL | https://{endpoint}/api/v1/webrtc/realtime?model={model_name} |
Content-Type | application/sdp |
Authorization | Bearer <API_KEY> |
| Corpo da solicitação | Offer SDP |
| Resposta bem-sucedida | Answer SDP |
2. Inicializar o objeto de conexão e registrar os callbacks
No cliente web, crie um RTCPeerConnection. Nas outras plataformas, inicialize a biblioteca correspondente. Antes de estabelecer a conexão, registre os seguintes handlers:
- Mudanças no estado da conexão: determine se a conexão teve sucesso, falhou ou foi encerrada.
- Criação, abertura, mensagens e fechamento do DataChannel: transportam os eventos do modelo.
- Trilha de mídia remota: recebe e reproduz áudio ou processa outras mídias aceitas pela aplicação de destino.
txt, portanto trate também o callback datachannel.
3. Configurar direções de mídia e DataChannels
Selecionar as direções de mídia
As direções são relativas ao cliente. Os transceptores WebRTC negociam envio e recepção: sendrecv é bidirecional, sendonly apenas envia e recvonly apenas recebe. Os recursos disponíveis também dependem da resposta SDP do servidor e do suporte do modelo.
| Direction | Configuration |
|---|---|
| Enviar áudio | Negocie a capacidade de envio de áudio e prepare o microfone ou uma trilha de áudio externa; associe-a após o modelo estar pronto. |
| Receber áudio | Negocie a capacidade de recebimento de áudio e configure a reprodução no callback da trilha remota. |
| Enviar vídeo | Quando o modelo de destino aceitar entrada visual, negocie a capacidade de envio de vídeo e prepare a câmera ou uma trilha de vídeo externa. |
m=audio. Não a remova apenas porque a aplicação não precisa reproduzir áudio.
Direções de mídia deste modelo
| Modelo ou aplicação | Enviar áudio | Receber áudio | Enviar vídeo | Receber vídeo |
|---|---|---|---|---|
| Qwen-Omni-Realtime | ative quando houver entrada de voz | ative quando precisar de resposta por voz | ative quando houver entrada visual | não pode ser ativado |
Preparar mídia sem enviá-la
Negocie as direções necessárias antes de criar o Offer. Para modelos que exigem confirmação de inicialização, reserve a capacidade de envio sem anexar as faixas capturadas. Quando o modelo estiver pronto, use replaceTrack no emissor correspondente para iniciar a transmissão. Registre previamente os manipuladores de recepção de mídia.
Configure separadamente o envio de áudio, o recebimento de áudio e o envio de vídeo conforme necessário. Não una a ativação do microfone, a reprodução de áudio e a inicialização do modelo em uma única operação.
Exemplo de configuração de mídia
O exemplo a seguir mostra voz bidirecional com envio de vídeo opcional. Os três controles em media definem, respectivamente, o envio de áudio, o recebimento de áudio e o envio de vídeo. addTransceiver negocia previamente a direção; as trilhas capturadas são mantidas localmente até o modelo estar pronto e então associadas ao sender.
Consulte o código no exemplo completo.
Defina a resolução de vídeo e a taxa de quadros conforme o modelo de destino. Se a prévia local e o fluxo de saída precisarem de taxas diferentes, consulte a implementação Canvas na prática recomendada.
Criar canais de eventos
Crie um DataChannel antes de criar o Offer para que o SDP inclua a negociação do canal de dados. Consulte Enviar e receber eventos pelo canal Data para saber como cliente e servidor tratam a criação dos canais.
Os DataChannels transportam inicialização do modelo, texto e eventos de controle, e retornam resultados, estados e erros. As faixas de mídia transportam áudio e vídeo.
O exemplo completo cria o canal de eventos do cliente e registra o callback do canal do servidor antes de criar um Offer.
4. Estabelecer a conexão
Estabeleça a conexão nesta ordem:
- Chame
createOfferesetLocalDescription. - Colete os candidatos conforme os métodos ICE aceitos pelo servidor. Neste exemplo, o SDP local é enviado após a coleta ICE terminar.
- Envie o SDP local ao AppServer da aplicação, que usa a chave de API para chamar a interface de troca de SDP do Model Studio.
- Verifique o status HTTP. Em caso de sucesso, passe o Answer SDP retornado para
setRemoteDescription. - Aguarde a conexão indicar sucesso e confirme que o DataChannel usado para enviar eventos do modelo está aberto.
setRemoteDescription conclui apenas essa etapa de negociação; não comprova que a conexão de mídia está pronta. Os eventos só podem ser enviados quando o DataChannel estiver open.
Código de conexão e callbacks de estado
Monitore connectionstatechange para verificar o estado da conexão e icegatheringstatechange para aguardar o SDP local completo. A inicialização do modelo também depende do evento open do DataChannel e do evento que indica que o modelo está pronto; não considere apenas o término da troca de SDP.
O exemplo completo realiza a troca de SDP por startSession() e trata o resultado no callback de estado da conexão.
O AppServer deve encaminhar o Offer usando o endpoint e os cabeçalhos da seção 1. A interface do exemplo retorna SDP em texto simples. Não passe cabeçalhos HTTP, logs nem um envelope JSON para setRemoteDescription.
5. Trocar eventos do modelo e mídia
Inicializar o modelo
Quando a conexão e o canal de eventos estiverem disponíveis, inicialize o modelo de destino conforme seu protocolo. Armazene os eventos de inicialização do servidor e combine-os com o estado do canal para avançar no fluxo; não presuma uma ordem fixa de chegada dos callbacks.
Por exemplo, ao configurar um modelo com session.update, construa o evento conforme seu protocolo e aguarde a confirmação da configuração antes de enviar a entrada. Parâmetros como voz, modalidades de saída, VAD e taxa de amostragem devem vir da documentação atual do modelo.
session.created indica a criação da sessão e não deve ser considerado uma confirmação de que a configuração entrou em vigor. Para modelos que exigem essa confirmação, aguarde session.updated.
As definições dos eventos do modelo estão em Eventos do cliente e Eventos do servidor. Siga as instruções desta página para a transmissão de mídia e os modos disponíveis.
O Qwen-Omni-Realtime oferece apenas o modo VAD quando acessado por WebRTC; o modo Manual não é compatível. O áudio é transmitido pela trilha de áudio sem enviar input_audio_buffer.append; o vídeo é transmitido pela trilha de vídeo sem enviar input_image_buffer.append.
Exemplos de eventos do modelo
O áudio e o vídeo são transmitidos pelas trilhas de mídia sem usar os eventos de envio de mídia do WebSocket.
session.created → session.update → session.updated de qwen3.8-omni-flash-realtime. Configure os campos conforme a referência de eventos do modelo. Associe a trilha de envio de mídia somente após receber session.updated confirmando a conclusão da configuração.
Consulte o código no exemplo completo.
Para o modelo qwen3.8-omni-flash-realtime do exemplo, quando a saída de áudio estiver ativada, use response.audio.done para verificar o estado da geração de áudio. Esse evento não indica que o cliente terminou de reproduzir o áudio.
Iniciar a transmissão e a recepção de mídia
Quando o modelo estiver pronto, anexe as faixas de áudio e vídeo necessárias para transmissão. Trate a saída do modelo no callback da faixa remota e continue analisando os eventos DataChannel.
-
O áudio é transmitido por faixas de mídia RTP; não é necessário o evento
input_audio_buffer.append. -
As imagens são transmitidas por faixas de vídeo. WebRTC não oferece suporte a
input_image_buffer.append. - Os DataChannels transportam texto e eventos de estado, controle e erro.
startSendingMedia() associa a trilha de envio, e ontrack processa a mídia recebida.
6. Encerrar a interação e liberar recursos
Quando a conexão não for mais necessária, pare as faixas locais de captura da aplicação, feche os DataChannels e o RTCPeerConnection, libere os players e limpe o estado da aplicação.
Limpe a prontidão do modelo após uma falha ou desconexão inesperada. Inicialize o modelo novamente em uma nova conexão, sem reutilizar o estado da sessão anterior.
No exemplo completo, endSession() libera a conexão e os recursos de mídia.
Chame endSession() quando o usuário encerrar a chamada ou sair da página. Se a aplicação adicionar os recursos Canvas ou de gravação da prática recomendada, cancele também os loops de animação e pare as faixas Canvas e o MediaRecorder.
Enviar e receber eventos pelo canal Data
Verifique se o canal está open antes de chamar send com um evento serializado. Analise as mensagens recebidas no callback message, incluindo as dos canais criados pelo servidor.
Siga as definições de eventos do cliente do modelo de destino para nomes, campos, parâmetros e momentos de envio. Siga as definições de eventos do servidor para analisar respostas, alterações de estado, resultados e erros. Envie os eventos de inicialização exigidos pelo modelo e, depois, eventos de texto e controle necessários à aplicação.
Exemplo de DataChannel
Use a mesma função de associação para canais criados pelo cliente e pelo servidor. Ela trata o transporte e a análise JSON; handleModelEvent na seção 5 trata a semântica do modelo. Use sendModelEvent para inicialização, texto ou controle somente quando permitido pelo protocolo do modelo.
No exemplo completo, sendModelEvent() e bindDataChannel() enviam e recebem eventos.
No exemplo completo, o botão de início chama startSession() e o botão de encerramento chama endSession(). Essas funções são definidas neste exemplo e não são APIs nativas do WebRTC.
Definições de eventos do Qwen-Omni-Realtime
| Modelo ou aplicação | Eventos do cliente (envio) | Eventos do servidor (recepção) |
|---|---|---|
| Qwen-Omni-Realtime | Eventos do cliente | Eventos do servidor |
-
Use o campo
typedos eventos para identificar os eventos do modelo. Trate os identificadores associados conforme a referência de eventos deste modelo. - Operações exigidas pelo modelo, como confirmação da inicialização, envio definitivo da entrada, cancelamento da resposta e conclusão da tarefa, são tratadas no canal Data conforme o protocolo correspondente. Essas operações definem a interação com o modelo e são distintas do encerramento da conexão de transporte.
- Os dados de áudio e vídeo são transmitidos pelas trilhas de mídia. Ao consultar a documentação de eventos do modelo, siga a forma de acesso desta página para o encapsulamento da mídia e os modos de interação disponíveis. Não aplique diretamente o método de transmissão de mídia do WebSocket.