Sessies, gebeurtenissen en levenscyclus
Op deze pagina
Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd:
tts-1,tts-1-hdengpt-4o-mini-ttsstoppen met werken op 6 januari 2027 (vervanging:gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door/v1/audio/speech: migratie van spraaksynthese verschuift naar de Realtime API);gpt-realtime,gpt-4o-realtimeen legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeen/v1/audio/translationsop 26 februari 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026.
Gecorrigeerd op 3 november 2026. Input-transcriptie gebruikte
gpt-live-transcribe, wat alleen werkt in een transcriptie-sessie en nochserver_vadnochsemantic_vadondersteunt. In een conversatiesessie zoals deze, waar VAD elke beurt valideert, specificeert de documentatiegpt-transcribe, dat gevalideerde beurten transcribeert en eerdere beurten als context gebruikt. Bronnen: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Sessies, gebeurtenissen en levenscyclus
Elke WebSocket-verbinding met de Realtime API creëert een sessie. Deze sessie is de fundamentele beheerseenheid: deze kapselt de modelconfiguratie, de conversatiegeschiedenis, beschikbare tools en de huidige staat van de interactie in. Inzicht in de levenscyclus hiervan is essentieel voor het bouwen van robuuste spraakagenten.
De levenscyclus van een sessie
Zodra de WebSocket-verbinding tot stand is gebracht, zendt de server een session.created-gebeurtenis uit. De sessie doorloopt verschillende fasen:
Verbinding → session.created
De server bevestigt de sessie met een unieke ID en standaardconfiguratie.
Configuratie → session.update
U verzendt session.update om instructies, stem, tools en modaliteiten te definiëren.
Actieve conversatie
Uitwisseling van audio- en tekstgebeurtenissen tussen client en server.
Afsluiting → WebSocket disconnect
De sessie wordt vernietigd wanneer de verbinding sluit. Er wordt geen staat op de server bewaard.
Een sessie configureren
Na session.created verzendt u een session.update-gebeurtenis om het gedrag van het model te configureren. Het transcriberen van wat de gebruiker zegt (audio.input.transcription) is optioneel: zonder dit ontvangt u de stem maar niet de tekst. languages specificeert de verwachte talen en verbetert de herkenning:
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:
# Wacht op session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Configureer de sessie
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a French-speaking voice assistant. "
"Respond concisely and naturally.",
"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": []
}
}))
# Wacht op bevestiging (andere gebeurtenissen kunnen eerder arriveren)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Session updated")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Belangrijke sessieparameters
| Parameter | Beschrijving | Aanbevolen waarde |
|---|---|---|
| output_modalities | Uitvoermodaliteiten | ["audio"] (of ["text"]) |
| audio.output.voice | Synthesestem | marin, cedar, alloy, echo, enz. |
| audio.input.turn_detection | Detectie einde spraak | server_vad met drempelwaarde 0.5 |
| audio.input.format | Formaat binnenkomende audio | {"type": "audio/pcm", "rate": 24000} |
Het gebeurtenissysteem
De Realtime API is volledig event-driven. Elk uitgewisseld bericht is een JSON-object met een type-veld dat de aard ervan bepaalt. Gebeurtenissen vallen in twee categorieën:
Clientgebeurtenissen (u → server)
# De belangrijkste gebeurtenissen die u verzendt
client_events = {
"session.update": "Configuratie wijzigen",
"input_audio_buffer.append": "Een audiofragment verzenden",
"input_audio_buffer.commit": "De audiobuffer committen",
"input_audio_buffer.clear": "De audiobuffer wissen",
"conversation.item.create": "Handmatig een bericht toevoegen",
"conversation.item.truncate": "Een antwoord inkorten",
"conversation.item.delete": "Een bericht verwijderen",
"response.create": "Een antwoord triggeren",
"response.cancel": "Het huidige antwoord annuleren",
}
Servergebeurtenissen (server → u)
# De belangrijkste gebeurtenissen die u ontvangt
server_events = {
"session.created": "Sessie geïnitialiseerd",
"session.updated": "Configuratie toegepast",
"input_audio_buffer.speech_started": "Spraak gedetecteerd",
"input_audio_buffer.speech_stopped": "Stilte gedetecteerd",
"conversation.item.created": "Nieuw bericht in geschiedenis",
"response.created": "Generatie gestart",
"response.output_audio.delta": "Audiofragment van antwoord",
"response.output_audio_transcript.delta": "Transcriptiefragment",
"response.done": "Antwoord voltooid",
"error": "Fout",
}
Foutafhandeling
Fouten worden uitgezonden via een gebeurtenis van het type error. U moet deze altijd onderscheppen:
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"Fout [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Configuratiefout, herstellen en opnieuw proberen
pass
elif error["type"] == "server_error":
# Probleem aan de kant van OpenAI, opnieuw verbinden
pass
elif event_type == "session.updated":
print("Configuratie succesvol toegepast")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Gebruikte tokens: {usage}")
Belangrijkste punten
- Een sessie wordt automatisch gemaakt bij het tot stand brengen van de WebSocket-verbinding en vernietigd bij het verbreken ervan
session.updateconfigureert de sessie nasession.created; wacht opsession.updatedvoordat u vertrouwt op de nieuwe configuratie- Gebruik voor het transcriberen van input in een conversatiesessie
gpt-transcribe;gpt-live-transcribeis gereserveerd voor transcriptiesessies - Het protocol is puur event-driven: elk bericht heeft een
typedat de verwerking bepaalt - Clientgebeurtenissen sturen de interactie aan; servergebeurtenissen rapporteren resultaten
- Foutafhandeling is cruciaal: luister altijd naar
error-gebeurtenissen