GPT-6.2 Responses API:プレフィックスを変更するとreasoningが破棄される仕組みと対策
GPT-6.2 AstraとSol以降、Responses APIで過去の会話履歴を書き換えると、その後のreasoning項目が破棄されます。追記専用のinput履歴、configuration_update、additional_tools、先頭のdeveloperメッセージによる指示分離を採用し、input_transformationsとPrompt Cache Diagnosticsで動作を検証する手順を解説します。
目次

gpt-6.2-astraとgpt-6.2-sol以降、OpenAIのResponses APIでは、会話の途中でプレフィックスを書き換えたり、モデルをダウングレードしたり、組織またはエンドユーザーを変更したりすると、その後に続くreasoning項目が破棄されます。過去のdeveloperメッセージを書き換える処理や、以前のツール実行結果を短縮する処理、ターン間でトップレベルのreasoning.effortやtoolsを書き換える実装を行っている開発者やエージェント開発チームは、すべてこの仕様変更の影響を受けます。既存の実装を追記専用(append-only)のinput履歴に切り替え、会話途中の設定変更にはconfiguration_updateとadditional_toolsを使い、毎回のレスポンスでinput_transformationsを確認してreasoningが除外されていないか検証してください。
GPT-6.2のResponses API呼び出しに使う経路を選ぶ
GPT-6.2 AstraとSolはテキスト生成に限ればChat Completionsにも対応していますが、ツール呼び出しにはResponses APIが必要です。また、プレフィックスを保護するための機能(configuration_update、additional_tools、input_transformations)もResponses API専用の仕組みです。そのため、POST /v1/responsesを提供しており、ご自身のアクセス環境と課金条件に合うAPI経路を選んでください。
| 経路 | 利用条件 | 課金単位 | Responses APIの注意点 | 選ぶ目安 |
|---|---|---|---|---|
| BetterToken APIゲートウェイ | BetterTokenアカウント、コンソール発行のAPI Key、従量課金残高(購入した有料残高は月次リセットされません) | 対象モデルの現在の課金単位(入力・出力・キャッシュのトークンで単価やルールが異なる場合があります)。詳しくは現在の料金を参照してください | https://www.bettertoken.ai/v1(POST /v1/responses)でgpt-6.2-astraとgpt-6.2-solを提供しています。導入前にご自身のキーでステートレスなstore: falseリプレイ、configuration_update、input_transformationsの透過動作を検証してください | 利用可能な各モデルを1つの従量課金API Keyで使いたい場合、またはOpenAI直接課金を利用できない場合 |
| OpenAI API直接利用 | 対応国・地域にあるOpenAIアカウントとAPI課金設定 | 入力、キャッシュ済み入力、キャッシュ書き込み、出力の各1Mトークン単位 | configuration_update、input_transformations、prompt_cache_diagnostics、previous_response_id、バックグラウンドの完了ウィンドウ、組織単位のZero Data Retention(ZDR)へのネイティブ対応が公式ドキュメントに記載されています | OpenAIに直接アクセスでき、OpenAI側での状態保持、ZDR、または公式ドキュメント記載のベータ機能に依存する場合 |
BetterToken経由で追記専用リプレイとプレフィックス検知を検証する
BetterTokenは、BetterTokenコンソールで発行したAPI Keyで認証するhttps://www.bettertoken.ai/v1(POST /v1/responses)のOpenAI互換API経路を提供しています。2026-11-21時点で、Responsesエンドポイントの対象モデルとしてgpt-6.2-solとgpt-6.2-astraの両方が掲載されています。なお、BetterTokenはマルチモデル対応のプラットフォーム兼APIアクセス層であり、OpenAIの公式製品ではありません。また、BetterTokenのResponses APIリファレンスでは、ステートレスなstore: falseによる暗号化reasoningリプレイ、configuration_update、input_transformations、prompt_cache_diagnosticsの透過動作は検証済みとして記載されていません。本番環境へ組み込む前に、ご自身のAPI Keyを使って次の2ターン比較検証をステートレス実行してください。
まず、BashでBetterTokenのAPI Keyを画面に表示せずに環境変数へ設定します。
read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
次に、store: falseを指定して1ターン目を送信し、encrypted_contentを含むreasoning項目が少なくとも1件返ることを確認します。そのうえで、履歴をそのまま追記するステートレスなリプレイと、先頭のdeveloperメッセージだけを書き換えた対照リクエストを並べて比較します。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["BETTERTOKEN_API_KEY"],
base_url="https://www.bettertoken.ai/v1",
timeout=120.0,
max_retries=0,
)
model = "gpt-6.2-sol" # Or "gpt-6.2-astra"
history = [
{"role": "developer", "content": "You are a backend reviewer. Give concise engineering answers."},
{"role": "user", "content": "Draft a two-step plan to add a non-blocking index on PostgreSQL."},
]
first = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=history,
)
reasoning_items = [item for item in first.output if item.type == "reasoning"]
if not reasoning_items:
raise RuntimeError("Turn 1 returned no reasoning items; use a harder prompt or higher effort.")
if not all(getattr(item, "encrypted_content", None) for item in reasoning_items):
raise RuntimeError("Stateless replay unverified: Turn 1 reasoning items lack encrypted_content.")
reasoning_ids = [item.id for item in reasoning_items]
first_output = [item.to_dict() for item in first.output]
follow_up = {"role": "user", "content": "List the failure modes and rollback steps for step 2."}
append_only = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*history, *first_output, follow_up],
)
edited_history = [{**history[0], "content": history[0]["content"] + " Be brief."}, history[1]]
edited_control = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*edited_history, *first_output, follow_up],
)
print("reasoning_ids:", reasoning_ids)
print("append_only:", append_only.status, getattr(append_only, "input_transformations", None))
print("edited_control:", edited_control.status, getattr(edited_control, "input_transformations", None))
print("append_only_cached_tokens:", append_only.usage.input_tokens_details.cached_tokens)
本番導入の前に、次の4つの結果を必ず読み取ってください。
status == "completed"は、リクエストが受理されて正常終了したことだけを示します。ゲートウェイがターンをまたいでreasoningを保持した証明にはなりません。store: falseで送信した1ターン目が空でないreasoning_idsを返し、すべてのreasoning項目にencrypted_contentが含まれていることを確認してください。ゲートウェイがencrypted_contentを省略している場合、2ターン目で暗号化済みreasoningトークンを上流へ引き継げないため、ステートレスなリプレイは未検証として扱ってください。- 2ターン目の2つの呼び出しで
input_transformationsを比較します。透過動作が正常であれば、edited_control側にはreasoning_idsのいずれかのIDに一致するprefix_mismatch項目が記録され、append_only側には記録されません。両方の実行結果でinput_transformationsがNoneまたは空になる場合、ゲートウェイがこのフィールドを転送していない可能性があるため、検証結果は判定不能として扱ってください。 configuration_updateの透過動作は、プレフィックス検証とは別に確認してください。text.formatの更新については、別の2ターン目リクエストでtext.formatを厳格なJSONスキーマへ切り替え、出力がそのスキーマに一致するか確認することで検証できます。一方、OpenAIの仕様では会話途中のreasoning.effort変更が適用されたかを確認するレスポンスフィールドが定義されておらず、レスポンス側のreasoning.effortには引き続きリクエストレベルの値が返ります。そのため、BetterToken経由でのreasoning.effort向けconfiguration_updateは未検証として扱ってください。
プロンプトキャッシュについて、OpenAIはGPT-5.6以降のモデルでキャッシュ対象となる最小プレフィックス長を1,024可視入力トークンという適用条件に定めています。再利用可能なプレフィックスがこのしきい値に達したら、append_only.usage.input_tokens_details.cached_tokensを確認して実際のキャッシュ再利用数を計測してください。利用規模を拡大する前に、現在の料金で最新のモデル単価とキャッシュ条件を確認しておくことをおすすめします。
OpenAIを直接呼び出す場合は、base_urlを省略してOPENAI_API_KEYを設定し、OpenAI公式のKeep the prefix unchangedガイドに従ってください。
GPT-6.2でプレフィックス変更とみなされる操作
あるreasoning項目にとってのプレフィックスとは、その項目より前に配置された会話履歴全体を指します。GPT-6.2では、その先行履歴に手を加えると、変更箇所より後に現れるreasoning項目をAPI側が破棄します。
OpenAIのドキュメントでは、プレフィックス変更を次の2種類に分類しています。
- 過去の
input項目の編集:ツール実行結果の短縮、developerメッセージの書き換え、過去に送信した画像やファイルの縮小、古いターンを要約文へ置き換える操作などが該当します。 - ターン間でのリクエストレベルパラメータの変更:
toolsの更新(追加、削除、並び替え、スキーマや説明文の編集)、text.formatの変更、トップレベルのreasoning.effortの変更、さらにGPT-6.2より前のモデルでのinstructions変更が含まれます。
OpenAIのReasoningガイドによると、GPT-6.2以降でprefix_mismatchが発生するのは、reasoning項目より前の位置に内容を挿入または編集したときです。残りの項目を書き換えずに項目全体を丸ごと削除する操作や、reasoning項目より後に新しい項目を追記する操作だけでは、prefix_mismatchは発生しません。ただし、古いターンを削除するとプロンプトキャッシュの再利用率が下がる可能性があり、その変更によってキャッシュ再利用が妨げられた場合、Prompt Cache Diagnosticsはinput_changedを報告することがあります。
プレフィックス編集は、input_transformationsで報告される5種類の除外理由の1つです。
除外理由(reason) | APIがreasoning項目を除外する条件 |
|---|---|
prefix_mismatch | GPT-6.2以降で、対象のreasoning項目より前に内容が挿入または編集された場合 |
end_user_mismatch | GPT-6.2以降で、生成時と再利用時のリクエスト間でsafety_identifierが異なる場合(片方だけ省略した場合も含みます) |
model_mismatch | 異なるモデルファミリーへ切り替えた場合、または同一ファミリー内で下位モデルへダウングレードした場合(同一ファミリー内の上位モデルへのアップグレードであれば、他の条件を満たす限り互換性のあるreasoningが保持されます) |
organization_mismatch | 別の組織で生成された項目、または別ユーザー配下の異なるワークスペースで生成された項目を再利用した場合 |
turn_boundary | モデルが現在ターンのreasoningのみを使う構成で、項目が以前のターンに属している場合(対応モデルではreasoning.contextで対象範囲を制御できます) |
reasoning項目が破棄されると何が起きるか
Responses APIでは、reasoning項目がモデルへの入力から除外されてもリクエスト自体は完了することがあります。そのため、レスポンスのinput_transformationsを確認しない限り、reasoningの欠落に気づけません。会話途中のプレフィックス編集は、本番環境で次の2つの悪影響を引き起こします。
- reasoning破棄による影響:reasoning項目が除外されると、モデルは以前の推論をやり直さなければならなくなる場合があります。その結果、トークン消費量、コスト、応答遅延が増え、失われた推論をモデルが再現できない場合は出力品質も低下する恐れがあります。
- キャッシュ対象プレフィックス変更による影響:プロンプトキャッシュはリクエストの先頭から一致判定を行うため、プレフィックスを書き換えると編集箇所以降のキャッシュ再利用が途切れる場合があります。その結果キャッシュミスが起きると、入力コストや応答時間が増える可能性があります。
2026-11-21時点でOpenAIが公開しているStandard単価(入力272,000トークン以下)を見ると、キャッシュミスが積み重なったときの差は明確です。
- GPT-6.2 Astra(
gpt-6.2-astra):キャッシュ済み入力が$0.40/1Mであるのに対し、非キャッシュ入力は$8/1M(30分保持のキャッシュ書き込みは$10/1M、12時間保持のキャッシュ書き込みは$20/1M)、出力は$40/1Mです。 - GPT-6.2 Sol(
gpt-6.2-sol):キャッシュ済み入力が$0.10/1Mであるのに対し、非キャッシュ入力は$2/1M(30分保持のキャッシュ書き込みは$2.50/1M、12時間保持のキャッシュ書き込みは$5/1M)、出力は$10/1Mです。
入力が272,000トークンを超えると、OpenAIはリクエスト全体に対して入力単価とキャッシュ単価を2倍にし、出力には短コンテキスト時の単価の1.5xを課金します。安定したプレフィックスで12時間キャッシュ書き込みが採算に合う条件については、OpenAIの12時間プロンプトキャッシュ解説もあわせて参照してください。
プレフィックスを壊さずにパラメータとコンテキストを更新する
過去の履歴を直接書き換える処理をやめ、追記専用の項目へ置き換えることで、ターンをまたいでもreasoningとキャッシュ済みプレフィックスを維持できます。
configuration_updateでreasoning.effortとtext.formatを変更する
トップレベルのreasoning.effortを途中で変更すると、内部の非公開システム指示が書き換わることがあります。対応するGPT-6以降のモデルを標準の単一エージェントモードで使う場合は、リクエストレベルのreasoning.effortとtext.formatを最初の値のまま固定し、次のユーザーメッセージの直前にconfiguration_update項目をinputへ追記してください。
{
"type": "configuration_update",
"reasoning": {
"effort": "high"
},
"text": {
"format": {
"type": "json_schema",
"name": "migration_checks",
"strict": true,
"schema": {
"type": "object",
"properties": {
"safe": { "type": "boolean" },
"rollback_sql": { "type": "string" }
},
"required": ["safe", "rollback_sql"],
"additionalProperties": false
}
}
}
}
configuration_updateを使うときは、次の5つのルールを守ってください。
configuration_updateで指定した設定は、別の更新項目で上書きされるまで後続ターンにも継続して適用されます。reasoning.effortだけを更新しても以前のtext.format設定は維持され、逆の更新でも同様です。- レスポンスオブジェクトの
reasoning.effortには、更新後の値ではなくトップレベルのリクエスト値が引き続き返されます。 - 更新内容を引き継ぐには、
previous_response_idを使うか、inputを手動管理している場合は各configuration_update項目を元の位置のまま再送してください。 - 自動トランケーションおよび単体の
/responses/compactエンドポイントは、configuration_update項目を含む履歴を受け付けません。代わりにcontext_managementまたはcompaction_triggerを使用してください(手順は後述のコンテキスト圧縮の節で説明します)。 gpt-6.2-astraとgpt-6.2-solはいずれもreasoning.effort: "none"を拒否します。OpenAIのUsing GPT-6.2ガイドでは、初期値としてmediumを使い、これまでnoneやminimalを使っていた場合は代わりにlowを選ぶよう推奨しています。
toolsを書き換えずにツールの追加や制限を行う
リクエストレベルのtools配列、各スキーマ、および並び順はターン間で変更しないでください。呼び出し可能なツールを調整するには、プレフィックスを壊さない次の3つの方法を使います。
- 1ターンだけツール呼び出しを無効にする場合は、
toolsを削除せずtool_choiceに"none"を指定します。 - 1ターンだけ呼び出し可能なツールを絞り込む場合は、
tool_choiceでallowed_toolsを指定します。
{
"tool_choice": {
"type": "allowed_tools",
"mode": "auto",
"tools": [
{ "type": "function", "name": "get_weather" },
{ "type": "function", "name": "search_docs" }
]
}
}
- 会話の途中でツールを追加したい場合は、
developerロールのadditional_tools項目を追記するか、defer_loading: trueを指定したtool searchを使って、見つかったツール定義がコンテキスト末尾へ追記されるようにします。additional_tools内のツールはその項目が入力内に現れた後からのみ呼び出し可能になるため、手動リプレイ時も元の位置に保持してください。
{
"type": "additional_tools",
"role": "developer",
"tools": [
{
"type": "function",
"name": "get_customer",
"description": "Look up a customer by ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
}
再利用可能なdeveloperメッセージとトップレベルinstructionsを分ける
GPT-6.2以降、OpenAIはトップレベルのinstructionsをinputの後ろ、すなわちキャッシュのブレークポイント対象外の位置へ追加します。そのため、内容が変わっていなくてもリクエストごとに非キャッシュ入力単価で課金され、previous_response_idを使っても引き継がれません。
指示のスコープに応じて配置先を次のように分けてください。
- 再利用するシステムプロンプトや共通ポリシーは、プロンプトキャッシュが一致できるよう、
inputの先頭項目としてdeveloperメッセージに配置します。 - 会話途中で再利用可能な指示を更新したいときは、先頭の
developerメッセージを書き換えず、新しいdeveloperメッセージをinputの末尾に追記します。 - トップレベルの
instructionsは、そのリクエスト1回だけに適用する指示に限定して使います。
コンテキスト圧縮と長いツール出力を扱う
長大なツール出力の短縮や、画像・ファイルのサイズ削減は、初めてモデルへ送信する前の段階で済ませてください。すでに送信した過去の項目を後から切り詰めてはいけません。
コンテキスト圧縮(compaction)を行うとプレフィックスが変わるため、キャッシュミスの発生自体は避けにくくなります。長いセッションを扱う場合、OpenAIのCompactionガイドでは次の2つの経路が案内されています。
- 自動圧縮(
compact_thresholdを指定したcontext_management):プレフィックスが変化しても、OpenAI側が後続のreasoning項目を保持します。以前のターンにconfiguration_update項目が含まれている場合、APIはcompaction項目の直後に新しいconfiguration_updateを1件出力し、additional_toolsの宣言は暗号化された圧縮項目内に保存します。返却された出力項目をそのままの順序で再送してください。 - 明示的圧縮または独自圧縮:単体の
/responses/compactはconfiguration_update項目を含む履歴を拒否します。また、/responses/compactを呼び出すときはinstructionsを省略し、返されたウィンドウを元の順序で次のリクエストへ渡す必要があります。履歴にconfiguration_updateが含まれる場合は、代わりに/responsesリクエスト内へcompaction_trigger項目を含め、圧縮後に変更した各設定をあらためて宣言する新しいconfiguration_updateを次のユーザーメッセージの前に追記してください。独自の圧縮方式を使う場合は、古いターンをその場で置き換えるのではなく圧縮済み要約をコンテキスト末尾に配置するか、その後のreasoning項目が破棄されるトレードオフを受け入れる必要があります。
input_transformationsとPrompt Cache Diagnosticsでプレフィックス保持を検証する
レスポンスの確認には2つの仕組みを組み合わせてください。1つは除外されたreasoning項目を特定するため、もう1つはプロンプトキャッシュの再利用が途切れた原因を調べるために使います。
1. 毎回のレスポンスでinput_transformationsを確認する
Responses APIのcreateリファレンスでは、input_transformationsは{id, action, reason, type}オブジェクトからなる任意配列として定義されており、入力から除外されたreasoning項目が入力順に並びます(actionは"removed"、typeは"reasoning"です)。reasonが"prefix_mismatch"だった場合、idを過去のレスポンスのoutputにあるreasoning項目と照合して除外された項目を特定し、その項目より前の履歴を比較して変更箇所を調べてください。
2. comparison_response_idでPrompt Cache Diagnosticsを実行する
usage.input_tokens_details.cached_tokensが想定より少ない原因を調べるには、同じ組織内で直近に完了したレスポンスを選び、そのidをprompt_cache_options.comparison_response_idへ渡してprompt_cache_diagnosticsを確認します。
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}
OpenAIのPrompt cache diagnosticsガイドによると、prompt_cache_diagnostics.typeにはcache_hit、cache_miss、comparison_response_not_found、unavailableのいずれかが返ります。cache_missの場合はreasonとcache_missed_tokens(再利用されなかった推定トークン数)が返され、比較元の再利用可能プレフィックスの生のトークン数を示すcomparison_reusable_tokensが含まれることもあります。キャッシュミスの原因はreasonで次のように分類されます。
input_changed:developerメッセージへのタイムスタンプやリクエストIDの追加、過去ターンの編集・並び替え・削除など、先行入力が変更されました。tools_changed:ツールの追加、削除、並び替え、または定義の編集が行われました。reasoning_effort_changedまたはtext_format_changed:configuration_updateを使わずに、トップレベルのreasoning.effortまたはtext.formatを変更しました。model_changed、service_tier_changed、verbosity_changed、prompt_cache_key_changed:モデル選択、サービスティア、詳細度、またはキャッシュキーが変更されました。context_compacted:コンテキスト圧縮によって過去の会話内容が置き換わりました。
診断機能には次の5つの制限があります。利用にはGPT-5.6以降のモデルと1,024トークン以上の再利用可能なプレフィックスが必要です。報告されるのは最初に分類された1件の原因のみで、ベストエフォートベースの結果です。追加料金はかからずZero Data Retentionでも利用できます。stream=Trueのときはresponse.completedイベント内のevent.responseからprompt_cache_diagnosticsを読み取ります。また、この診断ではモデルが実際にreasoningを再利用したかどうかは検証できません。
カスタムAPIやゲートウェイ構成で確認すべき4つのポイント
カスタムAPIのベースURLや複数上流を持つゲートウェイ経由でGPT-6.2を利用するチームは、次の4点を確認してください。
- Chat Completionsではなく
POST /v1/responsesを呼び出す:GPT-6.2 AstraとSolはテキスト生成でChat Completionsに対応していますが、ツール呼び出し、configuration_update、additional_tools、input_transformationsを使うにはResponses APIが必須です。基本的な移行チェックリストは、GPT-6 AstraのResponses API移行ガイドにまとめています。 previous_response_idだけに頼らず、追記専用の完全なinput配列を再送する:BetterTokenのスマートルーティングは現在利用可能な上流チャネルへリクエストを振り分け、複数の上流が設定されたモデルでは対象エラーやタイムアウト発生時にフェイルオーバーできます(すべてのモデルに複数上流があるわけではなく、すべてのエラーでフェイルオーバーが発動するわけでもなく、成功を保証するものではありません)。ステートレスなリプレイを行えば、特定の上流に紐づくサーバー側状態への依存を避けられます。OpenAI APIにおけるZero Data Retention(ZDR)は、承認された組織が対象エンドポイントと機能で有効化する組織単位の設定であり、リクエストごとにstoreをfalseにする指定とは別物です。ただし、store: falseまたはZDR有効組織(OpenAI側でstoreがfalseとして扱われます)のいずれのステートレスモードでも、output内のreasoning項目には既定でencrypted_contentが含まれます。OpenAIは互換性のため従来のinclude: ["reasoning.encrypted_content"]も引き続き受け付けますが、指定は必須ではありません。返却されたすべてのoutput項目を元の順序で再送し、end_user_mismatchを防ぐためにsafety_identifierを全ターンで一致させる(または全ターンで省略する)とともに、input_transformationsでorganization_mismatchが出ていないか監視してください。- 未対応のサンプリングパラメータを省略する:
gpt-6.2-astraおよびgpt-6.2-solへのResponses呼び出しでは、トップレベルのtemperature、top_p、top_logprobsパラメータを省略し、includeからはmessage.output_text.logprobsのみを取り除いてください。 - バックグラウンドの完了ウィンドウはOpenAI直接呼び出しに限定する:OpenAIのResponses APIでは、GPT-6.2 AstraとSolは
service_tier: "flex"に対応していません。OpenAI APIを直接呼び出す長時間タスクでは、Responses APIのcompletion_windowガイドで解説しているバックグラウンドモードの2時間または8時間完了ウィンドウ(パブリックベータ)を利用してください。バックグラウンド完了ウィンドウはBetterTokenの公開Responses APIドキュメントでは未検証のため、この機能に依存するワークロードでは事前に動作を確認するか、OpenAIへ直接ルーティングしてください。