Qwen-Audio-Realtime Acesso por AOQ
Escopo de aplicação
Este documento se aplica ao Qwen-Audio-Realtime. As instruções de integração existentes abrangem 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. O modelo usado no exemplo é qwen-audio-3.1-realtime-plus.
- Use a chave de API e o ID do workspace correspondentes à região e ao workspace selecionados.
-
Domínio de Pequim:
{WorkspaceId}.cn-beijing.maas.aliyuncs.com; 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, solicite as permissões de acesso ao microfone exigidas pela 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.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plushttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus-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.
- Os dados de áudio são gerenciados pelo SDK do AOQ, que realiza a captura, o processamento, o envio, o recebimento e a reprodução. O chamador deve enviar e receber os dados da trilha Data conforme as definições de eventos do modelo de destino.
-
Uma conexão bem-sucedida indica que o canal de comunicação com o modelo foi estabelecido. O cliente só deve ativar o envio da mídia necessária depois que o modelo concluir a inicialização. Para o modelo
qwen-audio-3.1-realtime-plususado neste exemplo, enviesession.update, aguardesession.updatede, em seguida, 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 as 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 |
Direções de mídia deste modelo
A tabela a seguir mostra as direções de mídia deste modelo. Consulte o Escopo de aplicação para verificar os modelos abrangidos. Para outras formas de acesso, consulte Qwen-Audio-Realtime.
| Modelo ou aplicação | Enviar áudio | Receber áudio | Enviar vídeo | Receber vídeo |
|---|---|---|---|---|
| Qwen-Audio-Realtime | ative para conversas por voz; | ative quando precisar de respostas por voz; | não pode ser ativado; | 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 ou startAudioPlayer conforme a direção. A entrada e a saída personalizadas são descritas na seção de 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 |
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:
input_audio_buffer.append para reenviar o áudio. O áudio recebido é processado pelo player configurado ou pela 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-Audio-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.
- O áudio é transmitido pelas trilhas de mídia. Ao consultar a referência de eventos do modelo, siga esta página para o encapsulamento de mídia e os modos de interação disponíveis. Não aplique diretamente o método de envio de mídia do WebSocket.
Recursos avançados
| Recurso | Caso de uso | Documentação |
|---|---|---|
| controlar a transmissão de áudio | aguardar o modelo ficar pronto e pausar o envio de áudio | gerenciamento do envio de streams de mídia |
| dispositivos e processamento de áudio | codificação/decodificação, alto-falantes, mixagem de arquivos e callbacks de quadros de áudio | funções comuns de áudio |
| entrada de áudio externa | usar uma fonte de áudio do cliente | captura de áudio personalizada |
| saída de áudio externa | processado ou reproduzido pelo cliente | reprodução de áudio personalizada |
Exemplo de configuração da sessão
qwen-audio-3.1-realtime-plus. O áudio é transmitido pela trilha de mídia; não use os eventos de transmissão 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 |