Sessioner, händelser och livscykel
På denna sida
Uppdaterat 2 november 2026 — Ljudmodeller. Flera modeller i denna kurs är avvecklade:
tts-1,tts-1-hdochgpt-4o-mini-ttsslutar fungera den 6 januari 2027 (ersättning:gpt-realtime-2.1-mini, vilket OpenAI:s TTS-guide anger inte stöds av/v1/audio/speech: migreringen av talgenerering flyttas till Realtime API);gpt-realtime,gpt-4o-realtimeoch äldre ljudmodeller den 20 januari 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoch/v1/audio/translationsden 26 februari 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). För full-duplex-röst har GPT-Live 1 funnits tillgängligt i API:t sedan den 10 september 2026.
Korrigerat 3 november 2026. Inmatningstranskribering använde
gpt-live-transcribe, vilket endast fungerar i en transkriberingssession och varken stöderserver_vadellersemantic_vad. I en konversationssession som denna, där VAD validerar varje tur, specificerar dokumentationengpt-transcribe, som transkriberar validerade turer och använder tidigare turer som kontext. Källor: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Sessioner, händelser och livscykel
Varje WebSocket-anslutning till Realtime API skapar en session. Denna session är den grundläggande enheten för hantering: den kapslar in modellkonfiguration, konversationshistorik, tillgängliga verktyg och det aktuella tillståndet för interaktionen. Att förstå dess livscykel är avgörande för att bygga robusta röstagenter.
En sessions livscykel
Så snart WebSocket-anslutningen är etablerad sänder servern en händelse session.created. Sessionen genomgår flera faser:
Anslutning → session.created
Servern bekräftar sessionen med ett unikt ID och standardkonfiguration.
Konfiguration → session.update
Du skickar session.update för att definiera instruktioner, röst, verktyg och modaliteter.
Aktiv konversation
Utbyte av ljud- och texthändelser mellan klient och server.
Avslutning → WebSocket disconnect
Sessionen förstörs när anslutningen stängs. Inget tillstånd behålls på servern.
Konfigurera en session
Efter session.created skickar du en händelse session.update för att konfigurera modellens beteende. Att transkribera vad användaren säger (audio.input.transcription) är valfritt: utan detta får du rösten men inte texten. languages specificerar de förväntade språken och förbättrar igenkänningen:
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:
# Vänta på session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfigurera sessionen
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": []
}
}))
# Vänta på bekräftelse (andra händelser kan anlända först)
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"])
Viktiga sessionsparametrar
| Parameter | Beskrivning | Rekommenderat värde |
|---|---|---|
| output_modalities | Utmatningsmodaliteter | ["audio"] (eller ["text"]) |
| audio.output.voice | Syntesröst | marin, cedar, alloy, echo, etc. |
| audio.input.turn_detection | Detektering av talstopp | server_vad med tröskelvärde 0.5 |
| audio.input.format | Inkommande ljudformat | {"type": "audio/pcm", "rate": 24000} |
Händelsesystemet
Realtime API är helt händelsestyrt. Varje utbytt meddelande är ett JSON-objekt med ett fält type som avgör dess natur. Händelser delas in i två kategorier:
Klienthändelser (du → server)
# De viktigaste händelserna du skickar
client_events = {
"session.update": "Ändra konfiguration",
"input_audio_buffer.append": "Skicka en ljudbit",
"input_audio_buffer.commit": "Bekräfta ljudbufferten",
"input_audio_buffer.clear": "Rensa ljudbufferten",
"conversation.item.create": "Lägg till ett meddelande manuellt",
"conversation.item.truncate": "Korta ner ett svar",
"conversation.item.delete": "Ta bort ett meddelande",
"response.create": "Utlös ett svar",
"response.cancel": "Avbryt det aktuella svaret",
}
Serverhändelser (server → du)
# De viktigaste händelserna du tar emot
server_events = {
"session.created": "Session initierad",
"session.updated": "Konfiguration tillämpad",
"input_audio_buffer.speech_started": "Tal detekterat",
"input_audio_buffer.speech_stopped": "Tystnad detekterad",
"conversation.item.created": "Nytt meddelande i historiken",
"response.created": "Generering startad",
"response.output_audio.delta": "Ljudbit i svar",
"response.output_audio_transcript.delta": "Transkriberingsbit",
"response.done": "Svar avslutat",
"error": "Fel",
}
Felhantering
Fel sänds via en händelse av typen error. Du måste alltid fånga upp dem:
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"Fel [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Konfigurationsfel, åtgärda och försök igen
pass
elif error["type"] == "server_error":
# Problem på OpenAI:s sida, återanslut
pass
elif event_type == "session.updated":
print("Konfiguration tillämpad framgångsrikt")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Använda tokens: {usage}")
Viktiga punkter
- En session skapas automatiskt vid WebSocket-anslutning och förstörs vid frånkoppling
session.updatekonfigurerar sessionen eftersession.created; vänta påsession.updatedinnan du förlitar dig på den nya konfigurationen- För att transkribera inmatning i en konversationssession, använd
gpt-transcribe;gpt-live-transcribeär reserverat för transkriberingssessioner - Protokollet är rent händelsestyrt: varje meddelande har en
typesom avgör hur det hanteras - Klienthändelser styr interaktionen; serverhändelser rapporterar resultat
- Felhantering är avgörande: lyssna alltid efter
error-händelser