Claude Opus 5のeffortパラメータ完全ガイド：コスト、推論、移行時の400エラーを実装で検証する
2026年7月24日のClaude Opus 5リリースでは、多くの記事が「コストと機能の切り替え」に触れていました。しかし、具体的に何を切り替えるのか、レベルごとの差、料金・レイテンシへの影響、移行時の互換性までは説明されていません。実際に制御するのは、Messages APIのoutput_config.effortパラメータです。Opus 5には5段階のレベルがあり、デフォルトはhighです。また、Opus 4.8からレベルの意味が再調整されているため、既存設定をそのまま移行すると期待した性能・コストにならないほか、一部の組み合わせでは400エラーになります。
💡 読みながら実際のエンドポイントに対してレベルを試したい場合は、Apidogで同じリクエストを5つの設定で送信し、応答・トークン数・レイテンシを比較できます。
effortパラメータの正体
effortは、Messages APIリクエストのoutput_configオブジェクトに指定します。
{
"model": "claude-opus-5",
"max_tokens": 8192,
"output_config": { "effort": "high" },
"messages": [
{
"role": "user",
"content": "Refactor this module and explain the tradeoffs."
}
]
}
effortは、モデルが最終回答を生成する前に使用する内部推論の予算を制御します。
-
effortが高いほど、推論トークンが増えやすい - 推論トークンが増えるほど、出力側のコストとレイテンシが増える
-
effortが低いほど、推論・コスト・レイテンシを抑えられる
一般向けUIでは「effortセレクター」や「コスト対機能の切り替え」として見えることがありますが、API実装ではこのJSONフィールドが実体です。
リクエスト全体の形式はClaude Opus 5 APIウォークスルー、パラメータの参照情報はAnthropicのモデル概要を確認してください。
effortで制御できないもの
effortは表示される回答の長さを直接制御しません。
AnthropicのOpus 5プロンプトガイドによると、effortを下げると内部思考は短くなりますが、最終出力が短くなるわけではありません。
短い回答が必要な場合は、effort: "low"に頼るのではなく、プロンプトで明示します。
回答は箇条書き5項目以内にしてください。
コード例は必要な差分だけを示してください。
5つのeffortレベル
| レベル | 動作 | 一般的な用途 |
|---|---|---|
low |
回答前の推論が最小限 | 大量分類、抽出、ルーティング、短い要約 |
medium |
適度な推論 | 取得済みコンテキストに基づくQ&A、単一ファイル編集、構造化変換 |
high |
デフォルト。かなりの推論 | まだ評価していない汎用タスク |
xhigh |
拡張された推論 | コーディング、エージェントループ。Anthropicが推奨する開始点 |
max |
最大の推論予算 | 誤答コストがトークンコストを大きく上回る難しいワンショット問題 |
実装時に重要なのは、次の2点です。
1. デフォルトはhigh
output_configを送らない場合でも、Opus 5ではhighが適用されます。
{
"model": "claude-opus-5",
"max_tokens": 8192,
"messages": [
{
"role": "user",
"content": "Classify this support ticket."
}
]
}
上記のリクエストは、effort: "high"相当で実行されます。
これはOpus 4.8からの重要な変更です。Opus 4.8では、未変更のリクエストで思考が実行されないケースがありましたが、Opus 5ではデフォルトで実際の推論作業が発生します。そのため、未変更の移行でも出力側の使用量と請求額が変わる可能性があります。
この点はOpus 4.8からOpus 5への移行ガイドで確認してください。
2. コーディングではまずxhighから測定する
コーディングやエージェント的なワークロードでは、最初からmaxにするのではなく、xhighから始めます。
{
"model": "claude-opus-5",
"max_tokens": 64000,
"output_config": { "effort": "xhigh" },
"messages": [
{
"role": "user",
"content": "Fix the failing integration test and explain the root cause."
}
]
}
maxは難しいワンショット問題向けです。効果を計測せずに使うと、性能差が見えないまま余分な推論コストを負担する可能性があります。
Opus 4.8から移行する場合：レベルを再利用しない
Anthropicは、Opus 5で各effortレベルの意味を再調整しています。
つまり、Opus 4.8でのmediumと、Opus 5でのmediumは同じ推論量を意味しません。既存の設定をそのままコピーするのではなく、Opus 5上で改めてレベルを比較してください。
特に重要なのは、Opus 5ではlowとmediumが以前より強化されている点です。従来は真剣な本番タスクでhigh以上を選ぶケースが多かったとしても、Opus 5では分類・抽出・変換などのワークロードをlowまたはmediumで満たせる可能性があります。
Opus 5の料金は、入力100万トークンあたり5ドル、出力100万トークンあたり25ドルで、Opus 4.8と同じです。推論トークンは出力側として計上されるため、不要な推論を減らせれば出力コストの削減につながります。
料金表、50%のバッチ割引、512トークンのキャッシュ最小値はOpus 5料金内訳を参照してください。
単一エンドポイント以外も含めた最適化は、Claude APIの請求額を削減するための手段も役立ちます。
max_tokensとxhigh・maxの関係
max_tokensは、表示される回答だけの上限ではありません。内部の思考トークンと最終出力トークンを合計した上限です。
高いeffortでは、モデルが回答前の推論により多くのトークンを使う可能性があります。思考を使わないモデル向けの小さなmax_tokensを維持したままxhighやmaxを使うと、推論予算によって出力枠が不足し、回答が途中で切れることがあります。
xhighまたはmaxを使う場合、Anthropicのガイダンスではmax_tokens: 64000から開始します。
{
"model": "claude-opus-5",
"max_tokens": 64000,
"output_config": { "effort": "xhigh" },
"messages": [
{
"role": "user",
"content": "Fix the failing integration test and explain the root cause."
}
]
}
max_tokensは上限であり、予約購入ではありません。実際に生成されたトークンに対して課金されるため、上限を64000にしても、常に64000トークン分の料金が発生するわけではありません。
thinking: disabledとxhigh・maxを同時に使うと400エラーになる
以下の組み合わせは無効です。
{
"model": "claude-opus-5",
"max_tokens": 8192,
"thinking": { "type": "disabled" },
"output_config": { "effort": "xhigh" }
}
このリクエストは400エラーになります。
理由は単純で、思考を無効にしながら高い推論予算を要求しているためです。thinking: { "type": "disabled" }を指定すると、利用できるeffortはhigh以下に制限されます。
有効な組み合わせは次のとおりです。
- 思考が有効な状態（デフォルト）:
low、medium、high、xhigh、max - 思考が無効な状態:
low、medium、highのみ
移行時に起きやすいパターンは、Opus 4.8の設定からthinking: { "type": "disabled" }を残したまま、コーディング用にeffortだけをxhighへ変更するケースです。
Opus 5では、コスト制御のために思考を無効化するのではなく、低いeffortを指定する方法が推奨されています。思考を無効化すると、ツール呼び出しがプレーンテキストとして出力されたり、内部XMLタグが回答に混入したりする場合があります。
詳細はOpus 5のプロンプトガイドを参照してください。
実装手順：effortスイープを評価する
Opus 5へ移行する前後で、以下の手順でeffortスイープを実施します。
1. 本番に近いタスクセットを用意する
合成例ではなく、本番ログから30〜50件の実際のプロンプトを抽出します。
含めるべきもの:
- 通常ケース
- 失敗すると困る難しいケース
- 長いコンテキストを扱うケース
- ツール利用やコード修正が必要なケース
- レイテンシやコストが問題になる高頻度タスク
簡単な問題だけでは、各レベルの違いが見えません。
2. 先に合格条件を決める
モデル出力を見る前に、成功を判定する条件を定義します。
例:
- テストが通る
- JSONがスキーマ検証を通る
- 抽出フィールドが正解データと一致する
- 人間のレビュアーが合格・不合格を判定する
- 回答に必須の根拠や引用が含まれる
評価基準が曖昧だと、最終的に「なんとなく良い」という比較になってしまいます。
3. すべてのプロンプトを全レベルで実行する
40件のプロンプトなら、5レベルで合計200リクエストです。
40 prompts × 5 effort levels = 200 requests
レイテンシが重要でない一括評価なら、バッチAPIを使うことでコストを抑えられます。
4. 実行ごとに3つの値を記録する
少なくとも次を記録してください。
| 項目 | 用途 |
|---|---|
| 合格・不合格 | タスク品質を比較する |
usage.output_tokens |
出力側の実際のコストシグナルを比較する |
| 実測レイテンシ | ユーザー体験やSLAへの影響を確認する |
レスポンスのusageオブジェクトを必ず保存し、推論量の違いを推測ではなく実測値で比較します。
5. 合格する中で最も安いレベルを選ぶ
品質基準を満たす最小のeffortを選びます。
例えば、mediumとhighで合格率が同じなら、mediumを候補にします。候補が決まったら、調整に使用していないホールドアウトセットで再評価してください。
6. 次のモデル更新時にも再実行する
今回スイープが必要なのは、Opus 4.8からOpus 5への移行でレベルが再調整されたためです。同様の再調整は今後も起きる前提で、評価スクリプトやコレクションを残しておくと安全です。
Apidogで5レベルを横並び比較する
比較作業の本質は、同じリクエストを送信し、output_config.effortだけを変更して結果を並べることです。
Apidogを使う場合は、次の構成にします。
- Anthropic Messagesエンドポイントのリクエストを作成する。
- APIキーはリクエストボディに書かず、環境変数として保存する。
- 動作確認済みのリクエストをコレクションへ保存する。
- リクエストを5つ複製し、各リクエストで
output_config.effortのみを変更する。 - 各応答の
usageオブジェクトを比較する。 - 必要に応じてストリーミングを有効化し、SSEイベントでレイテンシを確認する。
-
stop_reasonがmax_tokensではないことを検証するアサーションを追加する。
特に、次のようなチェックは最初に設定する価値があります。
stop_reason が max_tokens ではないこと
高いeffortでは、回答が途中で切り詰められる問題が起きやすいためです。これを検証しておけば、短いが正常に見える失敗レスポンスを見逃しにくくなります。
比較コレクションを作成する場合は、Apidogをダウンロードしてください。
正直な上限：effortはモデルの能力階層を変えない
effortは、Opus 5をタスクに合わせて効率よく運用するためのレバーです。ただし、maxを指定しても、より上位のモデルとの能力差そのものがなくなるわけではありません。
Anthropicが公開したOpus 5のローンチ時の数値では、Opus 4.8のFrontier-Bench v0.1スコアの2倍以上、ARC-AGI 3では次点モデルの約3倍、CursorBench 3.2ではFable 5に0.5%以内の性能を半分の価格で実現したとされています。
ただし、これらはベンダーが実施・公開した数値であり、2026年7月25日時点で独立再現はされていません。中立的な測定値ではなく、出典付きのベンダー主張として扱うべきです。詳細はOpus 5ベンチマーク内訳を確認してください。
Opus 5の上位には、入力100万トークンあたり10ドル、出力100万トークンあたり50ドルのFable 5があります。またAnthropicは、サイバーセキュリティの悪用や自律生物学研究では、Opus 5がMythos 5に劣ると直接述べています。
effort: "max"は、Opus 5の推論予算を増やす設定であり、モデルの能力クラスを変える設定ではありません。ワークロードに対してOpus 5とFable 5のどちらが適切かは、Opus 5 vs Fable 5で検討できます。
FAQ
Claude Opus 5のデフォルトのeffortレベルは何ですか？
highです。output_configがないリクエストも、適応的思考が有効なhighとして実行されます。
5つのeffortレベルは何ですか？
low、medium、high、xhigh、maxです。コーディングやエージェント的な作業では、Anthropicはxhighから開始し、評価結果に基づいて下げることを推奨しています。
effort: "xhigh"で400エラーになるのはなぜですか？
多くの場合、thinking: { "type": "disabled" }も指定しているためです。思考を無効にするとeffortはhigh以下に制限されます。思考無効設定を外すか、effortをhigh以下にしてください。
Opus 4.8のeffort設定をOpus 5でそのまま使えますか？
使うべきではありません。レベルが再調整されているため、同じラベルでも推論量が異なります。Opus 5上で新たにスイープを実行してください。変更点は移行ガイドにあります。
effortを下げると回答も短くなりますか？
いいえ。effortは内部推論の量を制御します。短い回答が必要なら、プロンプトで出力形式や文字数を指定してください。
xhighまたはmaxでは、どのmax_tokensを使うべきですか？
64000から開始してください。max_tokensは思考と回答を合計した上限です。実際に生成されたトークンにのみ課金されるため、高い上限を指定しただけで追加料金が発生するわけではありません。
Claude Opus 5の仕様、利用可能性、料金の全体像は、Claude Opus 5とは何かから確認できます。
Top comments (0)