Qwen-Audio-Realtime Acesso por AOQ
O AOQ transmite áudio e eventos do modelo em trilhas separadas. O SDK captura, codifica/decodifica, transmite e reproduz o áudio; 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-Audio-Realtime.
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
ObservaçãoPara 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.
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-plusexport ENDPOINT="{WorkspaceId}.cn-beijing.maas.aliyuncs.com"
curl -X POST \
"https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus" \
-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 |
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
{
"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: Propriedades endpoint Endereç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 workspaceIdHash Hash do ID do workspace. |
Exemplo de conexão do AOQ Client SDK
ObservaçãoO 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.
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)
JSONObject obj = new JSONObject(responseText);
AoqClientEngine.AoqConnectConfig cfg = new AoqClientEngine.AoqConnectConfig();
cfg.token = obj.optString("aoqTokenForClient", "");
cfg.sid = obj.optString("sid", "");
cfg.certFingerprint = obj.optString("clientRelayCertFingerprint", "");
JSONArray arr = obj.optJSONArray("clientRelayEndpoints");
if (arr != null) {
for (int i = 0; i < arr.length(); i++) {
JSONObject o = arr.optJSONObject(i);
AoqClientEngine.AoqRelayEndpoint ep = new AoqClientEngine.AoqRelayEndpoint();
// Fall back to the array index when route_index is missing
ep.routeIndex = o.has("route_index") ? o.optInt("route_index", i) : i;
ep.endpoint = o.optString("endpoint", "");
ep.port = o.optInt("port", 0);
cfg.relayEndpoints.add(ep);
}
}
JSONObject ext = obj.optJSONObject("extraInfo");
cfg.workspaceIdHash = ext != null ? ext.optString("workspaceIdHash", "") : "";
AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
AoqClientEngine.AoqTrackParam data = new AoqClientEngine.AoqTrackParam();
data.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
cfg.publishTracks.add(audio);
cfg.publishTracks.add(data);
cfg.subscribeTracks.add(audio);
cfg.subscribeTracks.add(data);
engine.connect(cfg);
const obj = JSON.parse(responseText) as Record<string, Object | undefined>;
const cfg: AoqConnectConfig = {
token: String(obj['aoqTokenForClient'] ?? ''),
sid: String(obj['sid'] ?? ''),
certFingerprint: String(obj['clientRelayCertFingerprint'] ?? ''),
// Fall back to the array index when route_index is missing
relayEndpoints: (obj['clientRelayEndpoints'] as Array<any>).map((item, index) => ({
routeIndex: Number(item['route_index'] ?? index),
endpoint: String(item['endpoint'] ?? ''),
port: Number(item['port'] ?? 0)
})),
workspaceIdHash: String((obj['extraInfo'] as any)?.['workspaceIdHash'] ?? ''),
publishTracks: [
{ trackType: AoqTrackType.AoqTrackTypeAudio },
{ trackType: AoqTrackType.AoqTrackTypeData }
],
subscribeTracks: [
{ trackType: AoqTrackType.AoqTrackTypeAudio },
{ trackType: AoqTrackType.AoqTrackTypeData }
]
};
engine.connect(cfg);
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.
Observaçã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 |
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 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 |
A trilha Data é independente da direção do áudio: publique a trilha Data para enviar eventos do modelo e assine essa trilha para receber respostas. A entrada ou saída somente de texto também requer a trilha Data.
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 |
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)
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)
O áudio é transmitido pela trilha Audio; os eventos do modelo e o texto, pela trilha Data. Não use 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:
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ção | Eventos do cliente (envio) | Eventos do servidor (recepção) |
|---|---|---|
| Qwen-Audio-Realtime | Eventos do cliente | Eventos do servidor |
Siga também estas regras:
-
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 |
Para as interfaces genéricas de vídeo do SDK do AOQ, consulte Funções comuns de vídeo (SDK genérico) e Entrada de vídeo personalizada (SDK genérico). Este modelo não oferece entrada nem saída de vídeo.
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
ObservaçãoOs exemplos a seguir se aplicam a 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.
{
"type": "session.update",
"session": {
"voice": "longanqian_v3.1"
}
}
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 | 2026-10-27 |
| |
iOS | ||||
HarmonyOS | ||||
Windows | ||||
macOS | ||||
Electron | aoq-electron-sdk-1.4.0-59463182.tgz Como alternativa, instale pelo npm:
| |||
Linux |
| |||
| 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 |
ImportanteO 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.