OpenAI Realtime API: как устроить голосовой диалог в браузере

[cybercobra]

Для живого голосового диалога в браузере OpenAI рекомендует Realtime API с WebRTC. Сервер приложения выдаёт временный доступ к сеансу, а браузер передаёт звук. Постоянный API-ключ нельзя помещать в клиентский JavaScript: его сможет получить посетитель.

Разберём не только подключение, но и границу между звуком, событиями сеанса и серверными действиями. Именно их смешение усложняет диагностику, когда разговор уже начался, а после обращения к инструменту соединение пропадает.

Когда нужен именно Realtime​

Этот интерфейс рассчитан на разговор с быстрым ответом, перебиваниями и использованием инструментов во время диалога. Если задача состоит только в расшифровке готового файла, начинать с голосового сеанса обычно незачем: это другая архитектура.

В текущем вводном примере OpenAI используется gpt-realtime-2.1. Для браузера показан WebRTC, для серверного соединения — WebSocket. Выбор транспорта не заменяет проверку доступности модели и условий API для вашего проекта.

Как разделить браузер и сервер​

Вариант с временным ключом устроен так:

1. Браузер обращается к вашему серверу, чтобы начать сеанс.
2. Сервер с постоянным API-ключом запрашивает временный client secret.
3. Браузер получает только временный секрет и устанавливает WebRTC-соединение.
4. Аудио и события обрабатываются в рамках сеанса; ваша бизнес-логика остаётся отдельно.

В действующем интерфейсе для временного доступа используется POST /v1/realtime/client_secrets. Это не повод сделать свой endpoint выдачи секретов общедоступным без контроля. Авторизация пользователя и ограничение числа запусков нужны уже в вашем приложении.

Временный ключ защищает постоянный секрет, но сам по себе не ограничивает расходы вашего сервиса. Не записывайте оба вида ключей в журналы ошибок и не присылайте их вместе со скриншотами.

Почему «звук работает» ещё не означает готовность приложения​

Голосовой ответ подтверждает лишь часть цепочки. Отдельно проверьте обращение к серверному инструменту: например, к поиску по вашей базе. Для первого теста выбирайте безопасное действие только на чтение, без оплаты и изменения данных.

Успешный результат инструмента на сервере не доказывает, что приложение правильно передало его обратно в сеанс. Полезно различать три точки: сервер получил вызов, вернул данные, клиент отправил поддерживаемое событие в открытый канал.

Если соединение закрылось, сохраните время и порядок событий, состояние канала до отправки и текст ошибки. Из сообщения об обрыве нельзя уверенно заключить, что виноват размер ответа, модель или сеть. Эти причины требуют отдельных проверок.

Не смешивайте старые и новые примеры​

В актуальной инструкции перехода с beta на GA OpenAI отдельно требует обновить формат сеанса и событий. В частности, убирается старый заголовок OpenAI-Beta: realtime=v1, а для WebRTC применяется /v1/realtime/calls.

Поэтому опасно собирать приложение из трёх фрагментов разных лет: выдачу токена из одного руководства, создание сеанса из другого, отправку результата инструмента из третьего. Начните с одного актуального официального примера и добавляйте функции по очереди.

Что проверить перед открытием доступа пользователям​

• Начало и завершение разговора без оставшегося активного микрофона.
• Отказ в разрешении на микрофон с понятным сообщением.
• Перебивание ответа и последующее продолжение разговора.
• Недоступность серверного инструмента без выдуманного успешного результата.
• Повторное подключение после обрыва без двойного выполнения действия.
• Учёт потребления и ограничение злоупотреблений на стороне приложения.

Это план проверки, а не заявление о проведённом тестировании. Платные вызовы для статьи не выполнялись. Начальная схема и примеры доступны в руководстве Realtime API, а разделение клиентского и серверного доступа — в руководстве WebRTC.