Sesije, događaji i životni ciklus
Na ovoj stranici
Ažurirano 2. studenoga 2026. — Zvučni modeli. Nekoliko modela u ovom tečaju je zastarjelo:
tts-1,tts-1-hdigpt-4o-mini-ttsprestat će raditi 6. siječnja 2027. (zamjena:gpt-realtime-2.1-mini, za koji OpenAI TTS vodič navodi da nije podržan putem/v1/audio/speech: migracija sinteze govora prelazi na Realtime API);gpt-realtime,gpt-4o-realtimei stariji zvučni modeli 20. siječnja 2027. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribei/v1/audio/translations26. veljače 2027. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Za full-duplex glas, GPT-Live 1 dostupan je u API-ju od 10. rujna 2026.
Ispravljeno 3. studenoga 2026. Transkripcija ulaza koristila je
gpt-live-transcribe, koji radi samo u sesiji za transkripciju i ne podržava niserver_vadnisemantic_vad. U sesiji razgovora poput ove, gdje VAD validira svaki okret, dokumentacija specificiragpt-transcribe, koji transkribira validirane okrete i koristi prethodne okrete kao kontekst. Izvori: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Sesije, događaji i životni ciklus
Svaka WebSocket veza s Realtime API-jem stvara sesiju. Ta sesija predstavlja temeljnu jedinicu upravljanja: obuhvaća konfiguraciju modela, povijest razgovora, dostupne alate i trenutno stanje interakcije. Razumijevanje njezinog životnog ciklusa ključno je za izgradnju pouzdanih glasovnih agenata.
Životni ciklus sesije
Čim se uspostavi WebSocket veza, poslužitelj emitira događaj session.created. Sesija prolazi kroz nekoliko faza:
Veza → session.created
Poslužitelj potvrđuje sesiju jedinstvenim ID-om i zadanom konfiguracijom.
Konfiguracija → session.update
Šalješ session.update kako bi definirao upute, glas, alate i modalitete.
Aktivni razgovor
Razmjena audio i tekstualnih događaja između klijenta i poslužitelja.
Zatvaranje → WebSocket disconnect
Sesija se uništava kada se veza prekine. Na poslužitelju se ne zadržava nikakvo stanje.
Konfiguriranje sesije
Nakon session.created, pošalji događaj session.update kako bi konfigurirao ponašanje modela. Transkripcija onoga što korisnik govori (audio.input.transcription) opcionalna je: bez nje primaš glas, ali ne i tekst. languages specificira očekivane jezike i poboljšava 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:
# Čekaj session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfiguriraj sesiju
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": []
}
}))
# Čekaj potvrdu (ostali događaji mogu stići prvi)
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 sesije
| Parametar | Opis | Preporučena vrijednost |
|---|---|---|
| output_modalities | Izlazni modaliteti | ["audio"] (ili ["text"]) |
| audio.output.voice | Glas za sintezu | marin, cedar, alloy, echo, itd. |
| audio.input.turn_detection | Otkrivanje kraja govora | server_vad s pragom 0.5 |
| audio.input.format | Format dolaznog zvuka | {"type": "audio/pcm", "rate": 24000} |
Sustav događaja
Realtime API u potpunosti je vođen događajima. Svaka razmijenjena poruka JSON je objekt s poljem type koje određuje njezinu prirodu. Događaji spadaju u dvije kategorije:
Događaji klijenta (ti → poslužitelj)
# Glavni događaji koje šalješ
client_events = {
"session.update": "Izmijeni konfiguraciju",
"input_audio_buffer.append": "Pošalji dio zvuka",
"input_audio_buffer.commit": "Potvrdi audio međuspremnik",
"input_audio_buffer.clear": "Očisti audio međuspremnik",
"conversation.item.create": "Ručno dodaj poruku",
"conversation.item.truncate": "Skrati odgovor",
"conversation.item.delete": "Izbriši poruku",
"response.create": "Pokreni odgovor",
"response.cancel": "Otkaži trenutni odgovor",
}
Događaji poslužitelja (poslužitelj → ti)
# Glavni događaji koje primaš
server_events = {
"session.created": "Sesija inicijalizirana",
"session.updated": "Konfiguracija primijenjena",
"input_audio_buffer.speech_started": "Govor otkriven",
"input_audio_buffer.speech_stopped": "Tišina otkrivena",
"conversation.item.created": "Nova poruka u povijesti",
"response.created": "Generiranje započeto",
"response.output_audio.delta": "Dio audio odgovora",
"response.output_audio_transcript.delta": "Dio transkripcije",
"response.done": "Odgovor završen",
"error": "Greška",
}
Rukovanje greškama
Greške se emitiraju putem događaja tipa error. Uvijek ih moraš presresti:
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":
# Greška u konfiguraciji, popravi i pokušaj ponovno
pass
elif error["type"] == "server_error":
# Problem na strani OpenAI-ja, ponovno se poveži
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 točke
- Sesija se automatski stvara pri uspostavi WebSocket veze i uništava pri prekidu veze
session.updatekonfigurira sesiju nakonsession.created; pričekajsession.updatedprije oslanjanja na novu konfiguraciju- Za transkripciju ulaza u sesiji razgovora koristi
gpt-transcribe;gpt-live-transcriberezerviran je za sesije transkripcije - Protokol je isključivo vođen događajima: svaka poruka ima
typekoji određuje način rukovanja - Događaji klijenta pokreću interakciju; događaji poslužitelja izvještavaju o rezultatima
- Rukovanje greškama je ključno: uvijek slušaj događaje
error