Sesje, zdarzenia i cykl życia
Na tej stronie
Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych:
tts-1,tts-1-hdigpt-4o-mini-ttsprzestaną działać 6 stycznia 2027 (zastąpienie:gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez/v1/audio/speech: migracja syntezy mowy przechodzi do Realtime API);gpt-realtime,gpt-4o-realtimei starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribei/v1/audio/translations26 lutego 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). W przypadku głosu pełnodupleksowego, GPT-Live 1 jest dostępny w API od 10 września 2026.
Skorygowano 3 listopada 2026. Transkrypcja wejścia używała
gpt-live-transcribe, który działa tylko w sesji transkrypcji i nie obsługuje aniserver_vad, anisemantic_vad. W sesji konwersacyjnej, takiej jak ta, gdzie VAD waliduje każdą turę, dokumentacja wskazujegpt-transcribe, który transkrybuje zwalidowane tury i wykorzystuje poprzednie tury jako kontekst. Źródła: Transkrypcja w czasie rzeczywistym · GPT-Transcribe · GPT-Live-Transcribe.
Sesje, zdarzenia i cykl życia
Każde połączenie WebSocket z Realtime API tworzy sesję. Sesja jest podstawową jednostką zarządzania: inkapsuluje konfigurację modelu, historię rozmowy, dostępne narzędzia oraz bieżący stan interakcji. Zrozumienie jej cyklu życia jest kluczowe dla budowania niezawodnych agentów głosowych.
Cykl życia sesji
Gdy tylko połączenie WebSocket zostanie nawiązane, serwer emituje zdarzenie session.created. Sesja przechodzi przez kilka faz:
Połączenie → session.created
Serwer potwierdza sesję, przypisując unikalny identyfikator i domyślną konfigurację.
Konfiguracja → session.update
Wysyłasz session.update, aby zdefiniować instrukcje, głos, narzędzia i modalności.
Aktywna rozmowa
Wymiana zdarzeń audio i tekstowych między klientem a serwerem.
Zamknięcie → rozłączenie WebSocket
Sesja jest niszczona po zamknięciu połączenia. Żaden stan nie jest przechowywany na serwerze.
Konfigurowanie sesji
Po otrzymaniu session.created wyślij zdarzenie session.update, aby skonfigurować zachowanie modelu. Transkrypcja wypowiedzi użytkownika (audio.input.transcription) jest opcjonalna: bez niej otrzymasz głos, ale nie tekst. Parametr languages określa oczekiwane języki i poprawia rozpoznawanie:
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:
# Poczekaj na session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Skonfiguruj sesję
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": []
}
}))
# Poczekaj na potwierdzenie (inne zdarzenia mogą nadejść wcześniej)
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"])
Kluczowe parametry sesji
| Parametr | Opis | Zalecana wartość |
|---|---|---|
| output_modalities | Modalności wyjściowe | ["audio"] (lub ["text"]) |
| audio.output.voice | Głos syntezy | marin, cedar, alloy, echo itd. |
| audio.input.turn_detection | Wykrywanie końca wypowiedzi | server_vad z progiem 0.5 |
| audio.input.format | Format przychodzącego audio | {"type": "audio/pcm", "rate": 24000} |
System zdarzeń
Realtime API działa w pełni w oparciu o zdarzenia. Każda wymieniana wiadomość to obiekt JSON z polem type, które określa jej charakter. Zdarzenia dzielą się na dwie kategorie:
Zdarzenia klienta (ty → serwer)
# Główne zdarzenia wysyłane przez Ciebie
client_events = {
"session.update": "Modyfikacja konfiguracji",
"input_audio_buffer.append": "Wysłanie fragmentu audio",
"input_audio_buffer.commit": "Zatwierdzenie bufora audio",
"input_audio_buffer.clear": "Wyczyszczenie bufora audio",
"conversation.item.create": "Ręczne dodanie wiadomości",
"conversation.item.truncate": "Skrócenie odpowiedzi",
"conversation.item.delete": "Usunięcie wiadomości",
"response.create": "Uruchomienie generowania odpowiedzi",
"response.cancel": "Anulowanie bieżącej odpowiedzi",
}
Zdarzenia serwera (serwer → ty)
# Główne zdarzenia otrzymywane przez Ciebie
server_events = {
"session.created": "Inicjalizacja sesji",
"session.updated": "Zastosowanie konfiguracji",
"input_audio_buffer.speech_started": "Wykrycie mowy",
"input_audio_buffer.speech_stopped": "Wykrycie ciszy",
"conversation.item.created": "Nowa wiadomość w historii",
"response.created": "Rozpoczęcie generowania",
"response.output_audio.delta": "Fragment audio odpowiedzi",
"response.output_audio_transcript.delta": "Fragment transkrypcji",
"response.done": "Zakończenie odpowiedzi",
"error": "Błąd",
}
Obsługa błędów
Błędy są emitowane jako zdarzenia typu error. Musisz je zawsze перехwytywać:
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":
# Błąd konfiguracji, napraw i spróbuj ponownie
pass
elif error["type"] == "server_error":
# Problem po stronie OpenAI, połącz ponownie
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}")
Kluczowe wnioski
- Sesja jest tworzone automatycznie po nawiązaniu połączenia WebSocket i niszczona po rozłączeniu
session.updatekonfiguruje sesję posession.created; poczekaj nasession.updated, zanim zaczniesz polegać na nowej konfiguracji- Aby transkrybować dane wejściowe w sesji konwersacyjnej, użyj
gpt-transcribe;gpt-live-transcribejest zarezerwowany dla sesji transkrypcji - Protokół jest czysto zdarzeniowy: każda wiadomość posiada
type, który determinuje sposób jej obsługi - Zdarzenia klienta sterują interakcją; zdarzenia serwera raportują wyniki
- Obsługa błędów jest kluczowa: zawsze nasłuchuj zdarzeń
error