Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Sesije, događaji i životni ciklus

Lekcija 2 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Sesije, događaji i životni ciklus
  2. Životni ciklus sesije
  3. Konfiguriranje sesije
  4. Sustav događaja
  5. Rukovanje greškama
  6. Ključne točke

Ažurirano 2. studenoga 2026. — Zvučni modeli. Nekoliko modela u ovom tečaju je zastarjelo: tts-1, tts-1-hd i gpt-4o-mini-tts prestat ć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-realtime i 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-transcribe i /v1/audio/translations 26. 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 ni server_vad ni semantic_vad. U sesiji razgovora poput ove, gdje VAD validira svaki okret, dokumentacija specificira gpt-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:

1

Veza → session.created

Poslužitelj potvrđuje sesiju jedinstvenim ID-om i zadanom konfiguracijom.

2

Konfiguracija → session.update

Šalješ session.update kako bi definirao upute, glas, alate i modalitete.

3

Aktivni razgovor

Razmjena audio i tekstualnih događaja između klijenta i poslužitelja.

4

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.update konfigurira sesiju nakon session.created; pričekaj session.updated prije oslanjanja na novu konfiguraciju
  • Za transkripciju ulaza u sesiji razgovora koristi gpt-transcribe; gpt-live-transcribe rezerviran je za sesije transkripcije
  • Protokol je isključivo vođen događajima: svaka poruka ima type koji 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