OpenAI Realtime API

Что такое OpenAI Realtime API?

OpenAI Realtime API обеспечивает связь с низкой задержкой между вашим приложением и моделями, которые поддерживают speech-to-speech взаимодействие. Также поддерживает мультимодальные входы — audio, images и text — и мультимодальные выходы — audio и text — что делает его подходящим для интерактивных голосовых сценариев.

Помимо voice agents, Realtime API можно использовать для realtime-транскрипции аудио путём стриминга через WebSocket-соединение. Документация также выделяет рекомендуемые стартовые точки (например, Agents SDK for TypeScript) для браузерных voice agent workflow.

Ключевые возможности

• Speech-to-speech взаимодействия с низкой задержкой: Разработано для realtime-конверсационных аудио-сценариев, а не только request/response.
• Мультимодальные входы (audio, images, text): Позволяет одной сессии принимать разные типы входов в зависимости от логики приложения.
• Мультимодальные выходы (audio и text): Поддерживает возврат audio, text или обоих в рамках взаимодействия.
• Различные методы подключения: Выберите WebRTC (браузер/client-side), WebSocket (middle-tier server-side с постоянной низкой задержкой) или SIP (VoIP-телефония).
• Гайды по сессиям и разговорам: Включает рекомендации по промптингу, событиям жизненного цикла разговора и управлению поведением сессии на сервере.
• Realtime-транскрипция через WebSocket: Обеспечивает транскрипцию аудио-потоков в реальном времени.

Как использовать OpenAI Realtime API

1. Выберите метод подключения в зависимости от среды приложения: WebRTC для браузера/client, WebSocket для сервера/middle-tier или SIP для VoIP-телефонии.
2. Начните с сессии. Для браузерных voice agents документация рекомендует Agents SDK for TypeScript, который использует WebRTC в браузере и WebSocket на сервере.
3. Создайте и инициализируйте сессию в коде, затем подключитесь с помощью client API-ключа (пример использует RealtimeAgent и RealtimeSession с session.connect).
4. Взаимодействуйте с моделью через события. После подключения используйте гайды по промптингу/управлению, жизненному циклу разговора и (при необходимости) серверному контролю через webhooks.

Документация также описывает детали миграции на GA (см. FAQ), которые влияют на аутентификацию Realtime-запросов.

Сценарии использования

• Браузерный voice agent с speech-to-speech: Используйте WebRTC (часто через Agents SDK for TypeScript) для подключения микрофона и аудио-выхода в интерактивный разговор.
• Серверный realtime-ассистент: Используйте WebSocket-соединение из middle-tier для постоянной низкой задержки сети и централизованного управления сессиями.
• Интеграция с VoIP/телефонией: Подключайтесь через SIP, если целевая среда — телефония, а не веб-браузер.
• Realtime-транскрипция аудио: Стриньте аудио в Realtime-транскрипцию через WebSocket, чтобы получать результаты транскрипции во время отправки.
• Мультимодальное взаимодействие: Принимайте audio вместе с images и text в одной realtime-сессии, затем возвращайте audio, text или оба.

FAQ

Нужен ли beta-заголовок при использовании GA Realtime API?

Для GA-запросов документация указывает, что заголовок OpenAI-Beta: realtime=v1 следует удалить. Чтобы сохранить beta-поведение, продолжайте включать этот заголовок.

Как сгенерировать credentials для client-side (браузерных) Realtime-сессий?

В GA-интерфейсе документация описывает единый REST-эндпоинт — POST /v1/realtime/client_secrets — для генерации ключей, используемых для инициализации WebRTC или WebSocket-соединения с клиента. Пример показывает создание конфигурации сессии и постинг на этот эндпоинт.

Чем отличаются WebRTC и WebSocket по среде выполнения?

Документация позиционирует WebRTC как идеальный для браузерных/client-side взаимодействий, а WebSocket — для middle-tier серверных приложений с постоянными низкозадержными сетевыми соединениями.

Какое изменение URL для получения WebRTC SDP?

При инициализации WebRTC-сессии в браузере документация указывает, что URL для получения информации о удалённой сессии через SDP теперь /v1/realtime/calls.

Можно ли использовать Realtime API для транскрипции без полного voice-agent поведения?

Да. Документация специально упоминает realtime audio transcription путём транскрипции аудио-потоков в реальном времени через WebSocket-соединение.

Альтернативы

• Используйте Agents SDK для TypeScript, не строя всё напрямую на Realtime primitives: Это позволит сосредоточиться на оркестрации voice agent, при этом используя Realtime под капотом для подключения в браузере (WebRTC) и на сервере (WebSocket).
• Создайте конвейер транскрипции запрос/ответ вместо стриминга: Если приложению не требуется обработка аудио в реальном времени, workflow не-реального времени избегает событийно-ориентированного подхода сессий, описанного для Realtime.
• Другие подходы к realtime-коммуникации для голоса: Если нужны telephony-специфичные потоки, SIP-интеграция — один из вариантов в методах подключения Realtime; иначе выбирайте между WebRTC (браузер) и WebSocket (сервер) в зависимости от развертывания.
• Мультимодальный чат с non-realtime endpoints: Если требования к задержке менее строгие, чем «low-latency communication», подойдёт подход мультимодального чата не в реальном времени, хотя он не будет следовать стриминговому/событийному workflow сессий из docs Realtime.