Usar a API GPT em tempo real via WebSockets

A API do GPT Realtime do OpenAI do Azure para fala e áudio faz parte da família de modelos GPT-4o que oferece suporte a interações conversacionais de baixa latência, do tipo "fala de entrada, fala de saída".

Você pode usar a API em tempo real via WebRTC, SIP ou WebSocket para enviar entrada de áudio para o modelo e receber respostas de áudio em tempo real.

Siga as instruções neste artigo para começar a usar a API do Realtime por meio de WebSockets. Use a API em tempo real por meio de WebSockets em cenários de servidor para servidor em que a baixa latência não é um requisito.

Use a tabela a seguir para ajudá-lo a escolher o protocolo certo para seu cenário:

Pré-requisitos

Antes de usar o áudio gpt em tempo real, você precisa:

• Uma assinatura Azure. Crie um gratuitamente.
• Um recurso Microsoft Foundry. Crie o recurso em uma das regiões com suporte. Para obter as etapas de instalação, consulte Criar um recurso Microsoft Foundry.
• Uma implantação de um modelo de gpt em tempo real em uma região com suporte, conforme descrito na seção modelos com suporte neste artigo.
  • No portal do Foundry, carregue seu projeto. Selecione Compilar no menu superior direito, selecione a guia Modelos no painel esquerdo e selecione Implantar um modelo base. Pesquise o modelo desejado e selecione Implantar na página do modelo.
• Bibliotecas necessárias:
  • Python: pip install websockets azure-identity
  • JavaScript/Node.js: npm install ws @azure/identity

Modelos com suporte

Os modelos de GPT em tempo real estão disponíveis para implantações globais nas regiões Leste dos EUA 2 e Central da Suécia.

• gpt-4o-mini-realtime-preview (2024-12-17)
• gpt-4o-realtime-preview (2024-12-17)
• gpt-realtime (2025-08-28)
• gpt-realtime-mini (2025-10-06)
• gpt-realtime-mini (2025-12-15)
• gpt-realtime-1.5 (2026-02-23)

Para obter mais informações sobre modelos com suporte, consulte a documentação de modelos e versões.

Conexão e autenticação

A API em tempo real (via /realtime) é criada na API WebSockets para facilitar a comunicação de streaming totalmente assíncrona entre o usuário final e o modelo.

A API em tempo real é acessada por meio de uma conexão WebSocket segura com o /realtime ponto de extremidade do seu recurso do Azure OpenAI.

Você pode construir um URI de solicitação completa concatenando:

• O protocolo WebSocket seguro (wss://).
• O nome do host do ponto de extremidade do recurso do Azure OpenAI, por exemplo, my-aoai-resource.openai.azure.com
• O caminho da API: openai/v1/realtime para GA ou openai/realtime para visualização.
• Um parâmetro da cadeia de consulta model com o nome da sua implantação de modelo gpt-realtime, gpt-realtime-1.5 ou gpt-realtime-mini.
• (Somente versão prévia) Um api-version parâmetro de cadeia de caracteres de consulta para uma versão de API com suporte, como 2025-04-01-preview e um deployment parâmetro de consulta em vez de model.

O exemplo a seguir é um URI de solicitação bem construído /realtime :

wss://my-eastus2-openai-resource.openai.azure.com/openai/v1/realtime?model=gpt-realtime-deployment-name

wss://my-eastus2-openai-resource.openai.azure.com/openai/realtime?api-version=2025-04-01-preview&deployment=gpt-4o-mini-realtime-preview-deployment-name

Para autenticar:

• Microsoft Entra (recomendado): use a autenticação baseada em token com a API /realtime para um recurso do OpenAI do Azure com identidade gerenciada habilitada. Aplique um token de autenticação recuperado usando um token Bearer com o cabeçalho Authorization.
• Chave de API: uma api-key pode ser fornecida de duas maneiras:
  • Como usar um api-key cabeçalho de conexão na conexão pré-handshake. Essa opção não está disponível em um ambiente de navegador.
  • Usando um api-key parâmetro de cadeia de caracteres de consulta no URI da solicitação. Os parâmetros de cadeia de caracteres de consulta são criptografados ao usar HTTPS/WSS.

API em tempo real por meio da arquitetura do WebSockets

Depois que a sessão de conexão do WebSocket com /realtime for estabelecida e autenticada, a interação funcional ocorre por meio de eventos para o envio e recebimento de mensagens WebSocket. Cada um desses eventos assume a forma de um objeto JSON.

Os eventos podem ser enviados e recebidos em paralelo e os aplicativos geralmente devem lidar com eles simultaneamente e de forma assíncrona.

• Um chamador do lado do cliente estabelece uma conexão com /realtime, que inicia uma nova session.
• Um session cria automaticamente um padrão conversation. Não há suporte para várias conversas simultâneas.
• O conversation acumula sinais de entrada até que um response seja iniciado, seja por meio de um evento direto do chamador ou automaticamente pela detecção de atividade de voz (VAD).
• Cada response consiste em um ou mais items, que podem encapsular mensagens, chamadas de função e outras informações.
• Cada mensagem item tem content_part, permitindo que várias modalidades (texto e áudio) sejam representadas em um único item.
• O session gerencia a configuração do tratamento de entrada do chamador (por exemplo, áudio do usuário) e o tratamento comum da geração de saída.
• Cada chamada iniciada response.create pode substituir parte do comportamento de saída response, se desejado.
• Os item criados pelo servidor e os content_part nas mensagens podem ser preenchidos de forma assíncrona e em paralelo. Por exemplo, receber informações de áudio, texto e função simultaneamente de forma round robin.

Experimente o início rápido

Agora que você fez as etapas acima, você pode seguir as instruções no início rápido da API em tempo real para começar a usar a API realtime por meio de WebSockets.

Conteúdo relacionado

• Experimente o início rápido de áudio em tempo real
• Consulte a referência da API em tempo real
• Saiba mais sobre Azure openai quotas e limites