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

Arhitektura WebSocketa za Realtime API

Lekcija 1 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Arhitektura WebSocketa za Realtime API
  2. Tri glasovne arhitekture u 2026.
  3. WebRTC, WebSocket ili SIP
  4. WebSocket naspram REST-a: Zašto taj izbor?
  5. Uspostava WebSocket veze
  6. Arhitektura Realtime aplikacije
  7. Ključne točke

Ažurirano 2. studenoga 2026. — Audio 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 od strane /v1/audio/speech: migracija sinteze govora prelazi na Realtime API); gpt-realtime, gpt-4o-realtime i stariji audio 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. Dodatak 3. studenoga 2026.: odjeljak o tri OpenAI-jeve glasovne arhitekture (GPT-Live, Realtime API, lanac obrade) i odabiru transporta (WebRTC, WebSocket, SIP), temeljeno na vodičima Voice agents, Audio and voice i Getting started with the Realtime API; maksimalno trajanje sesije: 60 minuta (Realtime conversations).

Arhitektura WebSocketa za Realtime API

OpenAI-jev Realtime API predstavlja temeljnu promjenu paradigme u načinu na koji komuniciraš s jezičnim modelima. Za razliku od tradicionalnih REST API-ja koji funkcioniraju na ciklusu zahtjev-odgovor, Realtime API koristi protokol WebSocket za uspostavu trajne, dvosmjerne veze između tvoje aplikacije i modela.

Ova arhitektura omogućuje razmjenu zvuka u stvarnom vremenu: šalješ audio, model ga obrađuje i odgovara glasom uz malu latenciju, preskačući međukorake transkripcije ili tekst-u-govor. Ovo je jedan od ključnih gradivnih blokova za konverzacijske glasovne agente i srž ovog tečaja.

Tri glasovne arhitekture u 2026.

Prije otvaranja WebSocket veze, stavi Realtime API u kontekst uz ostala OpenAI-jeva rješenja. Vodič Voice agents razlikuje tri pristupa:

ArhitekturaNajbolje zaZašto odabrati
GPT-LiveFull-duplex razgovore s odvojenim backendomGlasovni model sluša dok govori i delegira rezoniranje i korištenje alata na backend po tvojem izboru; zadržava tvoj postojeći tekstualni agent netaknutim
Realtime APIGovor, rezoniranje i alate u jednoj sesijiJedan model interpretira audio, odlučuje što učiniti i izgovara odgovor
Lanac obradeGranularnu kontrolu nad svakim korakomTranskripcija, zatim tekstualni agent, zatim sinteza govora: pregledavaš ili transformiraš tekst između koraka i neovisno zamjenjuješ svaku komponentu

Za nove aplikacije glasovnih razgovora, OpenAI-jeva stranica Audio and voice sada preporučuje početak s GPT-Live. Realtime API ostaje ispravan početni izbor kada se agent mora uklopiti u jednu sesiju, podržavajući prekidanje od strane korisnika, brz prvi audio odgovor, prirodnu izmjenu govornika i izravne pozive alata. Lanac obrade najbolje funkcionira kada svaki korak mora ostati vidljiv: zadržavanje transkripata, provođenje pravila prije nego agent odgovori ili emitiranje glasa tek nakon validacije odgovora.

Ovaj tečaj fokusira se na Realtime API i lanac obrade, čije su komponente (transkripcija, sinteza govora) obrađene u narednim odjeljcima.

WebRTC, WebSocket ili SIP

Tvoj izbor transporta ovisi o tome odakle audio potječe. Prema dokumentaciji: koristi WebRTC za audio u pregledniku, s privremenom tajnom klijenta koju generira tvoj poslužitelj; WebSocket za audio cjevovode na strani poslužitelja; SIP za telefonske pozive. Upravljčka veza na strani poslužitelja također omogućuje pouzdanom backendu promatranje i upravljanje medijskom sesijom. Ova lekcija detaljno opisuje WebSocket, najjednostavniji način za razumijevanje razmijenjenih događaja; u pregledniku daj prednost WebRTC-u. Realtime sesija traje najviše 60 minuta.

WebSocket naspram REST-a: Zašto taj izbor?

U tradicionalnoj REST arhitekturi, svaka interakcija zahtijeva kompletan HTTP zahtjev: otvaranje TCP veze, TLS pregovaranje, slanje zaglavlja, čekanje odgovora i zatvaranje veze. Za audio u stvarnom vremenu, ovo opterećenje je neprihvatljivo.

Kriterij REST (Responses API) WebSocket (Realtime API)
Latencija 200–500 ms po zahtjevu < 50 ms nakon povezivanja
Smjer Samo klijent → poslužitelj Istovremeno dvosmjerno
Veza Nova za svaki zahtjev Trajna (sesija)
Audio Potrebna cijela datoteka Streaming dio po dio

Protokol WebSocket neprekidno drži kanal otvorenim. Jednom uspostavljen, klijent i poslužitelj mogu slati poruke u bilo kojem trenutku bez čekanja da druga strana završi.

Uspostava WebSocket veze

Evo kako uspostaviti vezu s Realtime API-jem u Pythonu:

import asyncio
import websockets
import json

OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"

async def connect_realtime():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        print("Connected to Realtime API")

        # Receive the welcome event
        response = await ws.recv()
        event = json.loads(response)
        print(f"Type: {event['type']}")
        # → "session.created"

        # Keep the connection open
        await asyncio.Future()

asyncio.run(connect_realtime())

URL veze uključuje model kao upitni parametar. Otkako je API postao općenito dostupan, potrebno je samo zaglavlje za autentifikaciju—zaglavlje OpenAI-Beta: realtime=v1 iz beta faze je uklonjeno.

Sučelje zabilježeno 5. kolovoza 2026. — Realtime API evoluira (modeli, nazivi događaja, format sesije): u slučaju nedoumice, provjeri službenu dokumentaciju.

Arhitektura Realtime aplikacije

Aplikacija koja koristi Realtime API slijedi slojevitu arhitekturu:

1

Audio sloj (snimanje/reprodukcija)

Snima mikrofon, reproducira audio odgovore. Koristi PyAudio, sounddevice ili Web Audio API u pregledniku.

2

WebSocket sloj (transport)

Upravlja trajnom vezom, kodira/dekodira JSON događaje, rukuje ponovnim povezivanjima.

3

Aplikacijski sloj (poslovna logika)

Orkestrira razgovor, upravlja kontekstom, poziva alate, obrađuje rezultate.

4

Poslužiteljski sloj (opcionalni proxy)

U produkciji, posrednički poslužitelj štiti API ključ i dodaje poslovnu logiku na strani poslužitelja.

Uloga proxy poslužitelja

Tijekom razvoja, svoju aplikaciju možeš izravno povezati s Realtime API-jem. U produkciji, proxy poslužitelj je ključan za:

  • Zaštitu tvog API ključa — nikada ga ne izlaži na strani klijenta
  • Autentifikaciju tvojih korisnika — provjeri tokenove prije otvaranja sesije
  • Kontrolu troškova — ograniči trajanje sesije i korištenje tokena
  • Bilježenje interakcija — radi otklanjanja grešaka i usklađenosti
# Pojednostavljeni primjer WebSocket proxyja s FastAPI-jem
from fastapi import FastAPI, WebSocket
import websockets

app = FastAPI()

@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
    await client_ws.accept()

    headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}

    async with websockets.connect(URL, additional_headers=headers) as openai_ws:
        async def forward_to_openai():
            async for message in client_ws.iter_text():
                await openai_ws.send(message)

        async def forward_to_client():
            async for message in openai_ws:
                await client_ws.send_text(message)

        await asyncio.gather(forward_to_openai(), forward_to_client())

Ključne točke

  • Tri glasovne arhitekture kod OpenAI-ja: GPT-Live (preporučeno za nove konverzacijske aplikacije), Realtime API (govor, rezoniranje i alati u jednoj sesiji) i lanac transkripcija → agent → sinteza
  • WebRTC za audio u pregledniku, WebSocket za poslužiteljske cjevovode, SIP za telefoniju; sesije traju najviše 60 minuta
  • Realtime API koristi WebSocket za dvosmjernu komunikaciju male latencije
  • Veza je trajna: jedno otvaranje za cijelu konverzacijsku sesiju
  • Slojevita arhitektura odvaja audio, transport, poslovnu logiku i poslužiteljski proxy
  • U produkciji, proxy poslužitelj je ključan za sigurnost i kontrolu troškova
  • Protokol je vođen događajima: svaka poruka je JSON objekt s poljem type