Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura WebSocket delle API Realtime

Lezione 1 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Architettura WebSocket delle API Realtime
  2. Tre architetture vocali nel 2026
  3. WebRTC, WebSocket o SIP
  4. WebSocket contro REST: perché questa scelta?
  5. Stabilire una connessione WebSocket
  6. Architettura di un’applicazione Realtime
  7. Punti chiave

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno di funzionare il 6 gennaio 2027 (sostituzione: gpt-realtime-2.1-mini, che la guida OpenAI TTS definisce non supportata da /v1/audio/speech: la migrazione della sintesi vocale passa alle API Realtime); gpt-realtime, gpt-4o-realtime e i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations il 26 febbraio 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026. Addendum 3 novembre 2026: sezione sulle tre architetture vocali di OpenAI (GPT-Live, API Realtime, catena di elaborazione) e sulla scelta del trasporto (WebRTC, WebSocket, SIP), basata sulle guide Voice agents, Audio and voice e Getting started with the Realtime API; durata massima della sessione: 60 minuti (Realtime conversations).

Architettura WebSocket delle API Realtime

Le API Realtime di OpenAI rappresentano un cambiamento fondamentale nel modo in cui interagisci con i modelli linguistici. A differenza delle tradizionali API REST che operano su un ciclo richiesta-risposta, le API Realtime utilizzano il protocollo WebSocket per stabilire una connessione persistente e bidirezionale tra la tua applicazione e il modello.

Questa architettura consente lo scambio audio in tempo reale: invii l’audio, il modello lo elabora e risponde vocalmente con bassa latenza, saltando i passaggi intermedi di trascrizione o sintesi vocale. Questo è uno dei mattoni fondamentali per gli agenti vocali conversazionali e il cuore di questo corso.

Tre architetture vocali nel 2026

Prima di aprire un WebSocket, inserisci le API Realtime nel contesto delle altre soluzioni di OpenAI. La guida Voice agents distingue tre approcci:

ArchitetturaIdeale perPerché sceglierla
GPT-LiveConversazioni full-duplex con un backend separatoIl modello vocale ascolta mentre parla e delega il ragionamento e l’uso degli strumenti a un backend di tua scelta; mantiene intatto il tuo agente testuale esistente
API RealtimeVoce, ragionamento e strumenti in un’unica sessioneUn singolo modello interpreta l’audio, decide cosa fare e pronuncia la risposta
Catena di elaborazioneControllo granulare su ogni passaggioTrascrizione, poi agente testuale, poi sintesi vocale: ispezioni o trasformi il testo tra i passaggi e sostituisci ogni componente indipendentemente

Per le nuove applicazioni di conversazione vocale, la pagina Audio and voice di OpenAI raccomanda ora di iniziare con GPT-Live. Le API Realtime rimangono il punto di partenza corretto quando l’agente deve rientrare in un’unica sessione, supportando l’interruzione dell’utente, una rapida prima risposta audio, un avvicendamento naturale dei turni e chiamate dirette agli strumenti. La catena di elaborazione funziona meglio quando ogni passaggio deve rimanere visibile: conservare le trascrizioni, far rispettare le regole prima che l’agente risponda o emettere la voce solo dopo aver validato la risposta.

Questo corso si concentra sulle API Realtime e sulla catena di elaborazione, i cui componenti (trascrizione, sintesi vocale) sono trattati nelle sezioni successive.

WebRTC, WebSocket o SIP

La scelta del trasporto dipende dall’origine dell’audio. Secondo la documentazione: usa WebRTC per l’audio nel browser, con un segreto client effimero generato dal tuo server; WebSocket per le pipeline audio lato server; SIP per le chiamate telefoniche. Una connessione di controllo lato server consente inoltre a un backend attendibile di osservare e guidare una sessione multimediale. Questa lezione dettaglia WebSocket, il modo più semplice per comprendere gli eventi scambiati; in un browser, preferisci WebRTC. Una sessione Realtime dura al massimo 60 minuti.

WebSocket contro REST: perché questa scelta?

In un’architettura REST tradizionale, ogni interazione richiede una richiesta HTTP completa: apertura di una connessione TCP, negoziazione TLS, invio degli header, attesa della risposta e chiusura della connessione. Per l’audio in tempo reale, questo sovraccarico è proibitivo.

Criterio REST (API Responses) WebSocket (API Realtime)
Latenza 200–500 ms per richiesta < 50 ms dopo la connessione
Direzione Solo Client → Server Bidirezionale simultanea
Connessione Nuova per ogni richiesta Persistente (sessione)
Audio File completo richiesto Streaming chunk per chunk

Il protocollo WebSocket mantiene un canale aperto continuamente. Una volta stabilita, client e server possono inviare messaggi in qualsiasi momento senza attendere che l’altro abbia finito.

Stabilire una connessione WebSocket

Ecco come stabilire una connessione alle API Realtime in 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())

L’URL di connessione include il modello come parametro di query. Da quando le API sono diventate generalmente disponibili, è richiesto solo l’header di autenticazione: l’header OpenAI-Beta: realtime=v1 della fase beta è stato rimosso.

Interfaccia annotata il 5 agosto 2026 — Le API Realtime evolvono (modelli, nomi degli eventi, formato della sessione): in caso di dubbio, consulta la documentazione ufficiale.

Architettura di un’applicazione Realtime

Un’applicazione che utilizza le API Realtime segue un’architettura a strati:

1

Livello audio (acquisizione/riproduzione)

Acquisisce il microfono, riproduce le risposte audio. Usa PyAudio, sounddevice o le Web Audio API nel browser.

2

Livello WebSocket (trasporto)

Gestisce la connessione persistente, codifica/decodifica gli eventi JSON, gestisce le riconnessioni.

3

Livello applicazione (logica di business)

Orchestra la conversazione, gestisce il contesto, chiama gli strumenti, elabora i risultati.

4

Livello server (proxy opzionale)

In produzione, un server intermediario protegge la chiave API e aggiunge logica di business lato server.

Il ruolo del server proxy

Durante lo sviluppo, puoi connettere la tua applicazione direttamente alle API Realtime. In produzione, un server proxy è essenziale per:

  • Proteggere la tua chiave API — non esporla mai lato client
  • Autenticare i tuoi utenti — verificare i token prima di aprire la sessione
  • Controllare i costi — limitare la durata della sessione e l’uso dei token
  • Registrare le interazioni — per il debug e la conformità
# 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())

Punti chiave

  • Tre architetture vocali in OpenAI: GPT-Live (consigliato per nuove app conversazionali), API Realtime (voce, ragionamento e strumenti in un’unica sessione) e la catena trascrizione → agente → sintesi
  • WebRTC per l’audio nel browser, WebSocket per le pipeline server, SIP per la telefonia; le sessioni durano al massimo 60 minuti
  • Le API Realtime usano WebSocket per una comunicazione bidirezionale a bassa latenza
  • La connessione è persistente: un’unica apertura per l’intera sessione conversazionale
  • L’architettura a strati separa audio, trasporto, logica di business e proxy server
  • In produzione, un server proxy è essenziale per sicurezza e controllo dei costi
  • Il protocollo è guidato dagli eventi: ogni messaggio è un oggetto JSON con un campo type