/claude-api cost-optimizeでAPIコストを段階的に削減する

/claude-api cost-optimizeとは何か

/claude-api cost-optimizeは、既存のClaude API実装のコストを、出力品質を落とさずに削れる範囲から順に検証していくClaude Codeのコマンドです。v2.1.247で追加された、バンドルスキルclaude-apiのサブコマンドの1つです。

最大の特徴は順序が固定されていることです。キャッシュ・トークン整理・バッチ処理という品質を犠牲にしないレバーを先に、effortとモデル選定という品質とコストを引き換えるレバーを後に回します。先に品質を落とす側へ飛ぶと、品質を犠牲にせず削れたはずの分まで一緒に失うためです。

「品質を犠牲にしない」はコマンドが無料という意味ではありません。ベースラインの計測やeffortの比較はモデルを実際に呼び出すので、実行前に承認を求められます。bareで/claude-api cost-optimizeとだけ打った場合、変更はそのまま適用されず、提案(diff)として出ます。

claude-apiスキルの自動起動条件やmigrate・prompt-auditとの役割分担はClaude Codeのclaude-apiスキルでAPI移行を自動化するにあります。

/claude-api cost-optimize

最初に決める3つ:スコープ・品質基準・ベースライン

リクエストでファイルやディレクトリを指定していればそれが対象で、指定がなければプロジェクト内のClaude API呼び出し全体が対象です。対話的なパスと夜間バッチは同じキーでも別のトラフィッククラスとして分け、プロファイルも順位付けも検証もクラスごとに行います。

Anthropicの直接提供API・Claude Platform on AWS・Bedrock・Vertex・Foundryのどれ向けのコードかも、最初に確認します。使えるレバーがプラットフォームで変わり、対象外のレバーは順位付けの前に「見送り」へ回るためです。

品質基準はプロジェクトのeval・テストスイート・成果物チェックです。無ければその旨をレポートの目立つ位置に書き、トレードオフ系のレバーは「evalが要る」という保留になります。評価が自分の目視だけの場合は、品質を犠牲にしないレバーの採否には使えても、トレードオフ系の判断には使えません。

ベースラインは、次の3つのうち得やすいものから採用します。

請求額の内訳をどう測るか

Admin APIキーがあれば、GET /v1/organizations/usage_report/messages(group_by[]=model、bucket_width=1d)でモデル別のトークン数を取れます。1回の応答は未キャッシュ入力・キャッシュ読み取り・5分と1時間のキャッシュ書き込み・出力に分かれ、各レバーが作用する量そのものです。ドル建てはGET /v1/organizations/cost_reportにgroup_by[]=descriptionを付けます。どちらもレポートを読むだけでトークンを消費せず、リクエスト完了から約5分でデータに載ります。

組織全体のレポートなので、1つのキーを複数プロジェクトで共有していると数字が混ざります。コードの想定(モデル・桁数)と合うかを見て、ずれていればapi_key_ids[]やworkspace_ids[]で絞ります。ただしコストレポートはこの2つの絞り込みを受け付けず、group_byでワークスペース単位に分けるのが限界です。Bedrock・Google Cloud・Foundryのトラフィックは、Consoleの使用状況ページに載りません。

Admin APIが使えないときは、システムプロンプトとツールスキーマの大きさ、ループの深さ、画像やPDFの解像度、max_tokensの設定値をコードから読みます。コードに見えない事情もあります。

• speedやinference_geoのように標準単価より割増になるパラメーターを使っていないか
• stop_reason: "refusal"で終わる応答の割合(一部の拒否は課金対象)
• thinkingとeffortを省略したときの既定動作。省略時に思考が走るモデルでは、出力トークンが見えない費用項目になる

アプリがresponse.usageをすでにログしているなら、代表的な1日分を先に見るのが最優先です。キャッシュのヒット率と入出力比が推測から実測に変わります。思考トークンはusage.output_tokens_details.thinking_tokensで直接わかります。compactionのような処理がサーバー側で走った応答は、その分がusage.iterationsに別立てで載るので、トップレベルの数字だけでなくiterationsも合算します。

得られたデータの粒度で、削減余地の書き方が決まります。

同じトークンを2つのレバーが二重に主張しないよう、上位のレバーで削れる分を差し引いてから順位付けします。削減余地が請求額のごく一部にとどまり、検証の実行費用に見合わないレバーは候補から外します。小さなワークロードでは「変更なしを推奨」が成功した結論です。

キャッシュが効いているかをどう見積もるか

プロンプトキャッシュは、エージェントループのコストを2.7〜5.3倍圧縮した計測があります。小規模なトリアージエージェントでは単独で請求の83%を削り、入力整理を足すと88%でした。ヒット率は入力トークンの79〜90%がキャッシュ読み取りになる水準です。仕組みはPrompt Cachingを理解する、多ターン会話での挙動は自動プロンプトキャッシュは多ターン会話でどう動くかにあります。

ログに使用量が無くても、リクエストのタイムスタンプがあればヒット率を見積もれます。時刻を並べ、直前のリクエストとの間隔がTTL以内なら1ヒットと数えます(読み取りでTTLが更新されます)。件数だけわかるなら、到着をポアソン過程と見て、ヒット率を1 - e^(-λ·TTL)で近似します。λは1秒あたりのリクエスト数です。平均間隔とTTLを比べるより、到着のばらつきを反映できます。

この式を5分TTL(300秒)に当てはめた計算例です。

1時間TTLは書き込みが入力の2倍(5分は1.25倍)なので、ヒット率だけでは決まりません。数秒おきにターンが進むループなら、5分の既定のままが安く、1時間設定よりClaude Sonnet 5で約15%、Claude Opus 5.5で約15〜18%安いという計測があります。1時間TTLが得になるのは、5分〜1時間の空きが20回に1回程度挟まり、1時間を超える空きが少ない場合です。1時間を超えると両方のキャッシュが切れ、1時間設定は高い書き込み単価を払い直します。

空きの前に前回と同じリクエストをmax_tokens: 0で送り直す「キープアライブ」も選択肢です。前回リクエストの開始から4分以内に送り、以後4分ごとに繰り返します。キャッシュの5分は応答の終了ではなくリクエストの開始から数えるためです。Claude Opus 5.5でmax_tokens: 1のキープアライブを使った計測では、空きが5〜10%の回に挟まる程度なら1時間TTLより8〜13%安くなっています。毎ターンの前に空きがあると割高です。max_tokens: 0が既存のエントリを更新するかは、Opus 5.5では計測されていません。

max_tokens: 0は、thinking.type: "enabled"・structured outputs・forced tool choiceのリクエストでは拒否されます。その場合は1時間TTLを使います。compactionパラメーター付きのリクエストもmax_tokens: 0では拒否されるので、キープアライブには流用できません。anthropic-betaヘッダーも再送が必要です。

Claude Fable 5.1(キャッシュ読み取りは0.025倍)でも、数分の空きが続くセッションでは、5分キャッシュを温め続けるほうが1時間キャッシュより1セッションあたり13〜20%安くなりました。

ツールや参照資料が重いとき

入力・ループ・出力のトークン整理は、症状ごとに使うレバーが違います。

画像は28×28ピクセルのパッチを1トークン前後として数えるため、コストが画素数に比例します。tool searchの効果は、スキーマが1万トークンを超えたあたりから出ます。それ未満では検索の手間のほうが重くなります。大きな参照ドキュメントは、ほとんどの呼び出しがその大半を読むなら、キャッシュされたプレフィックスに置いたままで十分に安く済みます。

プロンプトオーディットは入力整理の一部として走り、古いモデル向けの指示文を洗い出します。サポートデスクの評価では、Claude Opus 4.8向けのプロンプトをそのままClaude Opus 5に使うとチケットあたり36%増え、正確性は変わりませんでした。オーディット後は未監査版より14%安くなり、正答率も92%から97%に上がっています。検出パターンと手順は/claude-api prompt-auditで古いモデル向けの記述を検出するにまとめました。

長いループでは、古いツール結果の扱いが分かれます。issueトリアージエージェントの短い実行と、トークンが2.6倍の長い実行で計測した結果は次のとおりです。

コンテキストエディティングは節約手段ではなく、コンテキストウィンドウに余地を作る機能です。整理のたびにキャッシュ済みの会話が書き換わるためです。刈り込みは、作業の区切りで古いツール結果を1行の抜粋に置き換える数行のコードで、編集が会話の末尾に集まるのでキャッシュが効きます。ただしPreserved thinkingのチェックが走るモデルでは、クライアント側の編集で後続のthinkingブロックが無効になる点に注意が要ります。

出力側では、max_tokensを「打ち切りの安全弁」として扱います。モデルには見えないので、下げても節約は促されません。エージェント用途では64,000が出発点で、xhigh・max effortでも同じ値から始めます。1回の打ち切りが高くつく場合に限り128,000まで上げます。

16,384で切った計測では、Claude Opus 5.5の約4分の1、Claude Fable 5.1の43%の試行が途中で終わりました。解けた試行はごくわずかで、解けたタスクあたりのコストは64,000のときとほぼ変わりません。短くしたいのは見える応答の長さなので、プロンプトで出力の形を例つきで指定します。

待たない処理はバッチに回す

バッチ処理は、標準tierの全トークンが50%オフです。キャッシュの書き込みと読み取りにも割引が重なります。評価の実行・バックフィル・定期ジョブのように、誰も応答を待たない処理が対象です。

• 結果は最大24時間以内に非同期で届きます。この24時間は期限であってSLAではないため、ユーザーが待つ処理は同期のままにします
• バッチのリクエストは単発で、途中でツールループを回せません。入力を先に取得してツールループを1リクエストに畳めることもありますが、モデルの推論の仕方が変わるため、パラメーターではなく設計の判断です
• Managed Agentsのセッションには使えません

ここから先は品質と引き換え:effort・予算・モデル

トレードオフ系のレバーは、品質を犠牲にしないレバーを検証し終えたあとに試します。どれも、品質の変化を測る基準(eval)が前提です。

effortの掃引は、モデルを変える前に試すレバーです。同じセッション内で切り替えるとキャッシュが無効になって比較が歪むため、設定ごとに別セッションで回します。効き方はワークロードで大きく違います。

プロンプトキャッシュ・指示の棚卸し・effortをまとめて見る考え方はClaude Platformのコストを削減する3つの実装レバーにあります。

再実行が成立するのは、テストのように正誤を判定できるワークロードに限られます。判定が悪い結果を通してしまうと、失敗がそのまま漏れます。失敗した分は2回分の実行時間がかかるので、節約の代償は遅延です。正答率のわずかな上昇は主に2回目の試行によるもので、この方式は正答率ではなく節約のために使います。

タスク予算は、モデルにトークン予算を見せて自分でペースを配分させる仕組みです。ベータで、ヘッダーはtask-budgets-2026-03-13です。SWE-bench ProのClaude Fable 5.1では、ゆるい予算でコスト44%減・合格率約3点減、許される最も厳しい予算で58%減・6点減でした。2万トークンの下限を下回る予算は拒否されます。目安は、ループのトークン使用量の90パーセンタイル付近から始めて締めていくことです。タスクの最初のリクエストで一度だけ設定します(途中変更はキャッシュを無効にします)。予算は助言であってモデルを止めません。

モデル選定は最後に回し、基準を「トークン単価」ではなく「解けたタスクあたりのコスト」に置きます。同じ計測の中に、単価の順位がひっくり返る例が並んでいます。

20問のWideSearchでは、2問が支出全体の43%を占めました。平均ではなく、難しいタスクの尾側で比べます。1段階ずつ下げ、そのたびにeffortを掃引し直します。1〜2世代前のモデルを使っているなら、新しい世代へ上げるのも手段で、Opus 5はlowでOpus 4.8の既定よりコスト約30%で上回りました。

処理を分担する構成もあります。advisor構成は、Claude Opus 5.5(high)にFable 5.1を助言役に付けて、単独のhighより1.7点高く、費用は約2.1倍でした。差は試行間のばらつきの範囲です。orchestrator構成は、21.6百万トークンのコーパスで、Fable 5.1の単独実行より47〜55%安く、約2.3時間で終わりました。ただし正答率は10〜12点低く、BrowseCompの例では、Claude Fable 5単独で同じ正答率に22〜30%低いコストで届きました。

1レバーずつ測って採否を決める

採用するレバーは、削減額の順位ではなくStep 2で並んだ順(品質を犠牲にしないレバー、effort・予算、モデル)に1つずつ適用します。レバーごとに個別のdiffを作り、そのトラフィッククラスのevalを回して、直前の構成と正答率・コストを並べます。コストが下がっても正答率が下がったなら、最適化ではなく差し戻しです。

evalが無いプロジェクトには、最小の組み立て方があります。

1. 本番から抜き出した、または手書きの20〜30件の入力を固定する
2. 判定は正解との突き合わせ、簡単なルーブリック、自動チェッカーのうち手近なものにする
3. 各設定を同じ入力で回し、出力とresponse.usageを記録して、正答率とタスクあたりのコストを出す

最終的な本番切り替えには、約50件・各設定5回以上の試行が目安です。レバーごとの採否はもっと小さいセットで足りますが、1回の振れで決めず、試行を重ねます。

測ったのに削減が見えないとき

• キャッシュ検証が冷えたまま: 検証には温まったキャッシュが要ります。サンプルを順に流し、2回目以降から測ります。最初のリクエストは書き込みが1.25倍で乗るため、品質を犠牲にしないレバーが悪化したように見えます
• 共有キーで効果が混ざる: 切り替え後の確認もレポートの読み取りで行うので、キーを共有していると、どのプロジェクトの削減か切り分けられません
• evalが一部のパスしか覆わない: evalが検証できるのはそのトラフィッククラスだけで、覆われないパスのトレードオフ系レバーも「evalが要る」扱いのままです

まとめ

cost-optimizeの順序は「測る→品質を犠牲にしない順→品質と引き換える順」で、削減額の大きさではなく、品質を損なうリスクの小さい順に並んでいます。小さなワークロードや、すでにキャッシュが効いているコードでは、候補が空になる結果も正当な出力です。

同じclaude-apiスキルのPython SDKのメジャーバージョン移行コマンドは/claude-api upgradeでPython SDKをv0.xからv1へ移行するで扱っています。