Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Architektura WebSocket rozhraní Realtime API

Lekce 1 z 18 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Architektura WebSocket rozhraní Realtime API
  2. Tři hlasové architektury v roce 2026
  3. WebRTC, WebSocket nebo SIP
  4. WebSocket vs. REST: Proč tato volba?
  5. Navázání spojení WebSocket
  6. Architektura aplikace Realtime
  7. Klíčové poznatky

Aktualizováno 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých: tts-1, tts-1-hd a gpt-4o-mini-tts př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-realtime a starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations skončí 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:

ArchitekturaNejvhodnější proProč ji zvolit
GPT-LivePlně duplexní konverzace se samostatným backendemHlasový 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é relaciJediný model interpretuje zvuk, rozhoduje, co dělat, a vysloví odpověď
Zpracovatelský řetězecGranulární kontrola nad každým krokemPř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.

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:

1

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.

2

Vrstva WebSocket (transport)

Spravuje trvalé spojení, kóduje/dekóduje události JSON a řeší opětovná připojení.

3

Aplikační vrstva (obchodní logika)

Orchestruje konverzaci, spravuje kontext, volá nástroje a zpracovává výsledky.

4

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