API WebSocket di OpenAI: streaming in tempo reale con il 75% di costo in meno

Lo streaming WebSocket è il modo più veloce per interagire con i modelli AI. A differenza delle richieste HTTP tradizionali o anche di Server-Sent Events (SSE), WebSocket mantiene una connessione persistente e bidirezionale tra la tua applicazione e l'API. Nessuna configurazione della connessione per richiesta, nessun overhead HTTP, nessun limite half-duplex.

Smart AIPI ora supporta questo protocollo su wss://api.smartaipi.com/v1/realtime — completamente compatibile con l'API WebSocket di OpenAI, con un costo inferiore del 75%.

Perché WebSocket invece di SSE?

Server-Sent Events è stato lo standard per lo streaming AI, ma comporta compromessi che WebSocket elimina:

Per i loop di agent che eseguono decine di chiamate API consecutive, il risparmio cumulativo di latenza ottenuto con una connessione WebSocket persistente è significativo.

Come funziona

L'API WebSocket segue un protocollo event-driven. Invi la eventi JSON al server e ricevi eventi JSON in risposta — tutto su un'unica connessione persistente.

1. Connetti e autentica

Apri una connessione WebSocket con la tua API key negli header:

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

2. Invia una richiesta

Invia un evento response.create con il tuo 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. Ricevi eventi in streaming

Il server invia una sequenza di eventi mentre la risposta viene generata:

Esempi di codice

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 (test rapido)

Verifica che l'handshake WebSocket riesca con un singolo 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 connessione riuscita restituisce HTTP/1.1 101 Switching Protocols.

Quando usare WebSocket invece di SSE

Entrambi i protocolli funzionano tramite Smart AIPI. Scegli in base al tuo caso d'uso:

• Usa SSE per integrazioni semplici, richieste una tantum e quando vuoi l'implementazione più semplice possibile. Imposta stream: true su qualsiasi chiamata API standard.
• Usa WebSocket per loop di agent, applicazioni interattive, pattern di richieste ad alta frequenza e ovunque ti serva la latenza più bassa possibile tra chiamate consecutive.

Prezzi

Le richieste WebSocket vengono fatturate come le richieste API standard — in base all'utilizzo dei token. Si applica lo sconto del 75%:

Come iniziare

1. Ottieni una API key — Registrati su smartaipi.com (crediti gratuiti inclusi, nessuna carta di credito richiesta)
2. Connettiti — Apri un WebSocket verso wss://api.smartaipi.com/v1/realtime
3. Invia eventi — Usa il contenitore response.create con il tuo modello e prompt
4. Trasmetti le risposte in streaming — Elabora gli eventi response.output_text.delta man mano che arrivano

Se stai già usando l'API WebSocket di OpenAI, l'unica modifica è l'URL. Tutto il resto — autenticazione, eventi, formato del payload — è identico.

Domande frequenti

Smart AIPI supporta l'API WebSocket di OpenAI?

Sì. Collegati a wss://api.smartaipi.com/v1/realtime con la tua API key nell'header Authorization. Il protocollo è completamente compatibile con la WebSocket Responses API di OpenAI.

WebSocket è più veloce di SSE?

Per richieste consecutive, sì. WebSocket mantiene una connessione persistente, eliminando l'overhead dell'handshake TCP e TLS che SSE comporta a ogni nuova richiesta. Per richieste singole una tantum, la differenza è trascurabile.

Quali modelli funzionano tramite WebSocket?

Tutti i modelli disponibili tramite la Responses API: GPT-5.3 Codex, GPT-5.2, Codex Mini e altri. Specifica il modello nell'evento response.create.

Function calling e uso degli strumenti funzionano tramite WebSocket?

Sì. È disponibile l'intero set di funzionalità della Responses API — function calling, tool use, output strutturati e conversazioni multi-turn funzionano tutti sulla connessione WebSocket.

Esiste un limite di tempo per la connessione?

Le connessioni inattive vengono chiuse dopo 15 minuti. Invia messaggi periodici o riconnettiti quando necessario. Le connessioni attive che stanno trasmettendo dati in streaming non vengono interrotte.

Posso inviare più richieste su una sola connessione?

Sì. Questo è uno dei vantaggi principali. Dopo il completamento di una risposta, invia un altro evento response.create sulla stessa connessione senza riconnetterti.