ツールが返す画像を Claude に「見せる」 — tool_result を画像ブロックにしてトークンを約10分の1にする

Before / After のコストを実数で押さえる

違いを実感するために、同じ 1024×1024 の PNG を 2 通りで渡したときの概算を並べます。

画像のトークン数は、おおよそ「縦 × 横 ÷ 750」で見積もれます。1024×1024 なら 1024 * 1024 / 750 ≈ 1,398 トークンです。この式を知っていると、ツールが返す画像を縮小すべきかどうかを送信前に判断できます。たとえば 2048×2048 をそのまま返すと約 5,600 トークンになりますが、判定に 1024 で足りるなら、送る前に縮小するだけで 4 分の 1 に圧縮できます。

逆に言えば、base64 を文字列で詰めるアンチパターンでは、この見積もり式がまったく効きません。テキストは 1 文字単位で課金され、base64 は元データの約 1.37 倍に膨らむためです。1 枚で 2 万トークンというのは、こうして生まれます。

エージェントループに組み込む

実際のループはこうなります。Claude が tool_use を返す → 自分のコードでツールを実行して画像を得る → その画像を image ブロックにして tool_result で返す → Claude が画像を見て次の判断をする、という往復です。

import base64, anthropic
 
client = anthropic.Anthropic()
 
def render_thumbnail(candidate_id: str) -> bytes:
    # 実際にはサムネイル生成・取得処理。ここでは PNG バイト列を返すとする
    ...
 
def run_review(candidate_id: str):
    messages = [{
        "role": "user",
        "content": f"候補 {candidate_id} のサムネイルを生成して、視認性を5段階で評価してください。",
    }]
 
    while True:
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=[{
                "name": "render_thumbnail",
                "description": "指定した候補IDのサムネイルPNGを生成して返す",
                "input_schema": {
                    "type": "object",
                    "properties": {"candidate_id": {"type": "string"}},
                    "required": ["candidate_id"],
                },
            }],
            messages=messages,
        )
 
        if resp.stop_reason != "tool_use":
            return resp  # 最終評価が返ってきた
 
        # tool_use ブロックを処理
        tool_results = []
        for block in resp.content:
            if block.type != "tool_use":
                continue
            png = render_thumbnail(block.input["candidate_id"])
            b64 = base64.standard_b64encode(png).decode("ascii")
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": [{
                    "type": "image",
                    "source": {"type": "base64", "media_type": "image/png", "data": b64},
                }],
            })
 
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": tool_results})

ここで messages.append({"role": "assistant", "content": resp.content}) を忘れると、「tool_result に対応する tool_use ブロックがない」というエラーになります。アシスタントの tool_use を会話履歴に戻してから、その直後の user ターンで tool_result を返す、という順序が必須です。

TypeScript SDK でも形は同じ

言語が変わっても構造は同じです。content を配列にして image ブロックを入れる、という点だけ守れば動きます。

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
 
const toolResult = {
  type: "tool_result" as const,
  tool_use_id: toolUseId,
  content: [
    {
      type: "image" as const,
      source: { type: "base64" as const, media_type: "image/png" as const, data: b64 },
    },
    { type: "text" as const, text: "App Store スクリーンショットの最新版です。" },
  ],
};

私は App Store のスクリーンショットを差し替えたあと、その新しい画像をツール経由で Claude に見せて「文字が切れていないか」「端末枠からはみ出していないか」を一次チェックさせています。テキストで「こういう画像です」と説明するより、実物を見せたほうが指摘が具体的になります。ここでも base64 を文字列で渡していた頃は、毎回数万トークンを無駄にしていました。

URL や Files API という選択肢

base64 をメッセージに毎回埋めるとリクエストが重くなります。同じ画像を何度も参照するなら、source の型を変える方法があります。

繰り返し同じ図版を見せるパイプラインでは、Files API に一度アップロードして file_id で参照すると、毎回 base64 を送らずに済みます。私のように毎朝バッチでサムネイルを点検するようなループでは、固定の比較用基準画像だけ先にアップロードしておき、変動する候補画像だけ base64 で送る、という使い分けにしています。

送信前に決める3ステップ

本番に載せる前に、画像を返すツールでは次の順で方針を決めると安定します。私はこの3点を最初に固めてから実装に入るようにしています。

1. 解像度を決める: 判定に必要な最小解像度まで縮小します。原本をそのまま送らないことを推奨します。トークンも結果の再現性も、ここで決まります。
2. source タイプを選ぶ: 一回きりなら base64、繰り返し参照するなら file_id を選ぶ場合が多いです。個人的には、固定の比較基準だけ先にアップロードしておく形に落ち着きました。
3. 失敗時の対処を決める: メディアタイプ不一致やサイズ超過で読み取りに失敗したときの解決手順（縮小して再送、別形式へ変換）を、本番に出す前に用意しておきます。

落とし穴チェックリスト

実装中につまずきやすい点をまとめます。

• メディアタイプは正確に: image/png image/jpeg image/gif image/webp のいずれかを、実データと一致させます。PNG を image/jpeg と申告すると読み取りに失敗します。
• サイズは送る前に縮小: 長辺が大きすぎる画像はトークンも増え、内部で縮小もされます。判定に必要な解像度まで自前で落としたほうが、コストも結果の再現性も安定します。
• ユーザー画面には自動表示されない: ツール結果として返した画像は、Claude は「見える」ものの、アプリ側の最終回答に自動でインライン表示されるわけではありません。チャットUIで見せたいなら、自分のフロントで明示的に描画する必要があります。
• 順序とペアリング: tool_use（assistant）→ tool_result（user）の対応を崩さないこと。複数ツールを並列で呼んだ場合は、すべての tool_use_id に対して結果を返します。
• 巨大画像の上限: API には 1 枚あたりのサイズ上限があります。高解像度の原本をそのまま投げず、点検用の縮小版を返す設計にしておくと安全です。

まず最初に変えるべき一行

すでにツールから画像を返している実装があるなら、今日できる最小の改善は明確です。content に文字列で base64 を入れている箇所を探し、content を配列にして {"type": "image", "source": {...}} ブロックに置き換えてください。これだけで、同じ画像のトークンコストがおおよそ 10 分の 1 になり、しかも Claude が初めて中身を「見て」判断できるようになります。

実装の参考になれば幸いです。私自身まだ運用しながら最適点を探っている途中ですが、画像を返すツールを書くときは「これは Claude にテキストとして読ませているのか、画像として見せているのか」を最初に確かめる、という一点だけでも効くはずです。