API WebSocket de OpenAI: streaming en tiempo real con 75% menos costo

El streaming con WebSocket es la forma más rápida de interactuar con modelos de AI. A diferencia de las solicitudes HTTP tradicionales o incluso de Server-Sent Events (SSE), WebSocket mantiene una conexión persistente y bidireccional entre tu aplicación y la API. Sin configurar una conexión por solicitud, sin sobrecarga de HTTP, sin limitaciones de half-duplex.

Smart AIPI ahora es compatible con este protocolo en wss://api.smartaipi.com/v1/realtime — totalmente compatible con la API WebSocket de OpenAI, con un costo 75% menor.

¿Por qué usar WebSocket en lugar de SSE?

Server-Sent Events ha sido el estándar para el streaming de AI, pero trae compromisos que WebSocket elimina:

Para bucles de agentes que hacen docenas de llamadas consecutivas a la API, el ahorro acumulado de latencia de una conexión WebSocket persistente es significativo.

Cómo funciona

La API WebSocket sigue un protocolo basado en eventos. Envías eventos JSON al servidor y recibes eventos JSON de vuelta, todo a través de una sola conexión persistente.

1. Conectarse y autenticarse

Abre una conexión WebSocket con tu API key en los headers:

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

2. Enviar una solicitud

Envía un evento response.create con tu 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. Recibir eventos de streaming

El servidor devuelve una secuencia de eventos a medida que se genera la respuesta:

Ejemplos 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 (prueba rápida)

Verifica que el handshake de WebSocket se complete correctamente con un solo 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

Una conexión exitosa devuelve HTTP/1.1 101 Switching Protocols.

Cuándo usar WebSocket vs SSE

Ambos protocolos funcionan a través de Smart AIPI. Elige según tu caso de uso:

• Usa SSE para integraciones simples, solicitudes puntuales y cuando quieras la implementación más sencilla posible. Configura stream: true en cualquier llamada estándar a la API.
• Usa WebSocket para bucles de agentes, aplicaciones interactivas, patrones de solicitud de alta frecuencia y cualquier caso en el que necesites la menor latencia posible entre llamadas consecutivas.

Precios

Las solicitudes WebSocket se facturan igual que las solicitudes estándar a la API: según el uso de tokens. Se aplica el descuento del 75%:

Primeros pasos

1. Obtén una API key — Regístrate en smartaipi.com (incluye créditos gratis, no se requiere tarjeta de crédito)
2. Conéctate — Abre un WebSocket a wss://api.smartaipi.com/v1/realtime
3. Envía eventos — Usa el contenedor response.create con tu modelo y prompt
4. Haz streaming de respuestas — Procesa los eventos response.output_text.delta a medida que llegan

Si ya usas la API WebSocket de OpenAI, el único cambio es la URL. Todo lo demás — autenticación, eventos, formato de payload — es idéntico.

Preguntas frecuentes

¿Smart AIPI es compatible con la API WebSocket de OpenAI?

Sí. Conéctate a wss://api.smartaipi.com/v1/realtime con tu API key en el header Authorization. El protocolo es totalmente compatible con la API WebSocket Responses de OpenAI.

¿WebSocket es más rápido que SSE?

Para solicitudes consecutivas, sí. WebSocket mantiene una conexión persistente, eliminando la sobrecarga del handshake TCP y TLS que SSE incurre en cada solicitud nueva. Para solicitudes únicas y puntuales, la diferencia es mínima.

¿Qué modelos funcionan sobre WebSocket?

Todos los modelos disponibles a través de la API Responses: GPT-5.3 Codex, GPT-5.2, Codex Mini y otros. Especifica el modelo en el evento response.create.

¿Function calling y tool use funcionan sobre WebSocket?

Sí. Todo el conjunto de funciones de la API Responses está disponible: function calling, tool use, salidas estructuradas y conversaciones multi-turn funcionan sobre la conexión WebSocket.

¿Hay un límite de tiempo para la conexión?

Las conexiones inactivas se cierran después de 15 minutos. Envía mensajes periódicos o vuelve a conectarte según sea necesario. Las conexiones activas que transmiten datos no se interrumpen.

¿Puedo enviar varias solicitudes en una sola conexión?

Sí. Esa es una de las ventajas clave. Después de que una respuesta termine, envía otro evento response.create en la misma conexión sin volver a conectarte.