# OpenAI Realtime

API метод WebSocket /openai/api/v1/realtime, ограничения сессии и расчет использования.

`GET /openai/api/v1/realtime` с WebSocket Upgrade открывает Realtime-сессию для моделей GPT Realtime либо сессию распознавания речи. Поля событий описаны в [документации OpenAI Realtime](https://developers.openai.com/api/reference/resources/realtime/methods/connect), модели — в [каталоге](https://coreinfra.ru/docs/catalog.md).

HTTP-тела у запроса нет. Минимальный запрос на открытие соединения:

```bash
curl --http1.1 -i 'https://hub.coreinfra.ai/openai/api/v1/realtime?model=gpt-realtime-2.1' \
  -H "Authorization: Bearer $COREINFRA_API_KEY" \
  -H 'Connection: Upgrade' \
  -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' \
  -H 'Sec-WebSocket-Key: AAAAAAAAAAAAAAAAAAAAAA=='
```

Фрагмент успешного ответа на Upgrade:

```http
HTTP/1.1 101 Switching Protocols
Connection: upgrade
Upgrade: websocket
```

Далее обмен идет через JSON-события WebSocket по адресу `wss://hub.coreinfra.ai/openai/api/v1/realtime?model=gpt-realtime-2.1`; пример выше проверяет только открытие соединения.

## Отличия от API OpenAI

Ключ хаба передается в `Authorization: Bearer …`. Из подпротоколов допустим только `realtime`; передавать ключ через подпротокол нельзя. Beta-интерфейс с `OpenAI-Beta`, содержащим `realtime`, не поддерживается. Присутствие `call_id` отклоняется: подключение к WebRTC- или SIP-вызову не обслуживается.

В query `intent` принимает `realtime` или `transcription`, по умолчанию выбирается `realtime`. Для обычной сессии нужен `model`; для `intent=transcription` модель распознавания речи задается в настройках сессии. Конвертации в модели других протоколов нет.

### События и поля

Хаб принимает JSON в текстовых сообщениях. Бинарные сообщения и неизвестные типы событий отклоняются. У `event_id` допускается строка не длиннее 512 символов.

В `session.update` отклоняются `prompt`, `tracing` и MCP-инструмент с `tunnel_id`, если соответствующее поле не равно `null`. Также запрещены смена модели или типа сессии и пользовательский голос. Можно повторить текущую модель; перед отправкой поле `model` удаляется. Модель распознавания речи должна поддерживаться хабом; псевдоним модели в этой настройке не принимается.

В `response.create` действуют те же запреты на `prompt`, MCP с `tunnel_id` и пользовательский голос; `null` в `prompt` и `tunnel_id` допускается. `conversation` может быть `auto`, `none` или `null`. Для сессии распознавания речи `response.create` запрещен. В сообщениях и входе ответа изображения принимаются только в кодировке base64 (`data:image/...;base64,...`).

В `response.metadata` допускается не более 15 пар ключ–значение.

События `rate_limits.updated` клиенту не передаются.

### Резерв и списание

При открытии обычной сессии проверяется доступность средств для первого ответа, без удержания резерва. Каждый ответ модели и каждое распознавание входного аудио оплачиваются как отдельная операция. Клиентский `response.create` резервируется до отправки; ответ или распознавание, начатые автоматически, — после события о начале.

Списание идет по использованию завершенной операции с разделением текста, аудио, изображений и чтения кэша по [тарифам](https://hub.coreinfra.ai/pricing) (подробнее — на страницах [«Стоимость моделей Realtime»](https://coreinfra.ru/docs/billing/realtime.md) и [«Стоимость синтеза и распознавания речи»](https://coreinfra.ru/docs/billing/speech.md)). Если средств для автоматически начатой работы не хватает, хаб отменяет ответ и закрывает сессию; уже начатая работа учитывается.

После отключения клиента хаб до 30 секунд получает использование начатых операций. Максимальная длительность соединения — один час. На запись в соединение отводится 10 секунд. Размер одного сообщения WebSocket ограничен 100 МиБ.

## Ошибки

До Upgrade статус-код `400` означает неверный `intent`, отсутствующий `model`, недопустимый `call_id`, подпротокол, beta-интерфейс или неподдерживаемую модель. Некорректный Upgrade либо обычный HTTP-запрос без Upgrade возвращает статус-код `426`.

После Upgrade ошибки передаются событием `error`. Коды ограничений: `stored_prompt_unsupported`, `tracing_unsupported`, `mcp_tunnel_unsupported`, `model_change_unsupported`, `session_type_change_unsupported`, `transcription_session_response_unsupported`, `transcription_model_unsupported`, `remote_image_unsupported`, `custom_voice_unsupported`, `conversation_unsupported`, `malformed_event`, `metadata_full`, `binary_event_unsupported`, `unknown_event_type`. Истечение срока соединения обозначается `session_expired`.

Отказ в создании резерва возвращается как `hub_request_rejected`, отказ в доступе — `hub_forbidden`, внутренняя ошибка — `hub_internal_error`. Общие ошибки авторизации, баланса и лимитов расходов описаны в [общем справочнике](https://coreinfra.ru/docs/reference.md#errors).
