Azure OpenAI の gpt-5-chat に reasoning_effort や verbosity を渡すと 400 エラーになる──このトラブルは多くの開発者がつまずく落とし穴です。本稿では結論を最初に示し、Azure AI Foundry 上で「GPT‑5 Reasoning」モデルを正しくデプロイ・呼び出す手順、Chat Completions と Responses API の違い、SDK と REST の具体例、そして回避策を網羅的にまとめます。明日からの実装にそのまま貼り付けられるサンプルと運用ベストプラクティスまで一気通貫で解説します。
結論（最短回答）
- 標準の
gpt-5-chatではreasoning_effort／verbosityは使えません。要求ボディに含めると 400 BadRequest – Unrecognized request argument になります。 - これらのパラメータを使えるのは「GPT‑5 Reasoning」系（例：
gpt-5/gpt-5-mini/gpt-5-pro）を Azure AI Foundry で明示的にデプロイした場合のみです。さらに、verbosityは Responses API のtext.verbosityに設定します（Chat Completions のトップレベルでは効きません）。
なぜ 400「Unrecognized request argument」になるのか
原因は「モデル種別と API 面の不一致」です。gpt-5-chat は通常の会話タスク向けの chat-completion 系モデルであり、推論深度や説明量を直接切り替える reasoning_effort と verbosity を受け付けません（仕様上の未対応）。そのため、要求ボディに未知のキーが混入したと解釈され、Unrecognized request argument が返ります。
対して GPT‑5 の「Reasoning モデル群」は、reasoning_effort（minimal/low/medium/high）と verbosity（low/medium/high）をサポートします。特に verbosity は Responses API の text セクション内で指定する点が要注意です。
対応モデルの見極めかた（ミニマムチェックリスト）
- モデル名に
-chatが付くか：gpt-5-chatは通常会話用。reasoning_effort/verbosityは無効。 - 「Reasoning」系をデプロイしたか：
gpt-5/gpt-5-mini/gpt-5-proなどを AI Foundry からデプロイ（「モデル」カタログで選択）。 - 呼び出し API が正しいか：
verbosityは Responses API のみ（text.verbosity）。Chat Completions ではreasoning_effortのみ。
Azure AI Foundry で「GPT‑5 Reasoning」を有効化する手順
- Azure Portal から AI Foundry（旧 Azure AI Studio 相当）を開く。
- 左ナビの モデル からカタログを開き、GPT‑5（Reasoning 系）を検索。用途に応じて
gpt-5/gpt-5-mini/gpt-5-proを選択してデプロイする。 - デプロイ完了後、エンドポイント URL（例：
https://<resource>.openai.azure.com/openai/v1/）と デプロイ名 を控える。 - 以降のコードで
model="<デプロイ名>"を差し替える。
API 呼び出し設計：Chat Completions vs Responses
Chat Completions（Reasoning モデル向け）
Reasoning モデルを Chat Completions で呼ぶ場合、verbosity は使えず、reasoning_effort のみトップレベルで指定します。トークン上限は max_completion_tokens を使用します（従来の max_tokens は非対応）。また、temperature/top_p などのサンプリング系パラメータは Reasoning では未対応です。
from openai import OpenAI
client = OpenAI(
base_url="https://<resource>.openai.azure.com/openai/v1/",
api_key="<AZURE_OPENAI_API_KEY>",
)
resp = client.chat.completions.create(
model="<gpt-5-mini のデプロイ名>", # ← Reasoning モデルのデプロイ名
messages=[
{"role": "developer", "content": "あなたは手順を分かりやすく短く説明します。"},
{"role": "user", "content": "API ゲートウェイのキャッシュ戦略を要点だけで。"}
],
reasoning_effort="medium", # ← ここは OK（Chat Completions で有効）
max_completion_tokens=1500 # ← Reasoning は max_completion_tokens を使う
)
print(resp.choices[0].message["content"])
補足：一部モデル（例：gpt-5-pro）は reasoning_effort が high のみ等の制約があります。
Responses API（Reasoning + 新機能をフル活用）
verbosity を使うなら Responses API を選びます。設定場所はトップレベルではなく、text.verbosity。推論深度は reasoning.effort に置き場所が変わります。出力量の上限は max_output_tokens です。
from openai import OpenAI
client = OpenAI(
base_url="https://<resource>.openai.azure.com/openai/v1/",
api_key="<AZURE_OPENAI_API_KEY>",
)
resp = client.responses.create(
model="<gpt-5 のデプロイ名>", # ← Reasoning モデルのデプロイ名
input="社内ヘルプデスクの問い合わせ自動分類器の設計手順を、箇条書きで。",
reasoning={"effort": "medium"}, # ← Responses はここ（reasoning.effort）
text={"verbosity": "low"}, # ← Responses はここ（text.verbosity）
max_output_tokens=1200 # ← Responses は max_output_tokens
)
print(resp.output_text)
同じく REST でも input／reasoning／text の 3 ブロックで指定します。
curl -X POST "https://<resource>.openai.azure.com/openai/v1/responses" \
-H "Content-Type: application/json" \
-H "api-key: <AZURE_OPENAI_API_KEY>" \
-d '{
"model": "<gpt-5 のデプロイ名>",
"input": "SLA 監視ダッシュボードの KPI を5つ提案して。",
"reasoning": { "effort": "minimal" },
"text": { "verbosity": "high" },
"max_output_tokens": 800
}'
よくあるつまずき（エラー別チェックリスト）
| 症状 | 原因 | 対処 |
|---|---|---|
Unrecognized request argument: reasoning_effort | gpt-5-chat に Reasoning 用キーを渡している | gpt-5 / gpt-5-mini 等の Reasoning をデプロイして切替える。 |
verbosity を指定しても効果がない | Chat Completions にトップレベルで渡している | Responses API の text.verbosity に移す（Chat Completions では未対応）。 |
| 生成量が切れてしまう | Reasoning で max_tokens を使っている | Chat Completions は max_completion_tokens、Responses は max_output_tokens を使う。 |
温度や top_p が効かない | Reasoning モデルはサンプリング系を未サポート | パラメータを送らない（仕様）。 |
最小思考（minimal）でツール同時呼び出しが失敗 | 並列ツール呼び出し非対応の制約 | minimal を避けるか、直列で設計。 |
動作の違いをひと目で理解：対応表
| 項目 | Chat Completions（Reasoning） | Responses API（Reasoning） |
|---|---|---|
| 入力プロパティ | messages | input |
| 推論深度 | reasoning_effort（トップレベル） | reasoning.effort |
| 出力の詳しさ | 未対応 | text.verbosity（low/medium/high） |
| 出力量上限 | max_completion_tokens | max_output_tokens |
サンプリング系（temperature/top_p 等） | 未対応 | 未対応 |
| 並列ツール呼び出し | 一部制約あり（minimal 時は不可） | 同様 |
※ 仕様の骨子は Reasoning モデルの公式ガイドと Responses API ドキュメントに準拠。
「標準 GPT‑5 を使い続けたい」場合の現実解
どうしても gpt-5-chat を使い続けたい場合は、以下の設計で「それっぽい挙動」を近づけられます。
- System（または Developer）メッセージでスタイルを厳密化：簡潔に・結論先出し・根拠箇条書き などを明示。
- 出力量はトークンで制御：
max_tokens（chat-completion 用）や出力フォーマット（例：字数上限）で縛る。 - レスポンスの後処理：サーバー側で要約フィルタを挟み、「冗長→短文化」する。
# gpt-5-chat を簡潔モードに寄せるケース（疑似的）
resp = client.chat.completions.create(
model="<gpt-5-chat のデプロイ名>",
messages=[
{"role": "system",
"content": "常に短く結論から。箇条書き最大3点。不要な形容は避ける。"},
{"role": "user", "content": "ゼロトラスト導入の最初の3手を教えて。"}
],
max_tokens=600
)
ただし、これは 挙動の誘導 に過ぎず、Reasoning 固有の深い「思考コスト」調整や verbosity のネイティブ挙動とは異なります。正確にコントロールしたいなら Reasoning モデルへの切替が王道です。
実装テンプレート：安全な切替のためのコード差分
NG（標準 gpt-5-chat に Reasoning 用キー）
resp = client.chat.completions.create(
model="<gpt-5-chat のデプロイ名>",
messages=[...],
reasoning_effort="medium", # ← ❌ 未対応
verbosity="low" # ← ❌ 未対応
)
OK（Reasoning + Chat Completions）
resp = client.chat.completions.create(
model="<gpt-5-mini のデプロイ名>", # ← Reasoning
messages=[...],
reasoning_effort="low", # ← ✅
max_completion_tokens=1200 # ← ✅
)
OK（Reasoning + Responses / もっと柔軟）
resp = client.responses.create(
model="<gpt-5 のデプロイ名>",
input="要件定義書の章立てを簡潔に。",
reasoning={"effort": "minimal"}, # ← ✅
text={"verbosity": "low"}, # ← ✅
max_output_tokens=600 # ← ✅
)
モデル別の細かな注意点
gpt-5-pro：思考コストが高い前提で設計されており、reasoning_effortはhigh固定などの制限があります（ドキュメントの注記）。- サンプリング系パラメータ：Reasoning は
temperature/top_p/presence_penalty/frequency_penaltyなど非対応。要求ボディに含めない。 - 最小思考（
minimal）：並列ツール呼び出し非対応。tool_choice設計やフロー分割で回避。
移行・運用ベストプラクティス
1) 開発・テスト
- SDK を最新化：
max_completion_tokens/max_output_tokens、reasoning/textなど新キーに追随するため。 - トグル設計：環境変数やフラグで
gpt-5-chat（標準）と Reasoning を切替可能に。 - プロンプト規約：「短く結論→根拠→次の一手」 などの共通スタイルを System/Developer メッセージで固定。
2) 本番運用
- タイムアウト対策：Reasoning は思考コストがかかるため、待機時間・再試行・バックグラウンド実行の設計を入れる（Responses API のバックグラウンド機能の検討）。
- コスト監視：用途別に
gpt-5-miniやgpt-5-nanoを併用し、重タスクのみgpt-5/gpt-5-proを選ぶ。 - 冪等性：冗長化とタイムアウト時の再取得（Responses の
retrieve）で二重実行を避ける。
3) 観測性
- Reasoning summary を活用し、思考コストの可視化と品質監査（レスポンスに含める設定）。
- ログ整形：入力・出力・トークン内訳（
reasoning_tokensを含む）を採取してダッシュボード化。
トラブルシューティング：実例で学ぶ
ケース A：標準モデルでパラメータが拒否される
事象：gpt-5-chat に reasoning_effort を渡して 400。
解決：Reasoning モデルへ切替。さらに verbosity が必要なら Responses API へ。
ケース B：verbosity が効かない
事象：Chat Completions でトップレベル verbosity を付けても挙動不変。
解決：text.verbosity に移し、Responses API で呼ぶ。
ケース C：出力が途中で途切れる
事象：max_tokens を増やしても改善しない。
解決：Reasoning は max_completion_tokens（Chat）または max_output_tokens（Responses）に置き換える。
ケース D：パラメータの互換性が分からない
対処の型：
- モデルが Reasoning か Chat 専用かを確認（デプロイ名とカタログを照合）。
- 必要機能に応じて API を選択（
verbosityは Responses）。 - 該当 API の 対応パラメータ に合わせてボディを組む。
運用チューニングのコツ
- 速度最優先：
reasoning.effort="minimal"+text.verbosity="low"。要求を細かく分割し、並列処理でカバー。 - 品質最優先：
effort="high"+verbosity="high"だが、コストと待機時間に注意。 - 省コスト：問い合わせの 80% は
gpt-5-mini、難問のみgpt-5/gpt-5-proにフェイルオーバー。 - 安全設計：レスポンス整形ルール（最大見出し数、NG ワードフィルタ、JSON スキーマ制約）を合わせ技で。
FAQ（実務でよく出る疑問）
Q. 標準の gpt-5-chat で reasoning_effort/verbosity を使えるようになる見込みは？
A. 現時点の公式情報では Reasoning モデル群 に紐付く機能として案内されています。要件が確定しているなら、早めに Reasoning への移行前提で設計を固めるのが安全です。
Q. どの API を選ぶべき？
A. 推論深度だけを調整したいなら Chat Completions（reasoning_effort）、説明量もコントロールしたいなら Responses（text.verbosity）。将来の拡張（暗号化済み推論トレースの継承やバックグラウンド実行）を考えると Responses が有利です。
Q. 生成が冗長です。短くできますか？
A. Responses の text.verbosity="low" が最も確実。Chat Completions では System/Developer メッセージで短文化を強制し、ポストプロセスでさらに要約します。
まとめ
gpt-5-chatはreasoning_effort/verbosity非対応。400 エラーは仕様通り。- 使いたいなら Reasoning をデプロイ：
gpt-5/gpt-5-mini/gpt-5-pro。verbosityは Responses API のtextに。 - トークン指定の置換：Chat＝
max_completion_tokens／Responses＝max_output_tokens。サンプリング系は送らない。 - 移行のコツ：デプロイ名の切替、呼び出し面（messages ⇔ input）とパラメータ位置（トップレベル ⇔
reasoning/text）の差分に注目。
付録：最低限の健全性チェック・スクリプト
def sanity_check_request(payload: dict, api: str):
"""
api: 'chat' or 'responses'
"""
if api == "chat":
assert "messages" in payload, "Chat は messages 必須"
assert "input" not in payload, "Chat に input は不要"
# Reasoning: chat では reasoning_effort のみ
assert "reasoning_effort" in payload or True
assert "text" not in payload, "verbosity は Chat では無効"
assert "max_completion_tokens" in payload, "Reasoning は max_completion_tokens を使う"
elif api == "responses":
assert "input" in payload, "Responses は input 必須"
assert "messages" not in payload, "Responses に messages は不要"
# Reasoning: responses では reasoning.effort / text.verbosity
r = payload.get("reasoning", {})
t = payload.get("text", {})
assert isinstance(r, dict) and "effort" in r, "reasoning.effort を指定"
assert isinstance(t, dict) and "verbosity" in t, "text.verbosity を指定"
assert "max_output_tokens" in payload, "Responses は max_output_tokens を使う"
return True
この付録のように、API ごとの必須・禁止プロパティ を静的に検証するだけでも、デグレの大半を事前に防げます。
参考にした公式情報（要点）
- Reasoning モデルの機能・制約（
minimal／verbosity／非対応パラメータ 等）と Chat/Responses の差分。 - Responses API の
reasoning／text.verbosity／バックグラウンド実行／暗号化推論トレース。 - 標準
gpt-5-chatで当該パラメータが拒否される既知事象。 - モデルカタログ上での GPT‑5 系ラインアップ（Reasoning と Chat の区別）。
サンプル（実行順にコピペで検証）
1) Chat Completions（Reasoning Effort のみ）
from openai import OpenAI
client = OpenAI(base_url="https://<resource>.openai.azure.com/openai/v1/", api_key="<KEY>")
resp = client.chat.completions.create(
model="<gpt-5-mini>",
messages=[{"role":"user","content":"CI/CD パイプラインの最小構成を3項目で"}],
reasoning_effort="low",
max_completion_tokens=300
)
print(resp.choices[0].message["content"])
2) Responses（Reasoning + Verbosity）
resp = client.responses.create(
model="<gpt-5>",
input="SRE の当番運用を1週間で立ち上げる手順を。",
reasoning={"effort":"medium"},
text={"verbosity":"low"},
max_output_tokens=400
)
print(resp.output_text)
3) 既存の gpt-5-chat コードに安全パッチ
- response = client.chat.completions.create(
- model="<gpt-5-chat>",
- messages=...,
- reasoning_effort="medium",
- verbosity="low",
- max_tokens=16384
- )
+ response = client.chat.completions.create(
+ model="<gpt-5-chat>",
+ messages=...,
+ max_tokens=16384 # ← 余計なキーは送らない
+ )
実案件での設計指針（テンプレ）
- 要件を二層に分解：「深く考える必要」(
reasoning.effort) と「どれくらい話すか」(text.verbosity) を別軸で最適化。 - モデル選定：既読性・コスト・待機時間を見て
gpt-5-miniをデフォルト、難問時はgpt-5またはgpt-5-pro。 - API 選定：verbosity が要る＝Responses、既存互換重視＝Chat Completions。
- 失敗時のフォールバック：タイムアウト・レート制限に応じて縮小要求（
minimal／low）へ段階的後退。
終わりに
Azure OpenAI で GPT‑5 の reasoning_effort／verbosity を正しく使うには、モデル（Reasoning か否か）とAPI 面（Chat か Responses か）の二点をそろえることがすべてです。ここまでの手順・コード・対応表をそのままプロジェクトに組み込めば、400 エラーに悩まされることなく、深さと詳しさを自在にコントロールできます。
コメント