Skip to main content

Qwen-Audio-Realtime Acesso por WebRTC

Qwen-Audio-Realtime Acesso por WebRTC

O WebRTC transmite áudio pelas trilhas de mídia e eventos do modelo e texto pelo DataChannel. O cliente web pode usar as APIs nativas do navegador; outras plataformas podem usar bibliotecas compatíveis com WebRTC padrão. O Model Studio não fornece um SDK específico para WebRTC. Este documento descreve o procedimento de integração deste modelo pelo WebRTC e inclui um exemplo completo para o navegador.

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 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.
Use um contexto seguro para capturar áudio no navegador e solicite permissão para usar o microfone. Ao receber áudio, trate as restrições de reprodução automática do navegador.

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
POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus

  • 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.
O WebRTC realiza a autenticação durante a troca de SDP e não exige um token AOQ prévio. Nos exemplos abaixo, /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

WEBRTC Diagrama de sequência da conexão
  1. Prepare a chave de API e os parâmetros do modelo de destino no AppServer.
  2. Crie o objeto de conexão do cliente e registre os callbacks.
  3. Configure as direções de mídia e os DataChannels sem anexar as faixas de mídia de saída.
  4. Troque SDP pelo AppServer e aguarde a conexão e o canal de eventos ficarem prontos.
  5. Configure o modelo conforme seu protocolo. Anexe as faixas de mídia de saída necessárias após a confirmação.
  6. Pare a captura, feche a conexão e libere os recursos ao concluir a interação.
  • O áudio é transmitido pelas trilhas de mídia do WebRTC. A aplicação deve obter a trilha de áudio local, associar o player remoto e enviar e receber mensagens do 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 qwen-audio-3.1-realtime-plus nesta página, inicie o envio da mídia necessária somente após enviar session.update e receber session.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.
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>WebRTC access example</title>
</head>
<body>
<button id="start-session" type="button">Start</button>
<button id="end-session" type="button">End</button>
<script>
const pc = new RTCPeerConnection({ iceServers: [ ] });

const channels = new Set();
const senders = new Map();
const remoteAudio = document.createElement("audio");
remoteAudio.controls = true; // Allow manual playback if autoplay is blocked.
remoteAudio.autoplay = true;
document.body.appendChild(remoteAudio);

let localStream = null;
let eventChannel = null;
let stopped = false;
let started = false;
let sessionCreated = false;
let updateSent = false;
let modelReady = false;
let mediaStarted = false;
const requestController = new AbortController();
const media = {
  sendAudio: true,
  receiveAudio: true,
};

function mediaDirection(send, receive) {
  if (send && receive) return "sendrecv";
  if (send) return "sendonly";
  if (receive) return "recvonly";
  return "inactive";
}

async function configureMedia() {
  // Keep m=audio. The target service must support the selected directions.
  const transceiver = pc.addTransceiver("audio", {
    direction: mediaDirection(media.sendAudio, media.receiveAudio),
  });
  if (media.sendAudio) senders.set("audio", transceiver.sender);
  if (!media.sendAudio) return;
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: true,
    video: false,
  });
  // The user may end the call while the permission prompt is open.
  if (stopped) {
    stream.getTracks().forEach(track => track.stop());
    throw new Error("Session ended");
  }
  localStream = stream;
  // sender.track is still empty, so no captured data is sent to the model.
}
// See Send and receive events over DataChannels for bindDataChannel.
pc.ondatachannel = ({ channel }) => bindDataChannel(channel);
const clientChannel = pc.createDataChannel("oai-events");
bindDataChannel(clientChannel);
pc.onconnectionstatechange = () => {
  console.log("WebRTC state:", pc.connectionState);
  if (pc.connectionState === "connected") {
    tryInitializeModel();
  } else if (["failed", "disconnected", "closed"].includes(pc.connectionState)) {
    // This example ends the session; implement recovery as needed.
    endSession();
  }
};

function waitForIceComplete() {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => finish(new Error("ICE gathering timed out")), 15000);
    function finish(error) {
      clearTimeout(timer);
      pc.removeEventListener("icegatheringstatechange", check);
      requestController.signal.removeEventListener("abort", cancel);
      error ? reject(error) : resolve();
    }
    function check() {
      if (pc.iceGatheringState === "complete") finish();
    }
    function cancel() { finish(new Error("Session ended")); }
    pc.addEventListener("icegatheringstatechange", check);
    requestController.signal.addEventListener("abort", cancel, { once: true });
    if (stopped) cancel();
    else check();
  });
}

function normalizeAnswerSdp(sdp) {
  return String(sdp).trim().replace(/\r?\n/g, "\r\n") + "\r\n";
}

async function startSession() {
  if (started || stopped) return;
  started = true;
  try {
    await configureMedia();
    if (stopped) return;
    const offer = await pc.createOffer();
    await pc.setLocalDescription(offer);
    await waitForIceComplete();

    // Implement this same-origin application endpoint; it is not a Model Studio API.
    // AppServer forwards SDP with the API key and returns the raw Answer SDP.
    const response = await fetch("/api/realtime/sdp", {
      method: "POST",
      headers: { "Content-Type": "application/sdp" },
      body: pc.localDescription.sdp,
      signal: requestController.signal,
    });
    if (!response.ok) {
      throw new Error(`SDP exchange failed:${response.status} ${await response.text()}`);
    }
    const answerSdp = normalizeAnswerSdp(await response.text());
    if (stopped) return;
    await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });
    // Continue through connectionstatechange, DataChannel, and model events.
  } catch (error) {
    if (!stopped) console.error("Connection failed:", error);
    endSession();
  }
}
function tryInitializeModel() {
  if (stopped || updateSent || !sessionCreated ||
      pc.connectionState !== "connected" ||
      eventChannel?.readyState !== "open") return;
  sendModelEvent({
    event_id: `event_${crypto.randomUUID()}`,
    type: "session.update",
    session: {
      "modalities": media.receiveAudio ? ["audio", "text"] : ["text"],
      "voice": "longanqian_v3.1",
    },
  });
  updateSent = true;
}

async function handleModelEvent(event, channel) {
  if (stopped) return;
  if (event.type === "session.created") {
    sessionCreated = true;
    eventChannel = channel; // Send configuration through the channel that receives session events.
    tryInitializeModel();
  } else if (event.type === "session.updated" && updateSent) {
    modelReady = true;
    await startSendingMedia();
  } else if (event.type === "error") {
    console.error("Model error:", event.error);
    endSession();
  } else {
    // Display text, transcripts, or response status as defined by the selected model. Receive audio over media tracks.
    console.log("Model event:", event);
  }
}
async function startSendingMedia() {
  if (stopped || !modelReady || mediaStarted) return;
  mediaStarted = true;

  for (const track of localStream?.getTracks() ?? []) {

    if (stopped) return;
    const sender = senders.get(track.kind);
    if (sender) await sender.replaceTrack(track);
  }
}

// Register before startSession(). Tracks without streams are also received correctly.
const remoteAudioStream = new MediaStream();
pc.ontrack = ({ track }) => {
  if (stopped) return;
  if (track.kind === "audio" && media.receiveAudio) {
    remoteAudioStream.addTrack(track);
    remoteAudio.srcObject = remoteAudioStream;
    remoteAudio.play().catch(() => {
      console.info("Autoplay is blocked. Use the audio controls to play.");
    });
  }
};
function endSession() {
  if (stopped) return;
  stopped = true;
  modelReady = false;
  sessionCreated = false;
  updateSent = false;
  mediaStarted = false;
  requestController.abort(); // Cancel pending SDP requests and ICE gathering.
  localStream?.getTracks().forEach(track => track.stop());
  localStream = null;
  channels.forEach(channel => channel.close());
  channels.clear();
  eventChannel = null;
  pc.close();
  senders.clear();
  remoteAudioStream.getTracks().forEach(track => track.stop());
  remoteAudio.pause();
  remoteAudio.srcObject = null;
  remoteAudio.remove();
}
function sendModelEvent(event, channel = eventChannel) {
  if (stopped || pc.connectionState !== "connected" ||
      channel?.readyState !== "open") {
    throw new Error("Data channel is not ready");
  }
  channel.send(JSON.stringify(event));
}

function bindDataChannel(channel) {
  channels.add(channel);
  channel.onopen = () => {
    if (stopped) return;
    console.log("DataChannel opened:", channel.label);
    tryInitializeModel();
  };
  channel.onmessage = ({ data }) => {
    if (stopped) return;
    let event;
    try { event = JSON.parse(data); }
    catch (error) {
      console.warn("Cannot parse model event:", error);
      return;
    }
    if (!event || typeof event !== "object") return;
    handleModelEvent(event, channel).catch(error => {
      if (!stopped) console.error("Model event handling failed:", error);
      endSession();
    });
  };
  channel.onerror = error => console.error("DataChannel error:", error);
  channel.onclose = () => {
    channels.delete(channel);
    if (channel === eventChannel) endSession();
  };
  if (channel.readyState === "open") channel.onopen();
}

document.getElementById("start-session").addEventListener("click", startSession);
document.getElementById("end-session").addEventListener("click", endSession);
</script>
</body>
</html>

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.
SettingValue
MétodoPOST
URLhttps://{endpoint}/api/v1/webrtc/realtime?model={model_name}
Content-Typeapplication/sdp
AuthorizationBearer <API_KEY>
Corpo da solicitaçãoOffer SDP
Resposta bem-sucedidaAnswer SDP
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.

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.
O exemplo completo cria o objeto de conexão, as variáveis de estado e os callbacks no mesmo script. Cada chamada cria uma conexão. Após encerrar, reinicialize esses objetos para fazer outra chamada. O objeto de conexão e as variáveis de estado estão detalhados no Exemplo completo. Registre os ouvintes de mensagens antes de inicializar o modelo para não perder eventos de sessão iniciados pelo servidor. Não escute apenas o canal criado pelo cliente: o servidor envia eventos em um canal chamado txt, portanto trate também o callback datachannel.

3. Configurar direções de mídia e DataChannels

Selecionar a direção do áudio

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.
DirectionConfiguration
Enviar áudio negocie a capacidade de envio de áudio e prepare o microfone ou a trilha de áudio externa; associe a trilha quando o modelo estiver pronto
receber áudio— negocie a capacidade de recebimento de áudio e associe a reprodução no callback da trilha remota
Por exemplo, conversas por voz normalmente usam áudio bidirecional. O Offer SDP deve incluir a seção de mídia de áudio m=audio; não remova essa seção apenas porque a aplicação não precisa reproduzir áudio.

Direções de mídia deste modelo

Modelo ou aplicaçãoEnviar áudioReceber áudioEnviar vídeoReceber 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;
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.

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 o envio e o recebimento de áudio separadamente, conforme a necessidade. Não combine 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 usa voz bidirecional. Dois controles em media definem o envio e o recebimento de áudio separadamente. addTransceiver negocia previamente a direção, e a trilha capturada é mantida localmente até o modelo ficar pronto, quando é associada ao sender. Consulte o código no exemplo completo.

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. O DataChannel envia eventos de inicialização, texto e controle e recebe resultados, status e erros do modelo. A trilha de mídia transmite o áudio. 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:
  1. Chame createOffer e setLocalDescription.
  2. Colete os candidatos conforme os métodos ICE aceitos pelo servidor. Neste exemplo, o SDP local é enviado após a coleta ICE terminar.
  3. 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.
  4. Verifique o status HTTP. Em caso de sucesso, passe o Answer SDP retornado para setRemoteDescription.
  5. Aguarde a conexão indicar sucesso e confirme que o DataChannel usado para enviar eventos do modelo está aberto.
A troca SDP bem-sucedida ou a conclusão de 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 esta página para a transmissão de mídia e os modos disponíveis.

Exemplos de eventos do modelo

O áudio é transmitido pela trilha de mídia e não usa o evento de envio de mídia do WebSocket.
O exemplo a seguir mostra o fluxo session.created → session.update → session.updated de qwen-audio-3.1-realtime-plus. Configure os campos conforme a referência de eventos do modelo. Associe a trilha de envio de áudio somente depois de receber session.updated confirmando a conclusão da configuração. Consulte o código no exemplo completo. Para o modelo qwen-audio-3.1-realtime-plus deste exemplo, ao ativar a saída de áudio, é possível acompanhar o estado da geração de áudio pelo evento response.audio.done. Esse evento não indica que a reprodução do áudio no cliente terminou.

Iniciar a transmissão e a recepção de mídia

Quando o modelo estiver pronto, associe a trilha de envio de áudio necessária. Processe a saída do modelo no callback da trilha remota e continue analisando os eventos retornados pelo DataChannel.
  • O áudio é transmitido por faixas de mídia RTP; não é necessário o evento input_audio_buffer.append.
  • Os DataChannels transportam texto e eventos de estado, controle e erro.
No exemplo completo, 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 clicar no botão de encerramento ou fechar a página.

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-Audio-Realtime

Modelo ou aplicaçãoEventos do cliente (envio)Eventos do servidor (recepção)
Qwen-Audio-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.
  • 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.

Referências de eventos