◉CLAUDE LABEN
●CC 2.1.330 — Claude Code 2.1.330 で、長い会話を圧縮した直後に数分固まる問題が直りました●SONNET 4.5 — Claude API の Sonnet 4.5 は 11/30 で提供終了、残り8日です。推奨の移行先は claude-sonnet-5-5 です●MCP 401 — MCP サーバーが 401 を返しても、エラーにならず無言でタイムアウトする、という報告が出ています●NEW — 新着:Desktop が毎回 worktree を作るとき、確かめる3か所●OPUS 4.5 — Opus 4.5 の 11/24 は「これより前には廃止しない」下限日で、廃止の告知ではありません●SCHEMA — Agent SDK と Messages API の構造化出力は、同じスキーマでも返り値の形を一度見比べると安心です●CC 2.1.330 — Claude Code 2.1.330 で、長い会話を圧縮した直後に数分固まる問題が直りました●SONNET 4.5 — Claude API の Sonnet 4.5 は 11/30 で提供終了、残り8日です。推奨の移行先は claude-sonnet-5-5 です●MCP 401 — MCP サーバーが 401 を返しても、エラーにならず無言でタイムアウトする、という報告が出ています●NEW — 新着:Desktop が毎回 worktree を作るとき、確かめる3か所●OPUS 4.5 — Opus 4.5 の 11/24 は「これより前には廃止しない」下限日で、廃止の告知ではありません●SCHEMA — Agent SDK と Messages API の構造化出力は、同じスキーマでも返り値の形を一度見比べると安心です
記事一覧/API & SDK
⬡ API & SDK/2026-06-29上級

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

ツールが返した画像を tool_result に文字列で詰めると、同じ画像が約10〜20倍のトークンを消費します。image コンテンツブロックとして返す正しい組み立て方と、SDK 実装・コスト見積もり・落とし穴を実コードでまとめました。

Claude API148tool use5vision8tool_resultトークン最適化3

✦ プレミアム記事

ツールを実装していて、いちばん見落としやすい落とし穴があります。「ツールが画像を返しているのに、Claude はその画像を見ていない」という状態です。私自身、壁紙アプリのサムネイルをエージェントに判定させるツールを書いたとき、レスポンスは返るのに判断がやけに曖昧で、よく調べたら Claude は画像ではなく「base64 の長い文字列」を読まされていた、ということがありました。

tool_result は中に何でも詰められてしまうぶん、間違った形でも動いてしまいます。動くのに高く付く、というのがこの問題のいやらしいところです。ここでは、個人開発で実際にぶつかった事例をもとに、ツールが返す画像を Claude に正しく「見せる」ための組み立て方を、コストの実数とともに整理します。

ツールが画像を返すのに Claude が見ていない、という状態

tool_use に応えて結果を返すとき、多くの実装は tool_result の content に文字列を入れます。テキストを返すツールならそれで正解です。ところが画像を返したいときに、つい次のように書いてしまいます。

# アンチパターン: 画像の base64 を「文字列」として詰める
tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use_id,
    "content": f"画像データ: {base64_png}",  # ← これはテキスト扱い
}

この形でも API はエラーを返しません。Claude は base64 文字列を「テキスト」として受け取り、見かけ上は処理が進みます。しかし Claude はピクセルを見ていないので、画像の中身に基づく判断はできません。さらに悪いことに、数万文字の base64 がそのまま入力トークンとして課金されます。

公式 SDK のリポジトリやコミュニティでも、ツール結果の画像が「ネイティブな画像ブロックに変換されず、テキストとして送られて 1 枚あたり 15,000〜25,000 トークンを消費する」という報告が上がっています。同じ画像をユーザーメッセージとして直接添付すれば約 1,600 トークンで済むため、差はおよそ 10〜20 倍です。動いているのに 10 倍払っている、という典型例です。

正しい形は image コンテンツブロックを tool_result に入れること

tool_result の content は、文字列だけでなくコンテンツブロックの配列を受け取れます。ここに image ブロックを入れると、Claude はそれを画像として認識し、ビジョンモデルとしてピクセルを読み取ります。

# 正しい形: content を配列にして image ブロックを入れる
tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use_id,
    "content": [
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/png",
                "data": base64_png,
            },
        },
        {"type": "text", "text": "現在のサムネイル候補です。視認性を評価してください。"},
    ],
}

ポイントは 2 つあります。content を配列にすること、そして画像を {"type": "image", ...} ブロックとして渡すことです。テキストの補足を添えたいときは、同じ配列に text ブロックを並べれば一緒に渡せます。Claude 側は、この画像をユーザーが添付した画像と同じ仕組みで処理します。つまりトークン換算も画像レートが適用され、テキストとして数万トークン課金されることがなくなります。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦tool_result に base64 を文字列で入れると画像が「テキスト」扱いになり、1枚あたり約15,000〜25,000トークンを浪費する仕組みと、その回避策
✦image コンテンツブロックで返したときの実コスト(約1,600トークン前後)と、トークン数を縦横サイズから先読みする見積もり式
✦壁紙サムネイルや App Store スクリーンショットをエージェントに「見せて」判断させるループの実装と、サイズ上限・メディアタイプ・表示されない問題への対処
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

⬡ API & SDK2026-06-13
Claude Vision API 実装パターン — 画像解析・PDF 処理・OCR を本番品質で動かすまで
Claude API のビジョン機能を本番投入するための実装パターンをまとめました。Base64・URL・Files API の使い分け、ネイティブ PDF 処理、Tool Use による壊れない構造化抽出、Batch API でのコスト削減、エラー対処まで動くコードで解説します。
⬡ API & SDK2026-11-18
Linked billing で顧客に払ってもらう前に — 402 と 403 が返ったとき、どの財布が空なのかを見分ける
11月17日にベータ公開された Claude API の Linked billing では、リクエストごとに billing_policy で支払元を選べます。顧客に請求したリクエストが 402 や 403 で拒まれたとき、どの財布が原因かを切り分け、自分の負担で返すかを決める手順と、Python のラッパーをまとめました。
⬡ API & SDK2026-11-17
テキスト透かしを当てにするなら、コードではなく送信ボディで temperature を確かめます
11月16日から Opus 4.6・Opus 4.5・Sonnet 4.5・Haiku 4.5 の出力にもテキスト透かしが入ります。temperature・top_p・top_k を既定以外にすると付かない場合があるため、実際に送られたボディを1回だけ記録して判断する手順をまとめました。