Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Arquitetura WebSocket da API em Tempo Real

Aula 1 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Arquitetura WebSocket da API em Tempo Real
  2. Três Arquiteturas de Voz em 2026
  3. WebRTC, WebSocket ou SIP
  4. WebSocket vs. REST: Porquê Esta Escolha?
  5. Estabelecer uma Ligação WebSocket
  6. Arquitetura de Aplicações em Tempo Real
  7. Pontos-chave

Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarã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-realtime e 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-transcribe e /v1/audio/translations a 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:

ArquiteturaIdeal paraPorquê escolher
GPT-LiveConversas full-duplex com um backend separadoO 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 RealFala, raciocínio e ferramentas numa única sessãoUm único modelo interpreta o áudio, decide o que fazer e fala a resposta
Cadeia de processamentoControlo granular de cada etapaTranscriçã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:

1

Camada de áudio (captura/reprodução)

Captura o microfone, reproduz respostas de áudio. Utiliza PyAudio, sounddevice ou a Web Audio API no navegador.

2

Camada WebSocket (transporte)

Gerencia a ligação persistente, codifica/descodifica eventos JSON, trata de reconexões.

3

Camada de aplicação (lógica de negócio)

Orquestra a conversação, gere o contexto, chama ferramentas, processa resultados.

4

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