Sesiuni, evenimente și ciclu de viață
Pe această pagină
Actualizat la 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate:
tts-1,tts-1-hdșigpt-4o-mini-ttsvor înceta să funcționeze la 6 ianuarie 2027 (înlocuitor:gpt-realtime-2.1-mini, pe care ghidul OpenAI TTS precizează că nu este suportat de/v1/audio/speech: migrarea sintezei vocale se mută în Realtime API);gpt-realtime,gpt-4o-realtimeși modelele audio legacy la 20 ianuarie 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeși/v1/audio/translationsla 26 februarie 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pentru voce full-duplex, GPT-Live 1 este disponibil în API din 10 septembrie 2026.
Corectat la 3 noiembrie 2026. Transcrierea inputului folosea
gpt-live-transcribe, care funcționează doar într-o sesiune de transcriere și nu suportă niciserver_vad, nicisemantic_vad. Într-o sesiune de conversație ca aceasta, unde VAD validează fiecare intervenție, documentația specificăgpt-transcribe, care transcrie intervențiile validate și folosește intervențiile anterioare drept context. Surse: Transcriere în timp real · GPT-Transcribe · GPT-Live-Transcribe.
Sesiuni, evenimente și ciclu de viață
Fiecare conexiune WebSocket la Realtime API creează o sesiune. Această sesiune reprezintă unitatea fundamentală de gestionare: ea încapsulează configurarea modelului, istoricul conversației, instrumentele disponibile și starea curentă a interacțiunii. Înțelegerea ciclului său de viață este esențială pentru construirea unor agenți vocali robusti.
Ciclul de viață al unei sesiuni
Imediat ce conexiunea WebSocket este stabilită, serverul emite un eveniment session.created. Sesiunea parcurge mai multe faze:
Conexiune → session.created
Serverul confirmă sesiunea cu un ID unic și o configurație implicită.
Configurare → session.update
Trimiteți session.update pentru a defini instrucțiunile, vocea, instrumentele și modalitățile.
Conversație activă
Schimb de evenimente audio și text între client și server.
Închidere → deconectare WebSocket
Sesiunea este distrusă la închiderea conexiunii. Nicio stare nu este păstrată pe server.
Configurarea unei sesiuni
După session.created, trimiteți un eveniment session.update pentru a configura comportamentul modelului. Transcrierea a ceea ce spune utilizatorul (audio.input.transcription) este opțională: fără aceasta, primiți vocea, dar nu și textul. languages specifică limbile așteptate și îmbunătățește recunoașterea:
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:
# Așteptați session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Sesiune creată: {session_id}")
# Configurați sesiunea
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Ești un asistent vocal care vorbește franceză. "
"Răspunde concis și natural.",
"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": []
}
}))
# Așteptați confirmarea (alte evenimente pot sosi mai întâi)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Sesiune actualizată")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Parametri cheie ai sesiunii
| Parametru | Descriere | Valoare recomandată |
|---|---|---|
| output_modalities | Modalități de ieșire | ["audio"] (sau ["text"]) |
| audio.output.voice | Voce de sinteză | marin, cedar, alloy, echo etc. |
| audio.input.turn_detection | Detectarea sfârșitului vorbirii | server_vad cu pragul 0.5 |
| audio.input.format | Format audio de intrare | {"type": "audio/pcm", "rate": 24000} |
Sistemul de evenimente
Realtime API este integral bazat pe evenimente. Fiecare mesaj schimbat este un obiect JSON cu un câmp type care îi determină natura. Evenimentele se împart în două categorii:
Evenimente client (dumneavoastră → server)
# Principalele evenimente pe care le trimiteți
client_events = {
"session.update": "Modifică configurația",
"input_audio_buffer.append": "Trimite un fragment audio",
"input_audio_buffer.commit": "Confirmă bufferul audio",
"input_audio_buffer.clear": "Golește bufferul audio",
"conversation.item.create": "Adaugă un mesaj manual",
"conversation.item.truncate": "Trunchiază un răspuns",
"conversation.item.delete": "Șterge un mesaj",
"response.create": "Declanșează un răspuns",
"response.cancel": "Anulează răspunsul curent",
}
Evenimente server (server → dumneavoastră)
# Principalele evenimente pe care le primiți
server_events = {
"session.created": "Sesiune inițializată",
"session.updated": "Configurație aplicată",
"input_audio_buffer.speech_started": "Vorbire detectată",
"input_audio_buffer.speech_stopped": "Silent detectat",
"conversation.item.created": "Mesaj nou în istoric",
"response.created": "Generare începută",
"response.output_audio.delta": "Fragment audio de răspuns",
"response.output_audio_transcript.delta": "Fragment de transcriere",
"response.done": "Răspuns terminat",
"error": "Eroare",
}
Gestionarea erorilor
Erorile sunt emise printr-un eveniment de tip error. Trebuie să le interceptați întotdeauna:
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"Eroare [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Eroare de configurare, remediați și reîncercați
pass
elif error["type"] == "server_error":
# Problemă din partea OpenAI, reconectați-vă
pass
elif event_type == "session.updated":
print("Configurație aplicată cu succes")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Tokeni utilizați: {usage}")
Puncte cheie
- O sesiune este creată automat la conectarea WebSocket și distrusă la deconectare
session.updateconfigurează sesiunea dupăsession.created; așteptațisession.updatedînainte de a vă baza pe noua configurație- Pentru a transcrie inputul într-o sesiune de conversație, folosiți
gpt-transcribe;gpt-live-transcribeeste rezervat sesiunilor de transcriere - Protocolul este pur bazat pe evenimente: fiecare mesaj are un
typecare determină modul de tratare - Evenimentele client conduc interacțiunea; evenimentele server raportează rezultatele
- Gestionarea erorilor este critică: ascultați întotdeauna evenimentele
error