Skip to main content

Qwen-Omni-Realtime Acesso por AOQ

Qwen-Omni-Realtime Acesso por AOQ

O AOQ transmite áudio/vídeo e eventos do modelo em trilhas separadas. O SDK captura, codifica/decodifica, transmite e reproduz a mídia; a aplicação envia eventos do modelo pela trilha Data e processa as respostas. Esta página usa as direções de mídia e o protocolo de eventos do Qwen-Omni-Realtime.

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

Para obter um token antecipadamente ou consultar o fluxo completo de autenticação, veja os detalhes da autenticação de conexão.
Envie a solicitação a seguir pelo AppServer. Primeiro, configure a chave de API em uma variável de ambiente. Selecione a região no URL da solicitação abaixo e informe o ID do workspace. clientIp é opcional. Se for omitido, o gateway usará o endereço IP de origem da solicitação.
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime

export ENDPOINT="{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com"
curl -X POST \
  "https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'
Para informar o IP público do cliente, substitua -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 WorkspaceId no domínio do endpoint como token-plan.

Content-Type

application/json

Tipo de mídia da mensagem

Authorization

Bearer <YOUR_API_KEY>

Sua chave de API

x-dashscope-rtc-transport

moq

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

{
    "sid": "1d06b55683db49bba67a407902f62d02:1782706970:69aecdc5...",
    "aoqTokenForClient": "ecc1a46015d5496ca4ff7a48281eb739",
    "clientRelayEndpoints": [{"endpoint": "121.199.XX.XX", "port": 8443, "route_index": 0}],
    "clientRelayCertFingerprint": "sha256/99843495...",
    "sidExpiresInSecs": 7200,
    "extraInfo": {"workspaceIdHash": "2021b6f98cea4cff"}
}

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:
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.
workspaceIdHashHash do ID do workspace.

Exemplo de conexão do AOQ Client SDK

O campo 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.
iOS (Swift)
let resp = try JSONDecoder().decode(AllocateResponse.self, from: responseData)

let config = AoqConnectConfig()
config.token = resp.aoqTokenForClient
config.sid = resp.sid
config.certFingerprint = resp.clientRelayCertFingerprint
config.relayEndpoints = resp.clientRelayEndpoints.enumerated().map { index, item in
    let ep = AoqRelayEndpoint()
    // Fall back to the array index when route_index is missing
    ep.routeIndex = item.routeIndex ?? index
    ep.endpoint = item.endpoint
    ep.port = item.port
    return ep
}
config.workspaceIdHash = resp.extraInfo?.workspaceIdHash ?? ""

let audioTrack = AoqTrackParam()
audioTrack.trackType = .audio
let dataTrack = AoqTrackParam()
dataTrack.trackType = .data
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]

engine.connect(config)

Fluxo de trabalho

AOQ Diagrama de sequência da conexão
  1. Obtenha credenciais de conexão por meio do AppServer.
  2. Crie o mecanismo do SDK e registre os callbacks.
  3. Configure as faixas de mídia e Data e desative a transmissão de mídia de saída.
  4. Estabeleça a conexão AOQ e aguarde a conexão ser concluída.
  5. Configure o modelo conforme seu protocolo. Após a confirmação, ative a mídia de saída necessária.
  6. 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-realtime desta página, envie session.update, aguarde session.updated e 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 gatewayConfiguração do SDK
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints, converta cada ponto de acesso conforme a estrutura
extraInfo contém workspaceIdHashworkspaceIdHash
Obtenha novas credenciais para cada nova conexão. A possibilidade de reutilizar uma sessão ou iniciar outra tarefa na mesma conexão depende do protocolo do modelo de destino.

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:
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
Implemente 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çãoConfiguraçãoUso típico
enviar áudiopublique a trilha Audio, defina o codificador de áudio e configure a captura interna ou externaconversa por voz
receber áudioassine a trilha Audio, defina o decodificador de áudio e configure o player ou a reprodução externaresposta por voz
enviar vídeopublique a trilha Video e configure a câmera ou a entrada de vídeo externa e os parâmetros de codificaçãoenviar vídeo a modelos que aceitam entrada visual
receber vídeoeste modelo não oferece saída de vídeonão configure assinatura de vídeo
As faixas Data são independentes dessas quatro direções: publique uma faixa Data para enviar eventos do modelo e assine para receber respostas. A entrada e a saída de texto também exigem faixas Data.

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çãoEnviar áudioReceber áudioEnviar vídeoReceber vídeo
Qwen-Omni-Realtimeative quando houver entrada de vozative quando precisar de resposta por vozative quando houver entrada visualnã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:
ScenariopublishTrackssubscribeTracks
conversa por vozAudio, DataAudio, Data
conversa por voz com entrada visualAudio, Video, DataAudio, Data
Desative a mídia de saída antes de conectar para impedir que a entrada chegue ao modelo antes de ele estar pronto:
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
Captura, publicação de faixas e permissão de envio são operações distintas. Desativar a transmissão não interrompe a captura local nem afeta os eventos Data. Ativar a transmissão não cria faixas que não foram adicionadas.

4. Estabelecer a conexão

Preencha as credenciais e a configuração das trilhas em AoqConnectConfig e chame:
engine.connect(connectConfig)
Aguarde 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:
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
Analise a resposta em 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:
engine.enableSendMediaStream(.audio, enable: true)
Ative .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:
engine.disconnect()
AoqClientEngine.destroy()
Após uma desconexão inesperada, limpe o estado de prontidão da aplicação e siga Gerenciamento do estado da conexão. Inicialize o modelo novamente após reconectar.

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çãoEventos do cliente (envio)Eventos do servidor (recepção)
Qwen-Omni-RealtimeEventos do clienteEventos do servidor
Siga também estas regras:
  • Use o campo type dos 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

RecursoCaso de usoDocumentação
Controlar a transmissão de áudio e vídeo separadamenteAguardar o modelo ficar pronto, pausar a mídia de saída ou ativar vídeo conforme necessárioGerenciamento da transmissão de mídia
Dispositivos e processamento de áudioCodificação, decodificação, alto-falantes, mixagem de arquivos e callbacks de quadros de áudioRecursos comuns de áudio
Entrada de áudio externaUsar uma fonte de áudio fornecida pela aplicaçãoCaptura de áudio personalizada
Saída de áudio externaProcessar ou reproduzir o áudio de saída na aplicaçãoReprodução de áudio personalizada
Captura e entrada de vídeoUsar uma câmera ou imagens fornecidas pela aplicaçãoRecursos comuns de vídeo, Entrada de vídeo personalizada
Os controles de transmissão afetam apenas a mídia. O cancelamento de respostas do modelo e o envio de turnos ainda exigem eventos do modelo de destino.

Exemplo de configuração da sessão

O exemplo a seguir se aplica a 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.
{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

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ãoPlataformaDownloadData de lançamentoNotas de versão
v1.4.0AndroidAoqClientSdk-release.aarlibPluginOpus.zip2026-10-27
  1. Adicionado suporte à entrada externa de vídeo H.264.
  2. Desempenho aprimorado.
  3. Corrigidos problemas de estabilidade conhecidos.
iOSAoqClientSdk.framework.zipAoqScreenShare.framework.zipPluginOpus.framework.zip
HarmonyOSAoqClientSdk.harlibPluginOpus.zip
WindowsAoqClientSdk-windows-x64.zip
macOSAoqClientSdk.framework.zipPluginOpus.framework.zip
Electronaoq-electron-sdk-1.4.0-59463182.tgzComo alternativa, instale pelo npm:npm install aoq-electron-sdk@1.4.0-59463182
Linuxx86_64: AoqClientSdk.ziparm64: AoqClientSdk.zip
v1.3.0Android2026-09-18
  1. Adicionado suporte ao compartilhamento de tela.

  2. Bitcode descontinuado.

  3. Adicionado suporte ao carregamento remoto de bibliotecas .so.

  4. Adicionado suporte à definição externa do tamanho máximo de quadros codificados.

  5. O codec padrão foi alterado para Opus.

  6. Desempenho aprimorado.

  7. Corrigidos problemas de estabilidade conhecidos.

iOS
HarmonyOS
WindowsAoqClientSdk-windows-x64.zip
macOS
Electron
Ou instale pelo npm: npm install aoq-electron-sdk@1.3.0-58586345
Linux
v1.2.2iOSAoqClientSdk.framework.zip2026-09-09
  1. Corrigido um problema no iOS que impedia a retomada da chamada após o fim de uma interrupção pelo sistema ou por uma chamada de voz de terceiros.

  2. Melhorado o cancelamento de eco no início de chamadas no iOS.

v1.2.0Android 2026-08-17
  1. Adicionado suporte ao macOS

  2. Adicionado suporte ao Windows

  3. Adicionado suporte ao Electron

  4. Adicionadas APIs Python e C++ para Linux

  5. Adicionada detecção de volume

  6. Desempenho aprimorado

  7. Corrigidos problemas de estabilidade conhecidos

iOS
HarmonyOS
Windows
macOS
Electron
Como alternativa, instale pelo npm: npm install aoq-electron-sdk@1.2.0-57407598
Linux
v1.1.0Android 2026-07-31
  1. Suporte a modelos ASR

  2. Suporte a modelos TTS

  3. Suporte ao kit de interação multimodal

  4. Adicionado suporte à plataforma Linux

  5. Desempenho aprimorado

  6. Corrigidos problemas de estabilidade conhecidos

iOS
HarmonyOS
LinuxAoqClientSdk.zip
v1.0.1Android 2026-07-09
  1. Acesso a modelos e aplicações pelo protocolo AOQ

  2. Parâmetros dos codecs de áudio e vídeo

  3. Captura e reprodução de áudio e vídeo de dispositivos

  4. Captura personalizada de áudio externo

  5. Captura personalizada de vídeo externo

  6. Codificação personalizada de vídeo externo

  7. Controle do envio de streams de mídia

iOS
HarmonyOS
O AOQ carrega o codec Opus como um plug-in de áudio. Para codificar ou decodificar com Opus, baixe o plug-in Opus e adicione-o ao projeto.

Referências de eventos

Tutoriais por cenário