API WebSocket da OpenAI: streaming em tempo real com 75% menos custo

O streaming via WebSocket é a forma mais rápida de interagir com modelos de AI. Ao contrário de requisições HTTP tradicionais ou até mesmo de Server-Sent Events (SSE), o WebSocket mantém uma conexão persistente e bidirecional entre sua aplicação e a API. Sem configuração de conexão a cada requisição, sem overhead de HTTP, sem limitações half-duplex.

O Smart AIPI agora oferece suporte a esse protocolo em wss://api.smartaipi.com/v1/realtime — totalmente compatível com a API WebSocket da OpenAI, com custo 75% menor.

Por que usar WebSocket em vez de SSE?

Server-Sent Events têm sido o padrão para streaming de AI, mas trazem trade-offs que o WebSocket elimina:

Para loops de agents que fazem dezenas de chamadas de API em sequência, a economia acumulada de latência com uma conexão WebSocket persistente é significativa.

Como funciona

A API WebSocket segue um protocolo orientado a eventos. Você envia eventos JSON para o servidor e recebe eventos JSON de volta — tudo por uma única conexão persistente.

1. Conecte-se e autentique

Abra uma conexão WebSocket com sua API key nos headers:

wss://api.smartaipi.com/v1/realtime
Authorization: Bearer sk-proj-your-smart-aipi-key
OpenAI-Beta: realtime=v1

2. Envie uma requisição

Envie um evento response.create com seu prompt:

{
  "type": "response.create",
  "response": {
    "model": "gpt-5.3-codex",
    "store": false,
    "instructions": "You are a helpful assistant.",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "What is WebSocket?" }
        ]
      }
    ]
  }
}

3. Receba eventos de streaming

O servidor envia de volta uma sequência de eventos à medida que a resposta é gerada:

Exemplos de código

Node.js

import WebSocket from "ws";

const ws = new WebSocket("wss://api.smartaipi.com/v1/realtime", {
  headers: {
    "Authorization": "Bearer sk-proj-your-key",
    "OpenAI-Beta": "realtime=v1",
  },
});

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "response.create",
    response: {
      model: "gpt-5.3-codex",
      store: false,
      input: [{
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Hello!" }],
      }],
    },
  }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data);
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
  if (event.type === "response.completed") {
    console.log("\n\nDone. Usage:", event.response.usage);
    ws.close();
  }
});

Python

import asyncio
import json
import websockets

async def main():
    headers = {
        "Authorization": "Bearer sk-proj-your-key",
        "OpenAI-Beta": "realtime=v1",
    }

    async with websockets.connect(
        "wss://api.smartaipi.com/v1/realtime",
        extra_headers=headers,
    ) as ws:
        await ws.send(json.dumps({
            "type": "response.create",
            "response": {
                "model": "gpt-5.3-codex",
                "store": False,
                "input": [{
                    "type": "message",
                    "role": "user",
                    "content": [{"type": "input_text", "text": "Hello!"}],
                }],
            },
        }))

        async for message in ws:
            event = json.loads(message)
            if event["type"] == "response.output_text.delta":
                print(event["delta"], end="", flush=True)
            if event["type"] == "response.completed":
                print(f"\n\nUsage: {event['response']['usage']}")
                break

asyncio.run(main())

cURL (teste rápido)

Verifique se o handshake do WebSocket é bem-sucedido com um único comando:

curl -isN --http1.1 \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGVzdA==" \
  -H "Authorization: Bearer sk-proj-your-key" \
  -H "OpenAI-Beta: realtime=v1" \
  https://api.smartaipi.com/v1/realtime

Uma conexão bem-sucedida retorna HTTP/1.1 101 Switching Protocols.

Quando usar WebSocket vs SSE

Ambos os protocolos funcionam com o Smart AIPI. Escolha com base no seu caso de uso:

• Use SSE para integrações simples, requisições pontuais e quando você quiser a implementação mais simples possível. Defina stream: true em qualquer chamada padrão da API.
• Use WebSocket para loops de agents, aplicações interativas, padrões de requisição de alta frequência e qualquer cenário em que você precise da menor latência possível entre chamadas consecutivas.

Preços

As requisições via WebSocket são cobradas da mesma forma que requisições padrão da API — por uso de tokens. O desconto de 75% se aplica:

Primeiros passos

1. Obtenha uma API key — Cadastre-se em smartaipi.com (créditos grátis incluídos, sem necessidade de cartão de crédito)
2. Conecte-se — Abra um WebSocket para wss://api.smartaipi.com/v1/realtime
3. Envie eventos — Use o envelope response.create com seu modelo e prompt
4. Faça streaming das respostas — Processe os eventos response.output_text.delta conforme chegarem

Se você já usa a API WebSocket da OpenAI, a única mudança é a URL. Todo o resto — autenticação, eventos, formato do payload — é idêntico.

Perguntas frequentes

O Smart AIPI oferece suporte à API WebSocket da OpenAI?

Sim. Conecte-se a wss://api.smartaipi.com/v1/realtime com sua API key no header Authorization. O protocolo é totalmente compatível com a WebSocket Responses API da OpenAI.

WebSocket é mais rápido que SSE?

Para requisições consecutivas, sim. O WebSocket mantém uma conexão persistente, eliminando o overhead de handshake TCP e TLS que o SSE gera em cada nova requisição. Para requisições únicas e pontuais, a diferença é desprezível.

Quais modelos funcionam via WebSocket?

Todos os modelos disponíveis pela Responses API: GPT-5.3 Codex, GPT-5.2, Codex Mini e outros. Especifique o modelo no evento response.create.

Function calling e uso de tools funcionam via WebSocket?

Sim. Todo o conjunto de recursos da Responses API está disponível — function calling, uso de tools, saídas estruturadas e conversas multi-turn funcionam pela conexão WebSocket.

Existe limite de tempo para a conexão?

Conexões ociosas são encerradas após 15 minutos. Envie mensagens periódicas ou reconecte quando necessário. Conexões ativas transmitindo dados não são interrompidas.

Posso enviar múltiplas requisições em uma única conexão?

Sim. Essa é uma das principais vantagens. Depois que uma resposta for concluída, envie outro evento response.create na mesma conexão sem reconectar.