Architektura WebSocket interfejsu API Realtime
Na tej stronie
Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie zostało wycofanych:
tts-1,tts-1-hdorazgpt-4o-mini-ttsprzestaną działać 6 stycznia 2027 (zamiennik:gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez/v1/audio/speech: migracja syntezy mowy przenosi się do interfejsu API Realtime);gpt-realtime,gpt-4o-realtimeoraz starsze modele audio przestaną działać 20 stycznia 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoraz/v1/audio/translationsprzestaną działać 26 lutego 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). W przypadku rozmów głosowych w trybie pełnodupleksowym, GPT-Live 1 jest dostępny w API od 10 września 2026. Dodatkowa uwaga z 3 listopada 2026: sekcja dotycząca trzech architektur głosowych OpenAI (GPT-Live, Realtime API, łańcuch przetwarzania) oraz wyboru transportu (WebRTC, WebSocket, SIP), oparta na przewodnikach Voice agents, Audio and voice oraz Getting started with the Realtime API; maksymalny czas trwania sesji: 60 minut (Realtime conversations).
Architektura WebSocket interfejsu API Realtime
Interfejs API Realtime od OpenAI stanowi fundamentalną zmianę paradygmatu w sposobie interakcji z modelami językowymi. W przeciwieństwie do tradycyjnych interfejsów REST działających w cyklu żądanie-odpowiedź, API Realtime wykorzystuje protokół WebSocket do nawiązania stałego, dwukierunkowego połączenia między Twoją aplikacją a modelem.
Ta architektura umożliwia wymianę dźwięku w czasie rzeczywistym: wysyłasz audio, model je przetwarza i odpowiada głosem z niskim opóźnieniem, pomijając pośrednie etapy transkrypcji czy syntezy mowy z tekstu. Jest to jeden z kluczowych elementów budujących konwersacyjnych agentów głosowych i sedno tego kursu.
Trzy architektury głosowe w 2026 roku
Zanim otworzysz połączenie WebSocket, umieść API Realtime w kontekście innych rozwiązań OpenAI. Przewodnik Voice agents wyróżnia trzy podejścia:
| Architektura | Najlepsze zastosowanie | Dlaczego warto wybrać |
|---|---|---|
| GPT-Live | Rozmowy pełnodupleksowe z oddzielnym backendem | Model głosowy słucha podczas mówienia i deleguje rozumowanie oraz używanie narzędzi do wybranego przez Ciebie backendu; pozwala zachować istniejącego agenta tekstowego |
| Realtime API | Mowa, rozumowanie i narzędzia w jednej sesji | Pojedynczy model interpretuje audio, decyduje co zrobić i wypowiada odpowiedź |
| Łańcuch przetwarzania | Szczegółowa kontrola nad każdym krokiem | Transkrypcja, następnie agent tekstowy, potem synteza mowy: możesz inspekcjonować lub przekształcać tekst między krokami i niezależnie wymieniać każdy komponent |
W przypadku nowych aplikacji do rozmów głosowych, strona Audio and voice od OpenAI rekomenduje obecnie rozpoczęcie pracy z GPT-Live. API Realtime pozostaje właściwym punktem startowym, gdy agent musi mieścić się w jednej sesji, obsługując przerwanie przez użytkownika, szybką pierwszą odpowiedź audio, naturalne przekazywanie głosu i bezpośrednie wywołania narzędzi. Łańcuch przetwarzania sprawdza się najlepiej, gdy każdy krok musi pozostać widoczny: zachowanie transkryptów, wymuszanie reguł przed odpowiedzią agenta lub emitowanie głosu dopiero po walidacji odpowiedzi.
Ten kurs skupia się na API Realtime oraz łańcuchu przetwarzania, których komponenty (transkrypcja, synteza mowy) są omówione w kolejnych sekcjach.
WebRTC, WebSocket czy SIP
Wybór transportu zależy od źródła dźwięku. Zgodnie z dokumentacją: użyj WebRTC dla dźwięku z przeglądarki, z efemerycznym sekretem klienta generowanym przez Twój serwer; WebSocket dla serwerowych potoków audio; SIP dla połączeń telefonicznych. Połączenie kontrolne po stronie serwera pozwala również zaufanemu backendowi obserwować i sterować sesją multimedialną. Ta lekcja szczegółowo opisuje WebSocket, jako najprostszy sposób na zrozumienie wymienianych zdarzeń; w przeglądarce preferuj WebRTC. Sesja Realtime trwa maksymalnie 60 minut.
WebSocket kontra REST: dlaczego ten wybór?
W tradycyjnej architekturze REST każda interakcja wymaga kompletnego żądania HTTP: otwarcia połączenia TCP, negocjacji TLS, wysłania nagłówków, oczekiwania na odpowiedź i zamknięcia połączenia. W przypadku dźwięku w czasie rzeczywistym ten narzut jest nie do przyjęcia.
| Kryterium | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Opóźnienie | 200–500 ms na żądanie | < 50 ms po nawiązaniu połączenia |
| Kierunek | Tylko klient → serwer | Jednoczesny dwukierunkowy |
| Połączenie | Nowe dla każdego żądania | Stałe (sesja) |
| Audio | Wymagany pełny plik | Strumieniowanie fragment po fragmencie |
Protokół WebSocket utrzymuje kanał stale otwarty. Po nawiązaniu połączenia klient i serwer mogą wysyłać wiadomości w dowolnym momencie, nie czekając na zakończenie działania drugiej strony.
Nawiązywanie połączenia WebSocket
Oto jak nawiązać połączenie z API Realtime w Pythonie:
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")
# Odbierz zdarzenie powitalne
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Utrzymaj połączenie otwarte
await asyncio.Future()
asyncio.run(connect_realtime())
Adres URL połączenia zawiera model jako parametr zapytania. Od momentu udostępnienia API do powszechnego użytku, wymagany jest tylko nagłówek uwierzytelniający – nagłówek OpenAI-Beta: realtime=v1 z fazy beta został usunięty.
Interfejs odnotowany 5 sierpnia 2026 — API Realtime ewoluuje (modele, nazwy zdarzeń, format sesji): w razie wątpliwości sprawdź oficjalną dokumentację.
Architektura aplikacji Realtime
Aplikacja korzystająca z API Realtime遵循uje architekturę warstwową:
Warstwa audio (przechwytywanie/odtwarzanie)
Przechwytuje mikrofon, odtwarza odpowiedzi audio. Wykorzystuje PyAudio, sounddevice lub Web Audio API w przeglądarce.
Warstwa WebSocket (transport)
Zarządza stałym połączeniem, koduje/dekoduje zdarzenia JSON, obsługuje ponowne łączenie.
Warstwa aplikacji (logika biznesowa)
Orkiestruje rozmowę, zarządza kontekstem, wywołuje narzędzia, przetwarza wyniki.
Warstwa serwera (opcjonalny serwer proxy)
W środowisku produkcyjnym serwer pośredni chroni klucz API i dodaje serwerową logikę biznesową.
Rola serwera proxy
Podczas rozwoju możesz połączyć swoją aplikację bezpośrednio z API Realtime. W środowisku produkcyjnym serwer proxy jest niezbędny, aby:
- Chronić Twój klucz API — nigdy nie udostępniaj go po stronie klienta
- Uwierzytelniać użytkowników — weryfikuj tokeny przed otwarciem sesji
- Kontrolować koszty — ograniczaj czas trwania sesji i zużycie tokenów
- Rejestrować interakcje — do celów debugowania i zgodności
# Uproszczony przykład proxy WebSocket z FastAPI
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())
Kluczowe wnioski
- Trzy architektury głosowe w OpenAI: GPT-Live (rekomendowane dla nowych aplikacji konwersacyjnych), Realtime API (mowa, rozumowanie i narzędzia w jednej sesji) oraz łańcuch transkrypcja → agent → synteza
- WebRTC dla audio z przeglądarki, WebSocket dla potoków serwerowych, SIP dla telefonii; sesje trwają maksymalnie 60 minut
- API Realtime wykorzystuje WebSocket do niskoopóźnieniowej komunikacji dwukierunkowej
- Połączenie jest stałe: jedno otwarcie na całą sesję konwersacyjną
- Architektura warstwowa oddziela audio, transport, logikę biznesową i serwer proxy
- W środowisku produkcyjnym serwer proxy jest niezbędny dla bezpieczeństwa i kontroli kosztów
- Protokół jest sterowany zdarzeniami: każda wiadomość to obiekt JSON z polem
type