Architektura WebSocket rozhraní Realtime API
Na této stránce
Aktualizováno 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých:
tts-1,tts-1-hdagpt-4o-mini-ttspřestanou fungovat 6. ledna 2027 (náhrada:gpt-realtime-2.1-mini, který podle průvodce OpenAI TTS není podporován koncovým bodem/v1/audio/speech: migrace syntézy řeči přechází na Realtime API);gpt-realtime,gpt-4o-realtimea starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translationsskončí 26. února 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pro plně duplexní hlasovou komunikaci je GPT-Live 1 dostupné v API od 10. září 2026. Dodatek ze 3. listopadu 2026: sekce o třech hlasových architekturách OpenAI (GPT-Live, Realtime API, zpracovatelský řetězec) a výběru transportu (WebRTC, WebSocket, SIP) na základě průvodců Voice agents, Audio and voice a Getting started with the Realtime API; maximální délka relace: 60 minut (Realtime conversations).
Architektura WebSocket rozhraní Realtime API
Realtime API od OpenAI představuje zásadní změnu paradigmatu v tom, jak interaguješ s jazykovými modely. Na rozdíl od tradičních REST API, která fungují na principu cyklu požadavek–odpověď, využívá Realtime API protokol WebSocket k vytvoření trvalého obousměrného spojení mezi tvou aplikací a modelem.
Tato architektura umožňuje výměnu zvuku v reálném čase: odešleš zvuk, model jej zpracuje a hlasově odpoví s nízkou latencí, přičemž přeskočí mezilehlé kroky přepisu nebo převodu textu na řeč. Je to jeden ze základních stavebních kamenů konverzačních hlasových agentů a srdce tohoto kurzu.
Tři hlasové architektury v roce 2026
Než otevřeš WebSocket, je důležité zasadit Realtime API do kontextu alongside dalších řešení OpenAI. Průvodce Voice agents rozlišuje tři přístupy:
| Architektura | Nejvhodnější pro | Proč ji zvolit |
|---|---|---|
| GPT-Live | Plně duplexní konverzace se samostatným backendem | Hlasový model naslouchá i během mluvení a deleguje logické úvahy a používání nástrojů na backend dle tvé volby; zachovává tvého stávajícího textového agenta nedotčeného |
| Realtime API | Řeč, logické úvahy a nástroje v jedné relaci | Jediný model interpretuje zvuk, rozhoduje, co dělat, a vysloví odpověď |
| Zpracovatelský řetězec | Granulární kontrola nad každým krokem | Přepis, poté textový agent, poté syntéza řeči: mezi kroky můžeš kontrolovat nebo transformovat text a každou komponentu nezávisle vyměnit |
Pro nové aplikace hlasových konverzací stránka Audio and voice od OpenAI nyní doporučuje začít s GPT-Live. Realtime API zůstává správným výchozím bodem, když se agent musí vejít do jedné relace, podporovat přerušování uživatelem, rychlou první zvukovou odpověď, přirozené střídání v řeči a přímé volání nástrojů. Zpracovatelský řetězec funguje nejlépe, když musí zůstat viditelný každý krok: uchování přepisů, vynucení pravidel před odpovědí agenta nebo vydání hlasu až po validaci odpovědi.
Tento kurz se zaměřuje na Realtime API a zpracovatelský řetězec, jehož komponenty (přepis, syntéza řeči) jsou pokryty v následujících sekcích.
WebRTC, WebSocket nebo SIP
Volba transportu závisí na tom, odkud zvuk pochází. Podle dokumentace: použij WebRTC pro zvuk v prohlížeči s jednorázovým klientským tajným klíčem generovaným tvým serverem; WebSocket pro serverové zvukové pipeline; SIP pro telefonní hovory. Řídicí spojení na straně serveru také umožňuje důvěryhodnému backendu sledovat a řídit mediální relaci. Tato lekce podrobně popisuje WebSocket, což je nejjednodušší způsob, jak pochopit vyměňované události; v prohlížeči upřednostni WebRTC. Relace Realtime trvá maximálně 60 minut.
WebSocket vs. REST: Proč tato volba?
V tradiční architektuře REST vyžaduje každá interakce kompletní HTTP požadavek: otevření TCP spojení, vyjednávání TLS, odeslání hlaviček, čekání na odpověď a uzavření spojení. Pro zvuk v reálném čase je tato režie nepřijatelná.
| Kritérium | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Latence | 200–500 ms na požadavek | < 50 ms po připojení |
| Směr | Pouze klient → server | Simultánní obousměrný |
| Spojení | Nové pro každý požadavek | Trvalé (relace) |
| Zvuk | Vyžadován celý soubor | Streamování po částech (chunk-by-chunk) |
Protokol WebSocket udržuje kanál neustále otevřený. Jakmile je navázán, mohou klient i server posílat zprávy kdykoli, aniž by museli čekat na dokončení druhé strany.
Navázání spojení WebSocket
Zde je návod, jak navázat spojení s Realtime API v Pythonu:
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())
URL spojení zahrnuje model jako parametr dotazu. Od chvíle, kdy API dosáhlo obecné dostupnosti, je vyžadována pouze autentizační hlavička – hlavička OpenAI-Beta: realtime=v1 z fáze beta již není potřeba.
Rozhraní zaznamenáno 5. srpna 2026 — Realtime API se vyvíjí (modely, názvy událostí, formát relace): v případě pochybností si ověř oficiální dokumentaci.
Architektura aplikace Realtime
Aplikace využívající Realtime API následuje vrstvenou architekturu:
Zvuková vrstva (zachytávání/přehrávání)
Zachytává mikrofon, přehrává zvukové odpovědi. Využívá PyAudio, sounddevice nebo Web Audio API v prohlížeči.
Vrstva WebSocket (transport)
Spravuje trvalé spojení, kóduje/dekóduje události JSON a řeší opětovná připojení.
Aplikační vrstva (obchodní logika)
Orchestruje konverzaci, spravuje kontext, volá nástroje a zpracovává výsledky.
Serverová vrstva (volitelný proxy)
V produkčním prostředí chrání prostřední server API klíč a přidává obchodní logiku na straně serveru.
Role proxy serveru
Během vývoje se můžeš připojit přímo k Realtime API. V produkčním prostředí je však proxy server nezbytný pro:
- Ochranu tvého API klíče – nikdy jej nezveřejňuj na straně klienta
- Autentizaci uživatelů – ověření tokenů před otevřením relace
- Kontrolu nákladů – omezení délky relace a využití tokenů
- Logování interakcí – pro ladění a soulad s předpisy
# Zjednodušený příklad proxy WebSocket 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())
Klíčové poznatky
- Tři hlasové architektury u OpenAI: GPT-Live (doporučeno pro nové konverzační aplikace), Realtime API (řeč, logické úvahy a nástroje v jedné relaci) a řetězec přepis → agent → syntéza
- WebRTC pro zvuk v prohlížeči, WebSocket pro serverové pipeline, SIP pro telefonii; relace trvají maximálně 60 minut
- Realtime API využívá WebSocket pro obousměrnou komunikaci s nízkou latencí
- Spojení je trvalé: jedno otevření pro celou konverzační relaci
- Vrstvená architektura odděluje zvuk, transport, obchodní logiku a serverový proxy
- V produkčním prostředí je proxy server nezbytný pro bezpečnost a kontrolu nákladů
- Protokol je řízen událostmi: každá zpráva je objekt JSON s polem
type