OpenAI Realtime API の unknown_parameter で設定が全部消える

2026/8/22更新: 2026/10/12Web開発者向け

OpenAI の Realtime API で、日本語で実況するキャラクターを動かしています。昨日まで日本語で喋っていた AI が、今日は突然こう言って登場しました。

Hey there! What would you like to talk about?

英語で、声も違い、人格の指示もすべて消えた素のアシスタントです。コードの差分は、設定にフィールドを一つ足しただけでした。

実測: 未知のパラメータ 1 つで session.update が丸ごと拒否される

画面のデバッグログに、こんなエラーイベントが出ていました。

type: invalid_request_error
code: unknown_parameter
param: session.max_response_output_tokens

max_response_output_tokens は、ベータ時代の Realtime API で応答のトークン数を制限するフィールドの名前です。当時の情報を元にそのまま足したのですが、GA の session オブジェクトではこの名前は受理されませんでした。

拒否されたのはこのフィールドだけでなく、`session.update` 全体でした。同じ session.update に入れていた人格の指示、声、VAD の設定、転写言語が全部適用されずにセッションが初期状態のまま始まったので、英語の素のアシスタントが出てきました。

さらに、このエラーは画面のログにしか出ていませんでした。永続化していたログは会話の内容と音声の状態だけで API のエラーイベントを書き出していなかったので、何が起きたかを追う前に、まず「エラーが出ていたこと」に気づくまで時間がかかりました。

設定が反映されないとき、私は「そのフィールドだけが無視されている」と思い込んでいました。実際には、session.update は一つでも受理できないフィールドがあると全体が拒否されます。

全体が拒否されると、症状から原因にたどり着けません。人格が消えた、声が違う、言語が違うという症状は、どれも「足したフィールド」とは無関係に見えるからです。

適用を待ってから始める。 session.update を送ったら、サーバーからの session.updated イベントで設定が反映されたことを確認してから会話を開始する。session.updated が来ずにエラーが来たら、接続自体を失敗させる。素の状態で始まるよりも、始まらない方がましです
API のエラーイベントは必ず永続ログに書く。 画面のログは見ていないと消えます
新しいフィールドはデプロイ前に実キーで受理を確認する。 名前が合っているかどうかは、送ってみないと分かりません

session.update 全体が拒否されるというのは、私の構成での観察です。API の仕様として保証されている挙動かどうかは確認できていません。ただ、受理されたかどうかを session.updated で確認する設計にしておけば、どちらであっても設定が適用されないまま会話が始まることはありません
この事故で、「人格が消えた状態」で走っていたテスト 2 回分のデータが無効になりました。計測の前にどのビルド（コミット SHA）とどの設定で走ったかを記録しておくべきでした。記録がなかったので、どこまでのデータが有効かを遡って判定することもできませんでした

設定が適用されたかは session.updated が返ったかで判定する。返らなければ接続を失敗させる
API のエラーイベントは永続ログに書く。特に接続直後のイベントは、見ている人がいない時間帯に出る
設定が反映されない時は、そのフィールドだけが無視されている場合と session.update 全体が拒否されている場合の両方を疑う。全体が拒否されると、症状が設定内容と無関係に見える
計測データには、ビルドの SHA と設定内容を一緒に記録する

設定を一行足しただけで人格が消えたのは、拒否されたかを確認せずに会話を始めていた設計の問題でした。「送った」と「適用された」は別の状態です。