Utilize a API Realtime GPT via WebSockets

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

Pode usar a API em tempo real via WebRTC, SIP ou WebSocket para enviar entrada de áudio ao modelo e receber respostas áudio em tempo real.

Siga as instruções deste artigo para começar a usar a API em tempo real através do WebSockets. Usa a API em tempo real via WebSockets em situações de servidor para servidor onde baixa latência não é obrigatória.

Use a tabela seguinte para o ajudar a escolher o protocolo certo para o seu cenário:

Pré-requisitos

Antes de poder usar áudio em tempo real GPT, precisa de:

• Uma subscrição do Azure. Crie um gratuitamente.
• Um recurso da Microsoft Foundry. Crie o recurso numa das regiões suportadas. Para os passos de configuração, veja Criar um recurso Microsoft Foundry.
• Uma implementação de um modelo GPT em tempo real numa região suportada, conforme descrito na secção de modelos suportados deste artigo.
  • No portal da Foundry, carregue o seu projeto. Selecione Construir no menu superior direito, depois selecione o separador Modelos no painel esquerdo e selecione Implementar um modelo base. Procura o modelo que queres e seleciona Implementar na página do modelo.
• Bibliotecas obrigatórias:
  • Python: pip install websockets azure-identity
  • JavaScript/Node.js: npm install ws @azure/identity

Modelos suportados

Os modelos GPT em tempo real estão disponíveis para implementações globais nas regiões East US 2 e Suécia Central.

• 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 mais informações sobre modelos suportados, consulte a documentação de modelos e versões.

Ligação e autenticação

A API Realtime (via /realtime) é construída sobre a API WebSockets para facilitar a comunicação em streaming totalmente assíncrona entre o utilizador final e o modelo.

A API em tempo real é acedida através de uma ligação WebSocket segura ao endpoint /realtime do seu recurso Azure OpenAI.

Pode construir um URI de pedido completo concatenando:

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

O exemplo seguinte é um URI de pedido bem estruturado /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 autenticação baseada em token com a API /realtime para um recurso Azure OpenAI com identidade gerida ativada. Aplique um token de autenticação recuperado usando um Bearer token com o Authorization cabeçalho.
• Chave API: An api-key pode ser fornecida de duas formas:
  • Usar um api-key cabeçalho de ligação na ligação pré-handshake. Esta opção não está disponível num ambiente de navegador.
  • Usando um api-key parâmetro de string de consulta no URI do pedido. Os parâmetros da string de consulta são encriptados quando se utiliza HTTPS/WSS.

API em tempo real via arquitetura WebSockets

Uma vez estabelecida e autenticada a sessão de ligação WebSocket a /realtime, a interação funcional ocorre através de eventos para enviar e receber mensagens WebSocket. Estes eventos assumem cada um a forma de um objeto JSON.

Os eventos podem ser enviados e recebidos em paralelo e as aplicações devem geralmente tratá-los simultaneamente e de forma assíncrona.

• Um chamador do lado do cliente estabelece uma ligação a /realtime, que inicia um novo session.
• A session cria automaticamente um padrão conversation. Múltiplas conversas simultâneas não são suportadas.
• Acumula conversation sinais de entrada até que o response seja iniciado, seja através de um evento direto pelo chamador ou automaticamente por deteção de atividade de voz (VAD).
• Cada um response consiste numa ou mais items, que podem encapsular mensagens, chamadas de funções e outras informações.
• Cada mensagem item tem content_part, permitindo que múltiplas modalidades (texto e áudio) sejam representadas num único item.
• O session gere a configuração do tratamento da entrada do chamador (por exemplo, áudio do utilizador) e do tratamento comum da geração de saídas.
• Cada chamador iniciado response.create pode sobrepor parte do comportamento de saída response , se desejar.
• Criadas item pelo servidor e as content_part nas mensagens podem ser preenchidas de forma assíncrona e em paralelo. Por exemplo, receber áudio, texto e informações funcionais em simultâneo, em formato round robin.

Experimenta o início rápido

Agora que já fez os passos acima, pode seguir as instruções no quickstart da API Realtime para começar com a API Realtime através do 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 c0