OpenAI Realtime APIのイベントをまとめてみた
OpenAI Realtime APIは、WebRTCを利用したリアルタイム音声対話を実現するための強力なAPIですが、関連するイベントやフローが多岐にわたり、ドキュメントだけでは理解が難しい部分があります。
この記事では、Realtime APIの主要なイベントの種類とフローをまとめてみました。
WebRTCの基本的な接続フロー
まず、OpenAI Realtime APIの基盤となるWebRTCの接続フローと主要な機能について見ていきましょう。
以下の図では、セッションの初期化からP2P接続の確立、音声処理の流れまでを視覚的に解説しています。
OpenAI Realtime API イベントフロー
WebRTCセッション初期化フロー:
REST API呼び出し
POST /v1/realtime/sessions
セッションオブジェクト
client_secret付き
↓ WebRTCで接続
WebRTC接続パラメータ
- modalities: ["audio", "text"] - 応答可能なモダリティ
- model: 使用するRealtimeモデル
- instructions: モデルへの指示（システムメッセージ）
- voice: 音声タイプ（alloy, ash, ballad等）
- input_audio_format: pcm16, g711_ulaw, g711_alaw
- output_audio_format: pcm16, g711_ulaw, g711_alaw
- turn_detection: 発話検出設定（server_vad等）
WebRTC特有の機能
- 低遅延の双方向リアルタイム音声通信
- 自動的な音声活動検出（VAD）
- ネットワーク状態に応じた適応型ビットレート調整
- エコーキャンセリングとノイズ抑制
- ブラウザ内でのネイティブメディア処理
WebRTC接続フロー (6)
シグナリングプロセス
- REST API認証
クライアントがREST APIを呼び出し、ephemeralトークンを取得
- RTCPeerConnection作成
クライアント側でWebRTC接続オブジェクトを初期化
- オファー生成と送信
クライアントがSDPオファーを作成し、サーバーに送信
- アンサー受信と設定
サーバーからSDPアンサーを受信し、ローカル接続に適用
- ICE候補交換
接続候補情報を交換し、最適な接続経路を確立
- 接続確立
接続状態が「connected」に変わり、メディア転送開始
WebRTCシグナリングと通信フロー
WebRTC技術情報
対応モデル:
gpt-4o-realtime-preview-2024-12-17
gpt-4o-mini-realtime-preview-2024-12-17
WebRTCの接続フローは以下のような順序で進行します：
- REST APIによるセッション作成とクライアントシークレットの取得
- WebRTCシグナリングプロセスの開始
- OpenAI Realtime APIとの接続確立
- 音声ストリームの送受信開始
Realtime APIのイベントフロー
次に、OpenAI Realtime APIで利用可能な具体的なイベントについて詳しく見ていきます。
主にサーバーから送られてくるイベントをアプリケーションでハンドリングしていくことになります。
OpenAI Realtime API イベントフロー
初期接続時の自動イベント:
セッション関連イベント (1)
セッション設定の更新
オーディオ関連イベント (5)
会話アイテム関連イベント (5)
レスポンス関連イベント (2)
その他の重要なイベント
まとめ
このあたりの情報とフローを頭に入れておくと、OpenAI Realtime APIを使った開発がスムーズに進むと思います。
本記事ではOpenAI Realtime API公式ドキュメント を参考に、イベントフローや接続プロセスを図解しています。公式ドキュメントでは技術的な詳細が記載されていますが、本記事ではより視覚的に理解しやすい形で整理しました。