Relace, události a životní cyklus
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 endpointem/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í hlas je GPT-Live 1 dostupné v API od 10. září 2026.
Opraveno 3. listopadu 2026. Přepis vstupu používal
gpt-live-transcribe, který funguje pouze v relaci typu transcription a nepodporuje aniserver_vad, anisemantic_vad. V konverzační relaci, jako je tato, kde VAD validuje každý obrat, dokumentace specifikuje použitígpt-transcribe, který přepisuje validované obraty a využívá předchozí obraty jako kontext. Zdroje: Přepis v reálném čase · GPT-Transcribe · GPT-Live-Transcribe.
Relace, události a životní cyklus
Každé připojení WebSocket k Realtime API vytvoří relaci. Tato relace je základní jednotkou správy: zapouzdřuje konfiguraci modelu, historii konverzace, dostupné nástroje a aktuální stav interakce. Porozumění jejímu životnímu cyklu je zásadní pro budování spolehlivých hlasových agentů.
Životní cyklus relace
Jakmile je navázáno připojení WebSocket, server vyšle událost session.created. Relace prochází několika fázemi:
Připojení → session.created
Server potvrdí relaci jedinečným ID a výchozí konfigurací.
Konfigurace → session.update
Odešleš session.update pro definování pokynů, hlasu, nástrojů a modalit.
Aktivní konverzace
Výměna zvukových a textových událostí mezi klientem a serverem.
Ukončení → odpojení WebSocket
Relace je zničena při uzavření připojení. Na serveru nezůstává žádný stav.
Konfigurace relace
Po události session.created odešli událost session.update pro nastavení chování modelu. Přepis toho, co uživatel říká (audio.input.transcription), je volitelný: bez něj obdržíš hlas, ale ne text. Parametr languages určuje očekávané jazyky a zlepšuje rozpoznávání:
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:
# Počkej na session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Relace vytvořena: {session_id}")
# Nakonfiguruj relaci
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Jsi hlasový asistent mluvící francouzsky. "
"Odpovídej stručně a přirozeně.",
"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": []
}
}))
# Počkej na potvrzení (nejdříve mohou přijít jiné události)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Relace aktualizována")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Klíčové parametry relace
| Parametr | Popis | Doporučená hodnota |
|---|---|---|
| output_modalities | Výstupní modality | ["audio"] (nebo ["text"]) |
| audio.output.voice | Hlas syntézy | marin, cedar, alloy, echo atd. |
| audio.input.turn_detection | Detekce konce řeči | server_vad s prahem 0.5 |
| audio.input.format | Formát příchozího zvuku | {"type": "audio/pcm", "rate": 24000} |
Systém událostí
Realtime API je zcela řízeno událostmi. Každá vyměněná zpráva je objekt JSON s polem type, které určuje její povahu. Události spadají do dvou kategorií:
Události klienta (ty → server)
# Hlavní události, které odesíláš
client_events = {
"session.update": "Úprava konfigurace",
"input_audio_buffer.append": "Odeslání části zvuku",
"input_audio_buffer.commit": "Potvrzení zvukové vyrovnávací paměti",
"input_audio_buffer.clear": "Vyčištění zvukové vyrovnávací paměti",
"conversation.item.create": "Ruční přidání zprávy",
"conversation.item.truncate": "Zkrácení odpovědi",
"conversation.item.delete": "Smazání zprávy",
"response.create": "Spuštění odpovědi",
"response.cancel": "Zrušení aktuální odpovědi",
}
Události serveru (server → ty)
# Hlavní události, které přijímáš
server_events = {
"session.created": "Relace inicializována",
"session.updated": "Konfigurace aplikována",
"input_audio_buffer.speech_started": "Detekována řeč",
"input_audio_buffer.speech_stopped": "Detekováno ticho",
"conversation.item.created": "Nová zpráva v historii",
"response.created": "Generování zahájeno",
"response.output_audio.delta": "Část odpovědi ve zvuku",
"response.output_audio_transcript.delta": "Část přepisu",
"response.done": "Odpověď dokončena",
"error": "Chyba",
}
Zpracování chyb
Chyby jsou vysílány prostřednictvím události typu error. Vždy je musíš zachytit:
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"Chyba [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Chyba konfigurace, oprav a zkus znovu
pass
elif error["type"] == "server_error":
# Problém na straně OpenAI, znovu se připoj
pass
elif event_type == "session.updated":
print("Konfigurace úspěšně aplikována")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Použité tokeny: {usage}")
Klíčové poznatky
- Relace se vytvoří automaticky při připojení WebSocket a zničí se při odpojení.
session.updatekonfiguruje relaci posession.created; před použitím nové konfigurace počkej nasession.updated.- Pro přepis vstupu v konverzační relaci použij
gpt-transcribe;gpt-live-transcribeje vyhrazen pro relace typu transcription. - Protokol je čistě event-driven: každá zpráva má
type, který určuje její zpracování. - Události klienta řídí interakci; události serveru hlásí výsledky.
- Zpracování chyb je kritické: vždy naslouchej událostem
error.