Claude API Claude API PHP コスト削減

Claude APIのアドバイザーツールで生成コストを6割下げた実装と実測

長文コンテンツの自動生成をAPIで回していると、1本あたりのコストがそのまま運用費になります。安いモデルに替えれば下がりますが、品質が読めない。そこで実行役に安いモデルを使い、要所の判断だけ賢いモデルに相談させるアドバイザーツールを実装しました。結果は1本$0.67から$0.26へ、約6割減。品質は落ちていません。実装で踏んだ400エラーと、工程ごとにモデルを割り当てる設計をまとめます。

前提: アドバイザーツールはClaude APIのベータ機能

先に前提を2つ書いておきます。

ひとつ目。アドバイザーツールはClaude API（Messages API）のサーバー側ツールです。Claude Codeを使っていて有効にできる設定ではありません。この記事はAPIを直接呼ぶ自作の仕組みに組み込んだ話で、コードもその前提で書いています。

ふたつ目。現時点でベータ機能です。リクエストにベータヘッダを付ける必要があり、仕様が変わる可能性があります。本番の基幹処理にいきなり入れるより、失敗しても影響が限定される処理から試すのが無難です。実際、後述するとおり応答の形も通常とは変わります。

アドバイザーツールは「実行役」と「相談役」を1リクエストで組み合わせる

通常のAPI呼び出しは1リクエスト＝1モデルです。アドバイザーツールを使うと、リクエスト本体の model（実行役＝エグゼキュータ）が本文を生成しつつ、生成の途中でツールとして宣言したモデル（アドバイザー）に方針を相談できます。トークン課金はそれぞれのモデルの単価で分かれます。

ツール定義はこれだけです。

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-8"
}

加えてベータヘッダ anthropic-beta: advisor-tool-2026-03-01 が要ります（これが前述のベータ指定です）。制約としてアドバイザーは実行役と同等以上の能力が必要で、逆転した組み合わせは400になります。今回は実行役をSonnet 5、アドバイザーをOpus 4.8にしました。

Haikuに adaptive thinking を送ると400になる

最初の実行は数秒で落ちました。

ERROR: Anthropic APIエラー: adaptive thinking is not supported on this model

原因は自分の実装でした。全リクエストに一律で thinking: {"type": "adaptive"} を付けていたところへ、コスト削減のために軽い工程をHaiku 4.5に割り当てたためです。adaptive thinkingは世代の新しいモデルだけが受け付けるので、Haikuに送ると弾かれます。

単一モデルで回している限り起きない事故です。工程ごとにモデルを変えられるようにした瞬間、リクエストの組み立ても「モデルによって変わる」ようになる。対処はモデルを見て付け外しするだけです。

private static function supports_adaptive_thinking( $model ) {
    $model = strtolower( (string) $model );
    if ( false !== strpos( $model, 'haiku' ) ) {
        return false;
    }
    return (bool) preg_match(
        '/(fable-5|mythos-5|opus-5|opus-4-(6|7|8)|sonnet-5|sonnet-4-6)/',
        $model
    );
}

モデル名の部分一致で判定しているのは、対応表を別に持つと新しいモデルが出るたびに更新が要るからです。名前の規則が変わったら破綻しますが、そのときはエラーメッセージで気づけます。

サーバー側ツールは pause_turn で中断することがある

アドバイザーのようなサーバー側で動くツールは、内部のループが上限に達すると stop_reason: "pause_turn" で応答を返してきます。これは失敗ではなく「続きがある」の合図で、それまでの応答をassistantとして履歴に戻し、同じ内容で再送すればサーバーが続きから再開します。

ここで追加のユーザーメッセージを付けてはいけません。「続けて」などと書くと、再開ではなく新しい指示として解釈されます。

$continuations = 0;
while ( 'pause_turn' === ( $body['stop_reason'] ?? '' ) && $continuations < 3 ) {
    $continuations++;
    $payload['messages'][] = array(
        'role'    => 'assistant',
        'content' => $blocks,   // 受け取ったブロックをそのまま戻す
    );
    // 同じpayloadで再送。ユーザーメッセージは足さない。
    $response = wp_remote_post( $endpoint, array( 'headers' => $headers, 'body' => wp_json_encode( $payload ) ) );
    // …応答をマージして継続判定へ
}

上限を3回にしているのは暴走防止です。応答の content には advisor_tool_result という見慣れないブロックが混ざりますが、本文を取り出す処理は text ブロックだけを拾えばよく、他は読み飛ばして問題ありません。

工程ごとにモデルを割り当てる — 判断が要る工程だけ賢いモデルに残す

コストが下がる本体はここです。1本の長文を作る処理は工程によって必要な賢さが違います。

そこで「工程名: モデルID」の対応表を設定として持ち、指定のない工程は既定モデルにフォールバックする形にしました。

そのうえで、判断の質が結果を左右する工程（本文と構成）にだけアドバイザーを付けます。全工程に付けると相談ぶんのコストが乗るので、絞るほうが効きます。照合・ファクトチェック系は品質を落としたくないので既定のOpusのまま残しました。

実測 — 1本あたり$0.67が$0.26になった

切り替え前は全工程Opus単独で、1晩12本の生成で1本あたり$0.67でした。新構成で2本生成した実測はこうです。

1本目: 入力19,299 / 出力18,189 / キャッシュ書込102,317 / 読取130,628 → 約$0.32（469秒）
2本目: 入力14,269 / 出力 7,357 / キャッシュ書込 79,159 / 読取103,914 → 約$0.20（384秒）

2本平均で約$0.26、削減率61%。注目したいのは1本目の出力18,189トークンで、これは切り替え前のOpus平均（約13,600）より多い。安いモデルに替えて文章が短くなったわけではないということです。

品質面では、狙って確認した観点——見出しが内容の約束を果たしているか、断定すべきところを伝聞で逃げていないか、出典が具体的なページに着地しているか——はいずれも切り替え前と同水準でした。

本文に「アドバイザーに相談します」と書かれた

一つだけ実害のある挙動がありました。疎通テストで返ってきた文章の冒頭がこれです。

この作業は「…」を2つ考案するというシンプルな創作タスクですが、
内容を書く前にアドバイザーに方向性を確認します。

実行役が自分の作業手順を出力に書いてしまっています。生成物をそのまま公開する構成だと、内部の仕組みが読者に見える事故になります。対処はプロンプトに1行入れるだけで済みました。

NEVER narrate your own process in the output — no meta-commentary about
planning, consulting an advisor, or deciding how to approach the task.
The output is the article itself.

これを入れたあとに生成した分では再発していません。アドバイザーを使うときは、相談したこと自体を出力に書かせない指示をセットで入れておくのが安全です。

導入するかの判断基準

冒頭に書いたとおりベータ機能で、レスポンスに新しいブロック型が増え、pause_turn の継続処理も要ります。単発の呼び出しに入れるほどの手間ではありません。

効くのは同じ処理を大量に繰り返す構成です。1本$0.4の差でも、月150本なら$60違います。逆に1日数回の呼び出しなら、実装コストのほうが上回ります。工程が分かれていて、そのうち一部だけが賢さを要求する——そういう形をしているなら、試す価値があります。