OpenAI Realtime API

O que é a OpenAI Realtime API?

A OpenAI Realtime API fornece comunicação de baixa latência entre sua aplicação e modelos que suportam nativamente interações speech-to-speech. Ela também suporta entradas multimodais — áudio, imagens e texto — e saídas multimodais — áudio e texto —, tornando-a adequada para experiências de voz interativas.

Além de agentes de voz, a Realtime API pode ser usada para transcrição de áudio em tempo real por meio de streaming de áudio via conexão WebSocket. A documentação também destaca pontos de partida recomendados (como o Agents SDK for TypeScript) para fluxos de trabalho de agentes de voz baseados em navegador.

Principais Recursos

• Interações speech-to-speech de baixa latência: Projetada para experiências de áudio conversacionais em tempo real, não apenas request/response.
• Entradas multimodais (áudio, imagens, texto): Permite que uma única sessão aceite diferentes tipos de entrada dependendo do fluxo da aplicação.
• Saídas multimodais (áudio e texto): Suporta o retorno de áudio, texto ou ambos como parte da interação.
• Múltiplos métodos de conexão: Escolha entre WebRTC (navegador/lado do cliente), WebSocket (servidor de camada intermediária com baixa latência consistente) e SIP (telefonia VoIP).
• Guias de ferramentas para sessão e conversa: Inclui orientações sobre prompting, eventos do ciclo de vida da conversa e gerenciamento de comportamento da sessão no servidor.
• Transcrição em tempo real via WebSocket: Fornece um caminho para transcrever fluxos de áudio em tempo real.

Como Usar a OpenAI Realtime API

1. Escolha um método de conexão com base em onde sua app roda: WebRTC para uso em navegador/cliente, WebSocket para servidor/camada intermediária ou SIP para telefonia VoIP.
2. Comece com uma sessão. Para agentes de voz no navegador, a documentação recomenda usar o Agents SDK for TypeScript, que utiliza WebRTC no navegador e WebSocket no servidor.
3. Crie e inicialize uma sessão no seu código, depois conecte usando uma chave de API de cliente (exemplo usa RealtimeAgent e RealtimeSession com session.connect).
4. Interaja com o modelo usando eventos. Após conectar, use os guias fornecidos para prompting/steering, gerenciamento do ciclo de vida da conversa e (quando necessário) controle do lado do servidor via webhooks.

A documentação também menciona detalhes de migração para GA (veja FAQ) que afetam a autenticação de requisições Realtime.

Casos de Uso

• Agente de voz baseado em navegador com speech-to-speech: Use WebRTC (geralmente via Agents SDK for TypeScript) para conectar microfone e saída de áudio para conversa interativa.
• Assistente em tempo real com suporte de servidor: Use uma conexão WebSocket de uma camada intermediária quando quiser rede de baixa latência consistente e gerenciamento centralizado de sessões.
• Integração VoIP/telefonia: Conecte via SIP quando o deployment alvo for um ambiente de telefonia em vez de navegador web.
• Transcrição de áudio em tempo real: Faça streaming de áudio para um fluxo de transcrição Realtime via WebSocket para receber resultados de transcrição enquanto o áudio é enviado.
• Interação multimodal: Aceite áudio junto com imagens e texto em uma única sessão em tempo real, depois retorne áudio, texto ou ambos.

FAQ

Preciso do cabeçalho beta ao usar a GA Realtime API?

Para requisições GA, a documentação afirma que o cabeçalho OpenAI-Beta: realtime=v1 deve ser removido. Se quiser manter o comportamento beta, deve continuar incluindo esse cabeçalho.

Como gero credenciais para sessões Realtime no lado do cliente (navegador)?

Na interface GA, a documentação descreve um único endpoint REST — POST /v1/realtime/client_secrets — para gerar chaves usadas na inicialização de conexões WebRTC ou WebSocket de clientes. O exemplo mostra a criação de uma configuração de sessão e postagem nesse endpoint.

Como WebRTC e WebSocket diferem em onde rodam?

A documentação posiciona o WebRTC como ideal para interações no lado do navegador/cliente, enquanto o WebSocket é ideal para aplicações server-side de camada intermediária com conexões de rede de baixa latência consistente.

Qual mudança de URL se aplica à recuperação de SDP WebRTC?

Ao inicializar uma sessão WebRTC no navegador, a documentação afirma que a URL para obter informações de sessão remota via SDP agora é /v1/realtime/calls.

Posso usar a Realtime API para transcrição sem comportamento completo de agente de voz?

Sim. A documentação destaca especificamente a transcrição de áudio em tempo real transcrevendo fluxos de áudio em tempo real via conexão WebSocket.

Alternativas

• Use o Agents SDK para TypeScript sem construir tudo diretamente sobre os primitivos do Realtime: Isso mantém o foco na orquestração de agentes de voz, aproveitando o Realtime nos bastidores para conectividade no navegador (WebRTC) e no servidor (WebSocket).
• Construa um pipeline de transcrição request/response em vez de streaming: Se seu app não exigir manipulação de áudio em tempo real, um fluxo de transcrição não em tempo real evita a abordagem de sessão orientada a eventos descrita para o Realtime.
• Outras abordagens de comunicação em tempo real para voz: Se precisar de fluxos específicos de telefonia, a integração baseada em SIP é uma opção entre os métodos de conexão do Realtime; caso contrário, escolha entre WebRTC (navegador) e WebSocket (servidor) dependendo do deployment.
• Chat multimodal com endpoints não em tempo real: Se os requisitos de latência forem menos rigorosos que “comunicação de baixa latência”, uma abordagem de chat multimodal não em tempo real pode servir, embora não siga o mesmo fluxo de sessão streaming/eventos descrito na documentação do Realtime.