Seje, dogodki in življenjski cikel
Na tej strani
Posodobljeno 2. novembra 2026 — Zvočni modeli. Nekateri modeli v tem tečaju so opuščeni:
tts-1,tts-1-hdingpt-4o-mini-ttsprenehajo delovati 6. januarja 2027 (nadomestilo:gpt-realtime-2.1-mini, ki ga vodnik za OpenAI TTS navaja kot nepodprt s strani/v1/audio/speech: selitev sinteze govora prehaja na Realtime API);gpt-realtime,gpt-4o-realtimein stari zvočni modeli 20. januarja 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribein/v1/audio/translations26. februarja 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Za polno duplexni glas je GPT-Live 1 na voljo v API-ju od 10. septembra 2026.
Popravljeno 3. novembra 2026. Vnosni prepis je uporabljal
gpt-live-transcribe, ki deluje le v seji za prepis in ne podpira nitiserver_vadnitisemantic_vad. V pogovorni seji, kot je ta, kjer VAD potrjuje vsak obrat, dokumentacija določa uporabogpt-transcribe, ki prepisuje potrjene obrate in uporablja prejšnje obrate kot kontekst. Viri: Prepis v realnem času · GPT-Transcribe · GPT-Live-Transcribe.
Seje, dogodki in življenjski cikel
Vsaka povezava WebSocket z Realtime API-jem ustvari sejo. Ta seja je osnovna enota upravljanja: zajema konfiguracijo modela, zgodovino pogovora, razpoložljiva orodja in trenutno stanje interakcije. Razumevanje njenega življenjskega cikla je ključno za gradnjo zanesljivih glasovnih agentov.
Življenjski cikel seje
Takoj ko je vzpostavljena povezava WebSocket, strežnik odda dogodek session.created. Seja prehaja skozi več faz:
Povezava → session.created
Strežnik potrdi sejo z edinstvenim ID-jem in privzeto konfiguracijo.
Konfiguracija → session.update
Pošlješ session.update za določitev navodil, glasu, orodij in modalitet.
Aktivni pogovor
Izmenjava zvočnih in besedilnih dogodkov med odjemalcem in strežnikom.
Zaključek → WebSocket disconnect
Seja se uniči, ko se povezava zapre. Na strežniku ne ostane nobeno stanje.
Konfiguriranje seje
Po dogodku session.created pošlji dogodek session.update za konfiguracijo obnašanja modela. Prepisovanje uporabnikovega govora (audio.input.transcription) je izbirno: brez tega prejmeš glas, ne pa tudi besedila. languages določa pričakovane jezike in izboljša prepoznavanje:
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čakaj na session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfiguriraj sejo
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a French-speaking voice assistant. "
"Respond concisely and naturally.",
"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čakaj na potrditev (najprej lahko prispejo drugi dogodki)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Session updated")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Ključni parametri seje
| Parameter | Opis | Priporočena vrednost |
|---|---|---|
| output_modalities | Izhodne modalitete | ["audio"] (ali ["text"]) |
| audio.output.voice | Glas za sintezo | marin, cedar, alloy, echo itd. |
| audio.input.turn_detection | Zaznavanje konca govora | server_vad s pragom 0.5 |
| audio.input.format | Vhodni zvočni format | {"type": "audio/pcm", "rate": 24000} |
Sistem dogodkov
Realtime API je v celoti usmerjen v dogodke. Vsako izmenjano sporočilo je objekt JSON s poljem type, ki določa njegovo naravo. Dogodki spadajo v dve kategoriji:
Dogodki odjemalca (ti → strežnik)
# Glavni dogodki, ki jih pošlješ
client_events = {
"session.update": "Spremeni konfiguracijo",
"input_audio_buffer.append": "Pošlji zvočni delček",
"input_audio_buffer.commit": "Potrdi zvočni medpomnilnik",
"input_audio_buffer.clear": "Počisti zvočni medpomnilnik",
"conversation.item.create": "Ročno dodaj sporočilo",
"conversation.item.truncate": "Okrajšaj odgovor",
"conversation.item.delete": "Izbriši sporočilo",
"response.create": "Sproži odgovor",
"response.cancel": "Prekliči trenutni odgovor",
}
Dogodki strežnika (strežnik → ti)
# Glavni dogodki, ki jih prejmeš
server_events = {
"session.created": "Seja inicializirana",
"session.updated": "Konfiguracija uporabljena",
"input_audio_buffer.speech_started": "Govor zaznan",
"input_audio_buffer.speech_stopped": "Tišina zaznana",
"conversation.item.created": "Novo sporočilo v zgodovini",
"response.created": "Generiranje začeto",
"response.output_audio.delta": "Zvočni delček odgovora",
"response.output_audio_transcript.delta": "Delček prepisa",
"response.done": "Odgovor končan",
"error": "Napaka",
}
Obravnava napak
Napake se oddajajo prek dogodka tipa error. Vedno jih moraš prestrezati:
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"Error [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Napaka v konfiguraciji, popravi in poskusi znova
pass
elif error["type"] == "server_error":
# Težava na strani OpenAI, ponovna povezava
pass
elif event_type == "session.updated":
print("Configuration applied successfully")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Tokens used: {usage}")
Ključne ugotovitve
- Seja se samodejno ustvari ob vzpostavitvi povezave WebSocket in uniči ob prekinitvi
session.updatekonfigurira sejo posession.created; pred zanašanjem na novo konfiguracijo počakaj nasession.updated- Za prepis vnosa v pogovorni seji uporabi
gpt-transcribe;gpt-live-transcribeje rezerviran za seje za prepis - Protokol je izključno usmerjen v dogodke: vsako sporočilo ima
type, ki določa njegovo obravnavo - Dogodki odjemalca poganjajo interakcijo; dogodki strežnika poročajo o rezultatih
- Obravnava napak je ključna: vedno poslušaj dogodke
error