Arquitetura WebSocket da API em Tempo Real
Nesta página
Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (substituição:gpt-realtime-2.1-mini, que o guia de TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de fala passa para a API em Tempo Real);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz em full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026. Adenda de 3 de novembro de 2026: secção sobre as três arquiteturas de voz da OpenAI (GPT-Live, API em Tempo Real, cadeia de processamento) e seleção do transporte (WebRTC, WebSocket, SIP), com base nos guias Voice agents, Audio and voice e Getting started with the Realtime API; duração máxima da sessão: 60 minutos (Realtime conversations).
Arquitetura WebSocket da API em Tempo Real
A API em Tempo Real da OpenAI representa uma mudança fundamental de paradigma na forma como interage com modelos de linguagem. Ao contrário das APIs REST tradicionais, que operam num ciclo de pedido-resposta, a API em Tempo Real utiliza o protocolo WebSocket para estabelecer uma ligação persistente e bidirecional entre a sua aplicação e o modelo.
Esta arquitetura permite a troca de áudio em tempo real: envia áudio, o modelo processa-o e responde vocalmente com baixa latência, ignorando etapas intermédias de transcrição ou de texto-para-fala. Este é um dos blocos de construção essenciais para agentes de voz conversacionais e o cerne deste curso.
Três Arquiteturas de Voz em 2026
Antes de abrir uma ligação WebSocket, contextualize a API em Tempo Real face às outras soluções da OpenAI. O guia Voice agents distingue três abordagens:
| Arquitetura | Ideal para | Porquê escolher |
|---|---|---|
| GPT-Live | Conversas full-duplex com um backend separado | O modelo de voz ouve enquanto fala e delega o raciocínio e o uso de ferramentas num backend à sua escolha; mantém o seu agente de texto existente intacto |
| API em Tempo Real | Fala, raciocínio e ferramentas numa única sessão | Um único modelo interpreta o áudio, decide o que fazer e fala a resposta |
| Cadeia de processamento | Controlo granular de cada etapa | Transcrição, depois agente de texto, depois síntese de fala: inspeciona ou transforma texto entre etapas e substitui cada componente de forma independente |
Para novas aplicações de conversação por voz, a página Audio and voice da OpenAI recomenda agora começar com o GPT-Live. A API em Tempo Real continua a ser o ponto de partida correto quando o agente deve caber numa única sessão, suportando interrupção do utilizador, primeira resposta de áudio rápida, tomada de turno natural e chamadas diretas a ferramentas. A cadeia de processamento funciona melhor quando cada etapa deve permanecer visível: reter transcrições, aplicar regras antes de o agente responder ou emitir voz apenas após validar a resposta.
Este curso foca-se na API em Tempo Real e na cadeia de processamento, cujos componentes (transcrição, síntese de fala) são abordados em secções subsequentes.
WebRTC, WebSocket ou SIP
A escolha do transporte depende da origem do áudio. Segundo a documentação: utilize WebRTC para áudio no navegador, com um segredo de cliente efémero gerado pelo seu servidor; WebSocket para pipelines de áudio no lado do servidor; SIP para chamadas telefónicas. Uma ligação de controlo no lado do servidor também permite que um backend fidedigno observe e oriente uma sessão de média. Esta lição detalha o WebSocket, a forma mais simples de compreender os eventos trocados; num navegador, prefira o WebRTC. Uma sessão em Tempo Real dura, no máximo, 60 minutos.
WebSocket vs. REST: Porquê Esta Escolha?
Numa arquitetura REST tradicional, cada interação exige um pedido HTTP completo: abrir uma ligação TCP, negociação TLS, envio de cabeçalhos, espera pela resposta e fecho da ligação. Para áudio em tempo real, esta sobrecarga é proibitiva.
| Critério | REST (API de Respostas) | WebSocket (API em Tempo Real) |
|---|---|---|
| Latência | 200–500 ms por pedido | < 50 ms após ligação |
| Direção | Apenas Cliente → Servidor | Bidirecional simultâneo |
| Ligação | Nova para cada pedido | Persistente (sessão) |
| Áudio | Ficheiro completo necessário | Streaming bloco a bloco |
O protocolo WebSocket mantém um canal aberto continuamente. Uma vez estabelecido, o cliente e o servidor podem enviar mensagens a qualquer momento, sem esperar que o outro termine.
Estabelecer uma Ligação WebSocket
Eis como estabelecer uma ligação à API em Tempo Real em Python:
import asyncio
import websockets
import json
OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
async def connect_realtime():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
print("Connected to Realtime API")
# Receive the welcome event
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Keep the connection open
await asyncio.Future()
asyncio.run(connect_realtime())
O URL da ligação inclui o modelo como parâmetro de consulta. Desde que a API atingiu a disponibilidade geral, apenas o cabeçalho de autenticação é necessário; o cabeçalho OpenAI-Beta: realtime=v1 da fase beta foi removido.
Interface assinalada a 5 de agosto de 2026 — A API em Tempo Real evolui (modelos, nomes de eventos, formato de sessão): em caso de dúvida, consulte a documentação oficial.
Arquitetura de Aplicações em Tempo Real
Uma aplicação que utiliza a API em Tempo Real segue uma arquitetura em camadas:
Camada de áudio (captura/reprodução)
Captura o microfone, reproduz respostas de áudio. Utiliza PyAudio, sounddevice ou a Web Audio API no navegador.
Camada WebSocket (transporte)
Gerencia a ligação persistente, codifica/descodifica eventos JSON, trata de reconexões.
Camada de aplicação (lógica de negócio)
Orquestra a conversação, gere o contexto, chama ferramentas, processa resultados.
Camada de servidor (proxy opcional)
Em produção, um servidor intermédio protege a chave da API e adiciona lógica de negócio no lado do servidor.
O Papel do Servidor Proxy
Durante o desenvolvimento, pode ligar a sua aplicação diretamente à API em Tempo Real. Em produção, um servidor proxy é essencial para:
- Proteger a sua chave de API — nunca a exponha no lado do cliente
- Autenticar os seus utilizadores — verificar tokens antes de abrir a sessão
- Controlar custos — limitar a duração da sessão e o uso de tokens
- Registar interações — para depuração e conformidade
# Simplified example of a WebSocket proxy with FastAPI
from fastapi import FastAPI, WebSocket
import websockets
app = FastAPI()
@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
await client_ws.accept()
headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}
async with websockets.connect(URL, additional_headers=headers) as openai_ws:
async def forward_to_openai():
async for message in client_ws.iter_text():
await openai_ws.send(message)
async def forward_to_client():
async for message in openai_ws:
await client_ws.send_text(message)
await asyncio.gather(forward_to_openai(), forward_to_client())
Pontos-chave
- Três arquiteturas de voz na OpenAI: GPT-Live (recomendado para novas aplicações conversacionais), API em Tempo Real (fala, raciocínio e ferramentas numa sessão) e a cadeia transcrição → agente → síntese
- WebRTC para áudio no navegador, WebSocket para pipelines no servidor, SIP para telefonia; as sessões duram no máximo 60 minutos
- A API em Tempo Real utiliza WebSocket para comunicação bidirecional de baixa latência
- A ligação é persistente: uma única abertura para toda a sessão conversacional
- A arquitetura em camadas separa áudio, transporte, lógica de negócio e proxy de servidor
- Em produção, um servidor proxy é essencial para segurança e controlo de custos
- O protocolo é orientado a eventos: cada mensagem é um objeto JSON com um campo
type