Sessioni, eventi e ciclo di vita
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno 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 Realtime API);gpt-realtime,gpt-4o-realtimee 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-transcribee/v1/audio/translationsil 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.
Corretto il 3 novembre 2026. La trascrizione dell’input utilizzava
gpt-live-transcribe, che funziona solo in una sessione di trascrizione e non supporta néserver_vadnésemantic_vad. In una sessione di conversazione come questa, dove il VAD convalida ogni turno, la documentazione specificagpt-transcribe, che trascrive i turni convalidati e utilizza i turni precedenti come contesto. Fonti: Trascrizione in tempo reale · GPT-Transcribe · GPT-Live-Transcribe.
Sessioni, eventi e ciclo di vita
Ogni connessione WebSocket alle Realtime API crea una sessione. Questa sessione è l’unità fondamentale di gestione: incapsula la configurazione del modello, la cronologia della conversazione, gli strumenti disponibili e lo stato corrente dell’interazione. Comprendere il suo ciclo di vita è essenziale per costruire agenti vocali robusti.
Il ciclo di vita di una sessione
Non appena la connessione WebSocket viene stabilita, il server emette un evento session.created. La sessione attraversa diverse fasi:
Connessione → session.created
Il server conferma la sessione con un ID univoco e una configurazione predefinita.
Configurazione → session.update
Invii session.update per definire istruzioni, voce, strumenti e modalità.
Conversazione attiva
Scambio di eventi audio e testo tra client e server.
Chiusura → disconnessione WebSocket
La sessione viene distrutta quando la connessione si chiude. Nessuno stato viene mantenuto sul server.
Configurazione di una sessione
Dopo session.created, invia un evento session.update per configurare il comportamento del modello. La trascrizione di ciò che dice l’utente (audio.input.transcription) è opzionale: senza di essa, ricevi la voce ma non il testo. languages specifica le lingue attese e migliora il riconoscimento:
import asyncio
import websockets
import json
async def configure_session():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
# Attendi session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Sessione creata: {session_id}")
# Configura la sessione
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Sei un assistente vocale di lingua francese. "
"Rispondi in modo conciso e naturale.",
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"prefix_padding_ms": 300,
"silence_duration_ms": 500
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": []
}
}))
# Attendi conferma (potrebbero arrivare prima altri eventi)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Sessione aggiornata")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Parametri chiave della sessione
| Parametro | Descrizione | Valore consigliato |
|---|---|---|
| output_modalities | Modalità di output | ["audio"] (o ["text"]) |
| audio.output.voice | Voce di sintesi | marin, cedar, alloy, echo, ecc. |
| audio.input.turn_detection | Rilevamento fine discorso | server_vad con soglia 0.5 |
| audio.input.format | Formato audio in ingresso | {"type": "audio/pcm", "rate": 24000} |
Il sistema di eventi
Le Realtime API sono interamente basate sugli eventi. Ogni messaggio scambiato è un oggetto JSON con un campo type che ne determina la natura. Gli eventi rientrano in due categorie:
Eventi client (tu → server)
# I principali eventi che invii
client_events = {
"session.update": "Modifica configurazione",
"input_audio_buffer.append": "Invia un chunk audio",
"input_audio_buffer.commit": "Conferma il buffer audio",
"input_audio_buffer.clear": "Svuota il buffer audio",
"conversation.item.create": "Aggiungi un messaggio manualmente",
"conversation.item.truncate": "Tronca una risposta",
"conversation.item.delete": "Elimina un messaggio",
"response.create": "Attiva una risposta",
"response.cancel": "Annulla la risposta corrente",
}
Eventi server (server → te)
# I principali eventi che ricevi
server_events = {
"session.created": "Sessione inizializzata",
"session.updated": "Configurazione applicata",
"input_audio_buffer.speech_started": "Discorso rilevato",
"input_audio_buffer.speech_stopped": "Silenzio rilevato",
"conversation.item.created": "Nuovo messaggio nella cronologia",
"response.created": "Generazione avviata",
"response.output_audio.delta": "Chunk audio della risposta",
"response.output_audio_transcript.delta": "Chunk di trascrizione",
"response.done": "Risposta terminata",
"error": "Errore",
}
Gestione degli errori
Gli errori vengono emessi tramite un evento di tipo error. Devi sempre intercettarli:
async def handle_events(ws):
async for raw_message in ws:
event = json.loads(raw_message)
event_type = event["type"]
if event_type == "error":
error = event["error"]
print(f"Errore [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Errore di configurazione, correggi e riprova
pass
elif error["type"] == "server_error":
# Problema lato OpenAI, riconnetti
pass
elif event_type == "session.updated":
print("Configurazione applicata con successo")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Token utilizzati: {usage}")
Punti chiave
- Una sessione viene creata automaticamente alla connessione WebSocket e distrutta alla disconnessione
session.updateconfigura la sessione doposession.created; attendisession.updatedprima di fare affidamento sulla nuova configurazione- Per trascrivere l’input in una sessione di conversazione, usa
gpt-transcribe;gpt-live-transcribeè riservato alle sessioni di trascrizione - Il protocollo è puramente basato sugli eventi: ogni messaggio ha un
typeche ne determina la gestione - Gli eventi client guidano l’interazione; gli eventi server riportano i risultati
- La gestione degli errori è fondamentale: ascolta sempre gli eventi
error