Сесии, събития и жизнен цикъл
На тази страница
Обновено на 2 ноември 2026 г. — Аудио модели. Няколко модела в този курс са депрецирали:
tts-1,tts-1-hdиgpt-4o-mini-ttsще спрат да работят на 6 януари 2027 г. (замяна:gpt-realtime-2.1-mini, който според ръководството на OpenAI за TTS не се поддържа от/v1/audio/speech: миграцията на синтез на реч преминава към Realtime API);gpt-realtime,gpt-4o-realtimeи наследените аудио модели на 20 януари 2027 г. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeи/v1/audio/translationsна 26 февруари 2027 г. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). За дуплексна гласова връзка, GPT-Live 1 е наличен в API от 10 септември 2026 г.
Коригирано на 3 ноември 2026 г. Транскрипцията на входа използваше
gpt-live-transcribe, който работи само в сесия за транскрипция и не поддържа нитоserver_vad, нитоsemantic_vad. В разговорна сесия като тази, където VAD валидира всяка реплика, документацията специфицираgpt-transcribe, който транскрибира валидирани реплики и използва предишните реплики като контекст. Източници: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Сесии, събития и жизнен цикъл
Всяка WebSocket връзка към Realtime API създава сесия. Тази сесия е основната единица за управление: тя обхваща конфигурацията на модела, историята на разговора, наличните инструменти и текущото състояние на взаимодействието. Разбирането на нейния жизнен цикъл е от съществено значение за изграждането на надеждни гласови агенти.
Жизненият цикъл на една сесия
Веднага щом WebSocket връзката бъде установена, сървърът изпраща събитие session.created. Сесията преминава през няколко фази:
Връзка → session.created
Сървърът потвърждава сесията с уникален идентификатор и конфигурация по подразбиране.
Конфигурация → session.update
Вие изпращате session.update, за да дефинирате инструкции, глас, инструменти и модалности.
Активен разговор
Размяна на аудио и текстови събития между клиента и сървъра.
Затваряне → WebSocket disconnect
Сесията се унищожава, когато връзката се затвори. Никакво състояние не се запазва на сървъра.
Конфигуриране на сесия
След session.created, изпратете събитие session.update, за да конфигурирате поведението на модела. Транскрибирането на това, което потребителят казва (audio.input.transcription), е по избор: без него получавате гласа, но не и текста. languages определя очакваните езици и подобрява разпознаването:
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:
# Изчакайте session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Конфигурирайте сесията
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": []
}
}))
# Изчакайте потвърждение (други събития може да пристигнат първи)
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"])
Ключови параметри на сесията
| Параметър | Описание | Препоръчителна стойност |
|---|---|---|
| output_modalities | Изходни модалности | ["audio"] (или ["text"]) |
| audio.output.voice | Глас за синтез | marin, cedar, alloy, echo и др. |
| audio.input.turn_detection | Откриване на край на речта | server_vad с праг 0.5 |
| audio.input.format | Входящ аудио формат | {"type": "audio/pcm", "rate": 24000} |
Системата от събития
Realtime API е изцяло базиран на събития. Всяко разменено съобщение е JSON обект с поле type, което определя неговата природа. Събитията попадат в две категории:
Събития от клиента (Вие → сървър)
# Основните събития, които изпращате
client_events = {
"session.update": "Промяна на конфигурацията",
"input_audio_buffer.append": "Изпращане на аудио чънк",
"input_audio_buffer.commit": "Фиксиране на аудио буфера",
"input_audio_buffer.clear": "Изчистване на аудио буфера",
"conversation.item.create": "Ръчно добавяне на съобщение",
"conversation.item.truncate": "Съкращаване на отговор",
"conversation.item.delete": "Изтриване на съобщение",
"response.create": "Стартиране на отговор",
"response.cancel": "Отмяна на текущия отговор",
}
Събития от сървъра (сървър → Вие)
# Основните събития, които получавате
server_events = {
"session.created": "Сесията е инициализирана",
"session.updated": "Конфигурацията е приложена",
"input_audio_buffer.speech_started": "Открита е реч",
"input_audio_buffer.speech_stopped": "Открита е тишина",
"conversation.item.created": "Ново съобщение в историята",
"response.created": "Генерирането започна",
"response.output_audio.delta": "Аудио чънк от отговора",
"response.output_audio_transcript.delta": "Транскрипционен чънк",
"response.done": "Отговорът приключи",
"error": "Грешка",
}
Обработка на грешки
Грешките се изпращат чрез събитие от тип error. Винаги трябва да ги прихващате:
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":
# Грешка в конфигурацията, поправете и опитайте отново
pass
elif error["type"] == "server_error":
# Проблем от страна на OpenAI, свържете се отново
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}")
Ключови изводи
- Сесия се създава автоматично при установяване на WebSocket връзка и се унищожава при прекъсване на връзката
session.updateконфигурира сесията следsession.created; изчакайтеsession.updated, преди да разчитате на новата конфигурация- За транскрибиране на вход в разговорна сесия използвайте
gpt-transcribe;gpt-live-transcribeе запазен за сесии за транскрипция - Протоколът е изцяло базиран на събития: всяко съобщение има
type, който определя обработката му - Събитията от клиента управляват взаимодействието; събитията от сървъра докладват резултатите
- Обработката на грешки е от критично значение: винаги слушайте за събития
error