WebSocket-architectuur van de Realtime API
Op deze pagina
Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd:
tts-1,tts-1-hdengpt-4o-mini-ttsstoppen op 6 januari 2027 (vervanger:gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door/v1/audio/speech: migratie van spraaksynthese gaat 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. Addendum 3 november 2026: sectie over OpenAI’s drie spraakarchitecturen (GPT-Live, Realtime API, verwerkingsketen) en transportkeuze (WebRTC, WebSocket, SIP), gebaseerd op de gidsen Voice agents, Audio en spraak en Aan de slag met de Realtime API; maximale sessieduur: 60 minuten (Realtime conversations).
WebSocket-architectuur van de Realtime API
OpenAI’s Realtime API vertegenwoordigt een fundamentele paradigmaverschuiving in hoe u met taalmodellen interacteert. In tegenstelling tot traditionele REST-API’s die werken op basis van een request-response-cyclus, gebruikt de Realtime API het WebSocket-protocol om een persistente, bidirectionele verbinding tot stand te brengen tussen uw applicatie en het model.
Deze architectuur maakt realtime audio-uitwisseling mogelijk: u verzendt audio, het model verwerkt dit en reageert vocaal met lage latentie, waarbij tussenliggende transcriptie- of tekst-naar-spraak-stappen worden overgeslagen. Dit is een van de kernbouwstenen voor conversationele voice agents en het hart van deze cursus.
Drie spraakarchitecturen in 2026
Voordat u een WebSocket opent, plaatst u de Realtime API in de context van OpenAI’s andere oplossingen. De gids Voice agents onderscheidt drie benaderingen:
| Architectuur | Het beste voor | Waarom kiezen? |
|---|---|---|
| GPT-Live | Full-duplex gesprekken met een aparte backend | Het spraakmodel luistert terwijl het spreekt en delegeert redeneren en toolgebruik aan een backend naar keuze; houdt uw bestaande tekstagent intact |
| Realtime API | Spraak, redeneren en tools in één sessie | Eén model interpreteert audio, beslist wat te doen en spreekt het antwoord uit |
| Verwerkingsketen | Granulaire controle over elke stap | Transcriptie, dan tekstagent, dan spraaksynthese: u inspecteert of transformeert tekst tussen stappen en wisselt elk component onafhankelijk uit |
Voor nieuwe voice-conversatieapplicaties raadt OpenAI’s pagina Audio en spraak nu aan om te beginnen met GPT-Live. De Realtime API blijft het juiste startpunt wanneer de agent binnen één sessie moet passen, met ondersteuning voor onderbreking door de gebruiker, snelle eerste audiorespons, natuurlijke beurtwisseling en directe tool-aanroepen. De verwerkingsketen werkt het beste wanneer elke stap zichtbaar moet blijven: transcripties behouden, regels afdwingen voordat de agent antwoordt, of spraak pas uitzenden na validatie van het antwoord.
Deze cursus focust op de Realtime API en de verwerkingsketen, waarvan de componenten (transcriptie, spraaksynthese) in volgende secties aan bod komen.
WebRTC, WebSocket of SIP
Uw transportkeuze hangt af van waar de audio vandaan komt. Volgens de documentatie: gebruik WebRTC voor browseraudio, met een ephemeraal clientgeheim gegenereerd door uw server; WebSocket voor server-side audiopipelines; SIP voor telefoongesprekken. Een server-side controleverbinding stelt een vertrouwde backend ook in staat om een mediasessie te observeren en te sturen. Deze les behandelt WebSocket, de eenvoudigste manier om uitgewisselde events te begrijpen; in een browser geeft u de voorkeur aan WebRTC. Een Realtime-sessie duurt maximaal 60 minuten.
WebSocket versus REST: waarom deze keuze?
In een traditionele REST-architectuur vereist elke interactie een compleet HTTP-verzoek: een TCP-verbinding openen, TLS-onderhandeling, headers verzenden, wachten op het antwoord en de verbinding sluiten. Voor realtime audio is deze overhead prohibitief.
| Criterium | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Latentie | 200–500 ms per verzoek | < 50 ms na verbinding |
| Richting | Alleen client → server | Gelijktijdig bidirectioneel |
| Verbinding | Nieuw voor elk verzoek | Persistent (sessie) |
| Audio | Volledig bestand vereist | Chunk-per-chunk streaming |
Het WebSocket-protocol houdt een kanaal continu open. Eenmaal tot stand gebracht, kunnen client en server op elk moment berichten verzenden zonder te wachten tot de ander klaar is.
Een WebSocket-verbinding tot stand brengen
Zo bouwt u een verbinding op met de Realtime API 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())
De verbindings-URL bevat het model als query-parameter. Sinds de API algemeen beschikbaar is, is alleen de authenticatie-header vereist; de OpenAI-Beta: realtime=v1-header uit de bètafase is verdwenen.
Interface opgemerkt op 5 augustus 2026 — De Realtime API evolueert (modellen, event-namen, sessie-indeling): raadpleeg bij twijfel de officiële documentatie.
Architectuur van een Realtime-applicatie
Een applicatie die de Realtime API gebruikt, volgt een gelaagde architectuur:
Audiolaag (capture/playback)
Legt de microfoon vast, speelt audio-antwoorden af. Gebruikt PyAudio, sounddevice of de Web Audio API in de browser.
WebSocket-laag (transport)
Beheert de persistente verbinding, codeert/decodeert JSON-events, handelt herverbindingen af.
Applicatielaag (business logic)
Orchestreert het gesprek, beheert context, roept tools aan, verwerkt resultaten.
Serverlaag (optionele proxy)
In productie beschermt een tussenliggende server de API-sleutel en voegt server-side business logic toe.
De rol van de proxyserver
Tijdens ontwikkeling kunt u uw applicatie direct verbinden met de Realtime API. In productie is een proxyserver essentieel om:
- Uw API-sleutel te beschermen — exposeer deze nooit aan de clientkant
- Uw gebruikers te authenticeren — verifieer tokens voordat u de sessie opent
- Kosten te beheersen — beperk sessieduur en tokengebruik
- Interacties te loggen — voor debugging en compliance
# 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())
Belangrijkste punten
- Drie spraakarchitecturen bij OpenAI: GPT-Live (aanbevolen voor nieuwe conversatie-apps), Realtime API (spraak, redeneren en tools in één sessie) en de keten transcriptie → agent → synthese
- WebRTC voor browseraudio, WebSocket voor server-pipelines, SIP voor telefonie; sessies duren maximaal 60 minuten
- Realtime API gebruikt WebSocket voor bidirectionele communicatie met lage latentie
- De verbinding is persistent: één opening voor de hele conversatiesessie
- Gelaagde architectuur scheidt audio, transport, business logic en server-proxy
- In productie is een proxyserver essentieel voor beveiliging en kostenbeheersing
- Het protocol is event-driven: elk bericht is een JSON-object met een
type-veld