Relácie, udalosti a životný cyklus
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ú duplexnú hlasovú komunikáciu je GPT-Live 1 dostupné v API od 10. septembra 2026.
Opravené 3. novembra 2026. Prepis vstupného zvuku používal
gpt-live-transcribe, ktorý funguje iba v relácii typu transcription a nepodporuje aniserver_vad, anisemantic_vad. V konverzačnej relácii, ako je táto, kde VAD validuje každý obrat, dokumentácia špecifikuje použitiegpt-transcribe, ktorý prepisuje validované obraty a využíva predchádzajúce obraty ako kontext. Zdroje: Prepis v reálnom čase · GPT-Transcribe · GPT-Live-Transcribe.
Relácie, udalosti a životný cyklus
Každé pripojenie WebSocket k Realtime API vytvára reláciu. Táto relácia je základnou jednotkou správy: zapuzdruje konfiguráciu modelu, históriu konverzácie, dostupné nástroje a aktuálny stav interakcie. Pochopenie jej životného cyklu je nevyhnutné pre budovanie robustných hlasových agentov.
Životný cyklus relácie
Akonáhle sa nadviaže pripojenie WebSocket, server vyšle udalosť session.created. Relácia prechádza niekoľkými fázami:
Pripojenie → session.created
Server potvrdí reláciu jedinečným ID a predvolenou konfiguráciou.
Konfigurácia → session.update
Odošleš session.update na definovanie inštrukcií, hlasu, nástrojov a modalít.
Aktívna konverzácia
Výmena zvukových a textových udalostí medzi klientom a serverom.
Ukončenie → odpojenie WebSocket
Relácia sa zničí po uzavretí pripojenia. Na serveri sa neuchováva žiadny stav.
Konfigurácia relácie
Po udalosti session.created odošli udalosť session.update na nastavenie správania modelu. Prepis toho, čo používateľ hovorí (audio.input.transcription), je voliteľný: bez neho dostaneš hlas, ale nie text. Parameter languages špecifikuje očakávané jazyky a zlepšuje rozpoznávanie:
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čkaj na session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Relácia vytvorená: {session_id}")
# Nakonfiguruj reláciu
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Si hlasový asistent hovoriaci po francúzsky. "
"Odpovedaj stručne a prirodzene.",
"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čkaj na potvrdenie (najprv môžu prísť iné udalosti)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Relácia aktualizovaná")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Kľúčové parametre relácie
| Parameter | Popis | Odporúčaná hodnota |
|---|---|---|
| output_modalities | Výstupné modality | ["audio"] (alebo ["text"]) |
| audio.output.voice | Hlas syntézy | marin, cedar, alloy, echo atď. |
| audio.input.turn_detection | Detekcia konca reči | server_vad s prahom 0.5 |
| audio.input.format | Formát prichádzajúceho zvuku | {"type": "audio/pcm", "rate": 24000} |
Systém udalostí
Realtime API je úplne riadené udalosťami. Každá vymenená správa je objekt JSON s poľom type, ktoré určuje jej povahu. Udalosti spadajú do dvoch kategórií:
Udalosti klienta (ty → server)
# Hlavné udalosti, ktoré odosielaš
client_events = {
"session.update": "Úprava konfigurácie",
"input_audio_buffer.append": "Odoslanie časti zvuku",
"input_audio_buffer.commit": "Potvrdenie zvukovej vyrovnávacej pamäte",
"input_audio_buffer.clear": "Vyčistenie zvukovej vyrovnávacej pamäte",
"conversation.item.create": "Manuálne pridanie správy",
"conversation.item.truncate": "Skrátenie odpovede",
"conversation.item.delete": "Vymazanie správy",
"response.create": "Spustenie odpovede",
"response.cancel": "Zrušenie aktuálnej odpovede",
}
Udalosti servera (server → ty)
# Hlavné udalosti, ktoré dostávaš
server_events = {
"session.created": "Relácia inicializovaná",
"session.updated": "Konfigurácia aplikovaná",
"input_audio_buffer.speech_started": "Zistená reč",
"input_audio_buffer.speech_stopped": "Zistené ticho",
"conversation.item.created": "Nová správa v histórii",
"response.created": "Generovanie začalo",
"response.output_audio.delta": "Časť zvuku odpovede",
"response.output_audio_transcript.delta": "Časť prepisu",
"response.done": "Odpoveď dokončená",
"error": "Chyba",
}
Spracovanie chýb
Chyby sa vysielať prostredníctvom udalosti typu error. Vždy ich musíš zachytiť:
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 konfigurácie, oprav a skús znova
pass
elif error["type"] == "server_error":
# Problém na strane OpenAI, znovu sa pripoj
pass
elif event_type == "session.updated":
print("Konfigurácia úspešne aplikovaná")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Použité tokeny: {usage}")
Kľúčové poznatky
- Relácia sa vytvorí automaticky pri pripojení WebSocket a zničí sa pri odpojení
session.updatekonfiguruje reláciu posession.created; pred použitím novej konfigurácie počkaj nasession.updated- Na prepis vstupu v konverzačnej relácii použij
gpt-transcribe;gpt-live-transcribeje vyhradený pre relácie typu transcription - Protokol je čisto riadený udalosťami: každá správa má
type, ktorý určuje jej spracovanie - Udalosti klienta riadia interakciu; udalosti servera hlásia výsledky
- Spracovanie chýb je kritické: vždy počúvaj na udalosti
error