Qwen-Omni-Realtime Acesso por AOQ
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 a chave de API apenas no servidor. Não a inclua em aplicações para navegadores ou dispositivos móveis.
- Ao capturar áudio pelo microfone ou vídeo pela câmera, solicite as permissões necessárias conforme os requisitos da plataforma.
- Baixe o SDK da sua plataforma em Downloads do SDK.
Autenticação e credenciais de conexão
clientIp é opcional. Se for omitido, o gateway usará o endereço IP de origem da solicitação.
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime-d '{}' no corpo da solicitação por -d '{"clientIp":"<CLIENT_PUBLIC_IP>"}'.
Campos da solicitação
Configuração | Valor | Descrição |
|---|---|---|
endpoint | Selecione o domínio do endpoint para o seu caso de uso | Informe o domínio do endpoint. Para mais detalhes, consulte Selecionar região, escopo de implantação e endpoint. Se você usar Token Plan, defina |
Content-Type |
| Tipo de mídia da mensagem |
Authorization |
| Sua chave de API |
x-dashscope-rtc-transport |
| Selecionar o protocolo AOQ |
clientIp | O endereço IP público do cliente | Opcional. Se for omitido, o serviço usará o IP de origem da solicitação recebida pelo gateway. Se for informado, usará clientIp. O serviço seleciona o melhor endpoint Relay com base no IP do cliente. |
Exemplo de resposta
Campos da resposta
Field | Description |
|---|---|
sid | Identificador exclusivo da sessão. |
aoqTokenForClient | Token de conexão do cliente. Passe esse valor no campo token do SDK. |
clientRelayEndpoints | Array de endpoints Relay. Cada elemento do array no exemplo de resposta contém os campos a seguir:
Propriedades endpointEndereço do endpoint Relay.portPorta do endpoint Relay.route_indexO exemplo de iOS abaixo usa o índice do array quando esse campo não está presente. |
clientRelayCertFingerprint | Impressão digital do certificado TLS do Relay. |
sidExpiresInSecs | Tempo de expiração da sessão, em segundos. |
extraInfo | Informações adicionais.
Propriedades workspaceIdHashHash do ID do workspace. |
Exemplo de conexão do AOQ Client SDK
clientIp é opcional no corpo da requisição. Se não for especificado, o endereço IP que requisita o gateway do Model Studio será usado como IP do cliente. Quando informado, o valor de clientIp tem precedência. Configure seu AppServer para obter o endereço IP real do cliente e transmiti-lo, garantindo a seleção do melhor ponto de acesso Relay.Fluxo de trabalho

- Obtenha credenciais de conexão por meio do AppServer.
- Crie o mecanismo do SDK e registre os callbacks.
- Configure as faixas de mídia e Data e desative a transmissão de mídia de saída.
- Estabeleça a conexão AOQ e aguarde a conexão ser concluída.
- Configure o modelo conforme seu protocolo. Após a confirmação, ative a mídia de saída necessária.
- Desconecte e libere os recursos ao concluir a interação.
- O SDK AOQ gerencia captura, processamento, transmissão, recepção e reprodução de mídia. Sua aplicação deve enviar e receber mensagens Data conforme as definições de eventos do modelo de destino.
-
Uma conexão bem-sucedida indica que o canal de transporte com o modelo foi estabelecido. O cliente só deve ativar o envio da mídia necessária após a inicialização do modelo. Para o modelo
qwen3.8-omni-flash-realtimedesta página, enviesession.update, aguardesession.updatede então inicie a transmissão de mídia.
1. Obter credenciais de conexão
O cliente solicita as credenciais ao AppServer. O AppServer chama o endpoint de conexão Realtime deste modelo e inclui a chave de API e x-dashscope-rtc-transport: moq na solicitação ao gateway. Para o endpoint completo, a solicitação e a descrição dos campos, consulte Autenticação por token.
Mapeie a resposta para AoqConnectConfig:
| Resposta do gateway | Configuração do SDK |
|---|---|
aoqTokenForClient | token |
sid | sid |
clientRelayCertFingerprint | certFingerprint |
clientRelayEndpoints | relayEndpoints, converta cada ponto de acesso conforme a estrutura |
extraInfo contém workspaceIdHash | workspaceIdHash |
2. Inicializar o SDK e registrar callbacks
Crie o mecanismo e registre callbacks para estado da conexão, mensagens Data e erros. O exemplo a seguir usa Swift no iOS:
AoqEngineDelegate; mantenha o estado da conexão em onConnectionStatusChange, analise os eventos do modelo de destino em onDataMsg e trate os erros do SDK em onError. Os eventos de erro retornados pelo modelo também devem ser tratados separadamente na lógica de processamento de mensagens Data. Para as interfaces do SDK e as descrições dos erros, consulte SDKs por plataforma e Referência de recursos.
3. Configurar o SDK
Selecionar direções de mídia
As direções são relativas ao cliente. Configure apenas as modalidades de entrada e saída necessárias à aplicação. Não adicione faixas para direções não utilizadas.
| Direção | Configuração | Uso típico |
|---|---|---|
| enviar áudio | publique a trilha Audio, defina o codificador de áudio e configure a captura interna ou externa | conversa por voz |
| receber áudio | assine a trilha Audio, defina o decodificador de áudio e configure o player ou a reprodução externa | resposta por voz |
| enviar vídeo | publique a trilha Video e configure a câmera ou a entrada de vídeo externa e os parâmetros de codificação | enviar vídeo a modelos que aceitam entrada visual |
| receber vídeo | este modelo não oferece saída de vídeo | não configure assinatura de vídeo |
Direções de mídia deste modelo
A tabela abaixo lista as direções de mídia deste modelo. Consulte o Escopo de aplicação para verificar os modelos abrangidos. Outras formas de acesso estão em Qwen-Omni-Realtime.
| 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 |
Configurar parâmetros e faixas de mídia
Configure separadamente o áudio de saída e de entrada: use setAudioEncoderConfig para saída e setAudioDecoderConfig para entrada. Esses parâmetros controlam a transmissão pela rede; o gateway converte o áudio para o formato exigido pelo modelo. Configure a codificação de transporte e o formato de áudio dos eventos conforme os requisitos do SDK e do modelo de destino, respectivamente.
Inicie startAudioCapture, startAudioPlayer ou startVideoCapture conforme necessário. Para entradas e saídas personalizadas, consulte os recursos avançados abaixo.
As faixas publishTracks são enviadas pelo cliente, e as faixas subscribeTracks são recebidas pelo cliente:
| Scenario | publishTracks | subscribeTracks |
|---|---|---|
| conversa por voz | Audio, Data | Audio, Data |
| conversa por voz com entrada visual | Audio, Video, Data | Audio, Data |
4. Estabelecer a conexão
Preencha as credenciais e a configuração das trilhas em AoqConnectConfig e chame:
onConnectionStatusChange retornar .connected para prosseguir com a inicialização do modelo. O retorno da chamada a connect não significa que a conexão foi estabelecida com sucesso.
5. Trocar eventos do modelo e mídia
Enviar e analisar eventos do modelo
O cliente envia eventos pela trilha Data. O trecho abaixo usa Swift para iOS. Para outras interfaces, consulte a Referência do SDK para iOS:
onDataMsg. Este modelo identifica os tipos de evento pelo campo type. Os campos completos, parâmetros e condições de encerramento devem seguir a documentação do modelo de destino.
Ativar mídia após o modelo estar pronto
Quando o modelo, a sessão ou a tarefa atual atender às condições de prontidão, ative apenas as direções de saída configuradas. Para entrada de fala, chame:
.video somente quando houver entrada de vídeo.
Transmita áudio e vídeo pelas respectivas faixas de mídia, e eventos e texto pelas faixas Data. Por exemplo, o Omni via AOQ não exige input_audio_buffer.append nem input_image_buffer.append para reenviar a mesma mídia. Processe o áudio recebido com o player configurado ou com a lógica de reprodução externa.
6. Encerrar a interação e liberar recursos
Quando a conexão não for mais necessária, chame na aplicação as interfaces de desconexão e liberação de recursos do SDK AOQ:
Enviar e receber eventos pelo canal Data
O cliente envia e recebe eventos do modelo pela trilha Data do SDK do AOQ. Durante a conexão, é necessário publicar e assinar essa trilha. Para enviar, serialize o evento do modelo em AoqDataMsg e chame a interface de envio Data da plataforma. Ao receber, analise a mensagem no callback onDataMsg. Consulte SDKs por plataforma para obter as interfaces detalhadas.
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.
| 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.
- Antes de encerrar, conclua o envio da entrada e o recebimento dos resultados conforme a documentação de eventos deste modelo. Se precisar reproduzir todo o áudio, libere a conexão somente depois de processar o áudio pendente na fila local.
- 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.
Recursos avançados
| Recurso | Caso de uso | Documentação |
|---|---|---|
| Controlar a transmissão de áudio e vídeo separadamente | Aguardar o modelo ficar pronto, pausar a mídia de saída ou ativar vídeo conforme necessário | Gerenciamento da transmissão de mídia |
| Dispositivos e processamento de áudio | Codificação, decodificação, alto-falantes, mixagem de arquivos e callbacks de quadros de áudio | Recursos comuns de áudio |
| Entrada de áudio externa | Usar uma fonte de áudio fornecida pela aplicação | Captura de áudio personalizada |
| Saída de áudio externa | Processar ou reproduzir o áudio de saída na aplicação | Reprodução de áudio personalizada |
| Captura e entrada de vídeo | Usar uma câmera ou imagens fornecidas pela aplicação | Recursos comuns de vídeo, Entrada de vídeo personalizada |
Exemplo de configuração da sessão
qwen3.8-omni-flash-realtime. O áudio e o vídeo são transmitidos pelas trilhas de mídia e não usam os eventos de envio de mídia do WebSocket.Download do SDK do AOQ
As notas de versão a seguir descrevem os recursos genéricos do SDK do AOQ. O suporte a mídia deste modelo é detalhado em Direções de mídia deste modelo acima.
| Versão | Plataforma | Download | Data de lançamento | Notas de versão |
|---|---|---|---|---|
| v1.4.0 | Android | AoqClientSdk-release.aarlibPluginOpus.zip | 2026-10-27 |
|
| iOS | AoqClientSdk.framework.zipAoqScreenShare.framework.zipPluginOpus.framework.zip | |||
| HarmonyOS | AoqClientSdk.harlibPluginOpus.zip | |||
| Windows | AoqClientSdk-windows-x64.zip | |||
| macOS | AoqClientSdk.framework.zipPluginOpus.framework.zip | |||
| Electron | aoq-electron-sdk-1.4.0-59463182.tgzComo alternativa, instale pelo npm:npm install aoq-electron-sdk@1.4.0-59463182 | |||
| Linux | x86_64: AoqClientSdk.ziparm64: AoqClientSdk.zip | |||
| v1.3.0 | Android | 2026-09-18 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | AoqClientSdk-windows-x64.zip | |||
| macOS | ||||
| Electron | Ou instale pelo npm: npm install aoq-electron-sdk@1.3.0-58586345 | |||
| Linux | x86_64: AoqClientSdk.zip arm64: AoqClientSdk.zip | |||
| v1.2.2 | iOS | AoqClientSdk.framework.zip | 2026-09-09 |
|
| v1.2.0 | Android | 2026-08-17 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | ||||
| macOS | ||||
| Electron | Como alternativa, instale pelo npm: npm install aoq-electron-sdk@1.2.0-57407598 | |||
| Linux | x86_64: AoqClientSdk.zip arm64: AoqClientSdk.zip | |||
| v1.1.0 | Android | 2026-07-31 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Linux | AoqClientSdk.zip | |||
| v1.0.1 | Android | 2026-07-09 |
| |
| iOS | ||||
| HarmonyOS |
Referências de eventos
Tutoriais por cenário
- Usar AOQ com qwen3.8-omni-flash-realtime para chamadas em tempo real
- Criar conversas por voz com botão de falar usando qwen3.8-omni-flash-realtime pelo AOQ