Arhitektura WebSocketa za Realtime API
Na ovoj stranici
Ažurirano 2. studenoga 2026. — Audio 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 od strane/v1/audio/speech: migracija sinteze govora prelazi na Realtime API);gpt-realtime,gpt-4o-realtimei stariji audio 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. 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:
| Arhitektura | Najbolje za | Zašto odabrati |
|---|---|---|
| GPT-Live | Full-duplex razgovore s odvojenim backendom | Glasovni 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 API | Govor, rezoniranje i alate u jednoj sesiji | Jedan model interpretira audio, odlučuje što učiniti i izgovara odgovor |
| Lanac obrade | Granularnu kontrolu nad svakim korakom | Transkripcija, 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:
Audio sloj (snimanje/reprodukcija)
Snima mikrofon, reproducira audio odgovore. Koristi PyAudio, sounddevice ili Web Audio API u pregledniku.
WebSocket sloj (transport)
Upravlja trajnom vezom, kodira/dekodira JSON događaje, rukuje ponovnim povezivanjima.
Aplikacijski sloj (poslovna logika)
Orkestrira razgovor, upravlja kontekstom, poziva alate, obrađuje rezultate.
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