Architektúra WebSocket rozhrania Realtime API
Na tejto strane
Aktualizované 2. novembra 2026 — Zvukové modely. Niekoľko modelov v tomto kurze je zastaraných:
tts-1,tts-1-hdagpt-4o-mini-ttsprestanú fungovať 6. januára 2027 (náhrada:gpt-realtime-2.1-mini, ktorý podľa sprievodcu OpenAI TTS nie je podporovaný cez/v1/audio/speech: migrácia syntézy reči prechádza na Realtime API);gpt-realtime,gpt-4o-realtimea staršie zvukové modely 20. januára 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translations26. februára 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pre plnohodnotnú obojsmernú hlasovú komunikáciu je GPT-Live 1 dostupné v API od 10. septembra 2026. Doplnok z 3. novembra 2026: sekcia o troch hlasových architektúrach OpenAI (GPT-Live, Realtime API, spracovateľský reťazec) a výbere transportu (WebRTC, WebSocket, SIP) na základe sprievodcov Voice agents, Audio and voice a Getting started with the Realtime API; maximálna dĺžka relácie: 60 minút (Realtime conversations).
Architektúra WebSocket rozhrania Realtime API
Realtime API od OpenAI predstavuje zásadnú zmenu paradigmy v spôsobe, akým interaguješ s jazykovými modelmi. Na rozdiel od tradičných REST API, ktoré fungujú na princípe cyklu požiadavka-odpoveď, Realtime API využíva protokol WebSocket na vytvorenie trvalého, obojsmerného spojenia medzi tvojou aplikáciou a modelom.
Táto architektúra umožňuje výmenu zvuku v reálnom čase: posielaš zvuk, model ho spracuje a hlasovo odpovedá s nízkou latenciou, pričom preskakuje medzikroky ako prepis alebo prevod textu na reč. Toto je jeden zo základných stavebných kameňov konverzačných hlasových agentov a srdcom tohto kurzu.
Tri hlasové architektúry v roku 2026
Pred otvorením WebSocketu si Realtime API zaraď do kontextu spolu s ostatnými riešeniami OpenAI. Sprievodca Voice agents rozlišuje tri prístupy:
| Architektúra | Najvhodnejšie pre | Prečo si ju vybrať |
|---|---|---|
| GPT-Live | Plno duplexné konverzácie so samostatným backendom | Hlasový model počúva počas hovoru a deleguje logické úvahy a použitie nástrojov na backend podľa tvojej voľby; zachováva tvojho existujúceho textového agenta nedotknutého |
| Realtime API | Reč, logické úvahy a nástroje v jednej relácii | Jeden model interpretuje zvuk, rozhoduje, čo robiť, a vysloví odpoveď |
| Spracovateľský reťazec | Granulárna kontrola nad každým krokom | Prepis, potom textový agent, potom syntéza reči: medzi krokmi kontroluješ alebo transformuješ text a každú súčasť môžeš nezávisle vymeniť |
Pre nové aplikácie hlasových konverzácií stránka Audio and voice od OpenAI teraz odporúča začať s GPT-Live. Realtime API zostáva správnym východiskovým bodom, keď sa agent musí zmestiť do jednej relácie, podporovať prerušenie používateľom, rýchlu prvú zvukovú odpoveď, prirodzené striedanie v hovore a priame volania nástrojov. Spracovateľský reťazec funguje najlepšie, keď musí každý krok zostať viditeľný: zachovanie prepisov, vynucovanie pravidiel pred odpoveďou agenta alebo vydanie hlasu až po overení odpovede.
Tento kurz sa zameriava na Realtime API a spracovateľský reťazec, ktorého komponenty (prepis, syntéza reči) sú pokryté v nasledujúcich sekciách.
WebRTC, WebSocket alebo SIP
Tvoja voľba transportu závisí od toho, odkiaľ zvuk pochádza. Podľa dokumentácie: použi WebRTC pre zvuk v prehliadači s jednorazovým klientskym tajomstvom generovaným tvojim serverom; WebSocket pre serverové zvukové pipeline; SIP pre telefónne hovory. Riadiace spojenie na strane servera tiež umožňuje dôveryhodnému backendu sledovať a usmerňovať mediálnu reláciu. Táto lekcia podrobne popisuje WebSocket, čo je najjednoduchší spôsob, ako pochopiť vymieňané udalosti; v prehliadači uprednostni WebRTC. Relácia Realtime trvá maximálne 60 minút.
WebSocket vs. REST: Prečo táto voľba?
V tradičnej architektúre REST si každá interakcia vyžaduje kompletnú HTTP požiadavku: otvorenie TCP spojenia, vyjednanie TLS, odoslanie hlavičiek, čakanie na odpoveď a uzavretie spojenia. Pre zvuk v reálnom čase je táto réžia neúnosná.
| Kritérium | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Latencia | 200–500 ms na požiadavku | < 50 ms po pripojení |
| Smer | Iba klient → server | Súčasné obojsmerné |
| Spojenie | Nové pre každú požiadavku | Trvalé (relácia) |
| Zvuk | Vyžaduje sa celý súbor | Streamovanie po častiach |
Protokol WebSocket udržuje kanál neustále otvorený. Po nadviazaní môžu klient aj server odosielať správy kedykoľvek bez čakania, kým druhá strana dokončí svoju činnosť.
Nadviazanie spojenia WebSocket
Tu je návod, ako nadviazať spojenie s Realtime API v Pythone:
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")
# Prijatie uvítacej udalosti
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Udržanie spojenia otvoreného
await asyncio.Future()
asyncio.run(connect_realtime())
URL spojenia obsahuje model ako parameter dopytu. Od chvíle, keď sa API stalo všeobecne dostupným, sa vyžaduje iba hlavička overenia – hlavička OpenAI-Beta: realtime=v1 z fázy beta už nie je potrebná.
Rozhranie zaznamenané 5. augusta 2026 — Realtime API sa vyvíja (modely, názvy udalostí, formát relácie): v prípade pochybností si over oficiálnu dokumentáciu.
Architektúra aplikácie Realtime
Aplikácia využívajúca Realtime API nasleduje vrstvenú architektúru:
Zvuková vrstva (zachytávanie/prehrávanie)
Zachytáva mikrofón, prehráva zvukové odpovede. Využíva PyAudio, sounddevice alebo Web Audio API v prehliadači.
Vrstva WebSocket (transport)
Spravuje trvalé spojenie, kóduje/dekóduje JSON udalosti, rieši opätovné pripájanie.
Aplikačná vrstva (obchodná logika)
Orchestruje konverzáciu, spravuje kontext, volá nástroje, spracováva výsledky.
Serverová vrstva (voliteľný proxy)
V produkčnom prostredí sprostredkujúci server chráni API kľúč a pridáva obchodnú logiku na strane servera.
Úloha proxy servera
Počas vývoja sa môžeš pripojiť priamo k Realtime API. V produkčnom prostredí je proxy server nevyhnutný na:
- Ochranu tvojho API kľúča – nikdy ho nezverejňuj na strane klienta
- Overenie používateľov – skontroluj tokeny pred otvorením relácie
- Kontrolu nákladov – obmedz dĺžku relácie a využitie tokenov
- Logovanie interakcií – pre ladenie a dodržiavanie predpisov
# Zjednodušený príklad WebSocket proxy s 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())
Kľúčové poznatky
- Tri hlasové architektúry v OpenAI: GPT-Live (odporúčané pre nové konverzačné aplikácie), Realtime API (reč, logické úvahy a nástroje v jednej relácii) a reťazec prepis → agent → syntéza
- WebRTC pre zvuk v prehliadači, WebSocket pre serverové pipeline, SIP pre telefóniu; relácie trvajú maximálne 60 minút
- Realtime API využíva WebSocket pre obojsmernú komunikáciu s nízkou latenciou
- Spojenie je trvalé: jedno otvorenie pre celú konverzačnú reláciu
- Vrstvená architektúra oddeľuje zvuk, transport, obchodnú logiku a serverový proxy
- V produkčnom prostredí je proxy server nevyhnutný pre bezpečnosť a kontrolu nákladov
- Protokol je riadený udalosťami: každá správa je objekt JSON s poľom
type