Claude Code に画像を渡すときのコンテキスト消費を減らす — ピクセル寸法で考えて縮小・クロップ・テキスト化で絞る

Claude Code にスクリーンショットや図を渡すと、会話のコンテキストが想像以上に減っていくことがあります。このとき消費されるのは画像のファイルサイズ（KB や MiB）ではなく、ピクセル寸法に比例する画像トークンです。したがって、JPEG 品質を落として容量を半分にしても、縦横のピクセル数が同じであればトークン数は変わりません。本稿では、公式ドキュメントに示された画像トークンの計算方法と長辺上限の挙動を確認し、そのうえで効く対策と効かない対策を分けて整理します。

Codex や OpenAI API を使う場合の最適化は別記事の Codex に画像を渡すときのコンテキスト消費を減らす — GPT-6.1 / GPT-6 / GPT-5.6 系の 32×32 px パッチと detail: low / high / original でトークンを削る にまとめてあります。

画像トークンはピクセル寸法で決まる

Anthropic の Vision ドキュメント では、画像は 28×28 px のパッチ単位で処理され、パッチ 1 つがビジュアルトークン 1 つに対応すると説明されています。画像のトークン数は次の式で決まります。

⌈幅（px） ÷ 28⌉ × ⌈高さ（px） ÷ 28⌉ = ビジュアルトークン数

この式にファイルサイズ・圧縮率・色数は含まれません。そのため、強く圧縮した JPEG と非圧縮 PNG は、同じピクセル寸法であれば同じトークン数になります。グレースケールにしても、EXIF を削っても、ピクセル寸法が変わらないかぎり画像トークンは減りません。

当てはめると、1920×1080 の画像は 69 × 39 = 2,691 トークン、960×540 の画像は 35 × 20 = 700 トークンになります。面積が 1/4 になるので、トークンも約 1/4 になる計算です。

ただし、実際の計上にはもう 1 つ重要な挙動があります。ドキュメントには、各モデルに長辺とビジュアルトークン数の上限があり、どちらかを超える画像は処理前に縮小されると明記されています。上限は次の 2 つのティアに分かれます。

Claude Code で使う Sonnet 5.5 や Opus 5.5 などの Claude 4.7 以降のモデルは、高解像度ティアに該当します。ドキュメントの表では、1920×1080 の画像は高解像度ティアでは縮小されず 2,691 トークン、標準ティアでは 1456×819 に縮小されて 1,560 トークンです。3840×2160 の 4K スクリーンショットをそのまま貼っても、高解像度ティアでは 2576×1449（4,784 トークン）に、標準ティアでは 1456×819（1,560 トークン）に縮小されるので、「大きいまま貼れば情報が多く残る」という直感は当てはまりません。縮小後の寸法で課金される一方、縮小は補間処理なので小さな文字は読みにくくなります。上限はモデルによって異なるため、使用するモデルの値は公式ドキュメントで確認してください。

効果の有無を整理すると、次のようになります。

アスキーアート化だけ補足しておくと、80×40 の文字列にしても数千トークンのテキストトークンになりがちで、しかも細部が落ちます。単純な枠組みを示す以上の用途では、同じ内容をプローズで記述するか、Mermaid などの構造化表現を渡すほうが情報量もトークン効率も上です。

効果の大きい順に対策する

画像を渡さずに済ませる

Claude Code での開発用途では、そもそも画像を必要としない情報が多く含まれています。この場合、テキストや構造化データで渡すほうが少ないトークンで済みますし、Claude が内容を機械的に扱いやすくもなります。

• UI の実装・修正が目的なら、該当箇所の HTML・CSS・DOM の抜粋を渡す
• フローチャートや画面遷移図は Mermaid のコードを渡す
• 表は CSV や Markdown の表で渡す
• グラフは元の数値データを渡す（CSV・JSON）
• エラーダイアログは、画面の画像ではなくエラーメッセージのテキストを貼る
• ロゴ・アイコンは SVG ソースを渡す

たとえば、ターミナルに表示されたエラーは次のテキストだけで十分なことが多いです。

Error: Cannot find module 'react'
File: src/main.tsx
Line: 12

画像内の文字だけが必要な場合は、OCR で文字を抽出するか、元のログを取得します。反対に、グラフの形状・UI の配置・図解の関係性は文字だけでは失われるため、必要に応じて画像と併用します。色や余白、視覚的な完成度の評価も、構造データだけでは判断できない領域です。

必要な領域だけクロップする

画面全体ではなく、問題が起きている箇所だけを切り出します。たとえば、ヘッダーの一部、ボタン 1 つ、エラーダイアログだけであれば、画像の面積は大きく減ります。1920×1080 のスクリーンショットから 480×270 の領域を切り出すと、面積比で 1/16、画像トークンは 18 × 10 = 180 トークンで約 1/15 です。

ピクセル寸法が課金の基準なので、必要な領域を 100% ピクセルで渡すほうが、画面全体を縮小して渡すよりも、同じトークン数で得られる情報密度は高くなります。クロップは解像度の縮小より前に検討する価値があります。

解像度を段階的に切り替える

全体の構造を確認する段階と、細部を確認する段階で解像度を分けると、トークンをまとめて抑えやすくなります。

1. 全体像を確認するため、長辺 960 px 程度に縮小した画像を渡す（約 700 トークン）
2. 小さな文字や細部が必要になったら、原画像から該当領域だけを切り出して追加で渡す

Vision ドキュメントの「画像品質に関するガイダンス」でも、大きすぎる画像は縮小されて文字が読みにくくなることがあるため、事前のリサイズ、クロップ、またはその両方を検討するよう案内されています。「まず全体を小さく見せ、必要なところだけ原寸で見せる」と覚えておくと良いです。

前処理をコマンドで自動化する

ImageMagick を使うと、画像を渡す前に自動で処理できます。ImageMagick 7 では magick コマンドを使います。ImageMagick 6 では convert を使います。

# 余白を削除
magick input.png -trim +repage output.png
 
# 960x540 以内に縮小（それより小さい画像は拡大しない）
magick input.png -resize '960x540>' output.png
 
# メタデータを削除してファイル容量を落とす（トークンは変わらない）
magick input.png -strip output.png

複数の処理を組み合わせる場合は、次のように書けます。

magick screenshot.png \
  -trim +repage \
  -resize '960x540>' \
  -strip \
  context.png

-trim は画像の端の色を基準に余白を判定します。背景が単色でない場合、必要な部分まで削除されることがあるため、結果を確認してから使ってください。

よく使うパターンは、スクリーンショットを保存するフォルダに fswatch などで監視を仕込み、保存された画像を自動でこの処理に流す構成です。手動で縮小を忘れることがなくなります。

画像を履歴に残し続けない

Claude Code では、一度渡した画像が会話の履歴に残り続け、以降のターンでも繰り返しコンテキストに乗ります。10 ターン続くセッションの 1 ターン目に 2,691 トークンの画像を貼ると、以降のターンでもその画像がコンテキストに含まれます。/compact やオートコンパクトで履歴が要約テキストに置き換わると、画像本体は残りません。また、リクエストの画像枚数や総サイズが上限に達すると、Claude Code は古い画像から一括で送信対象から外し、Claude はその画像を参照できなくなります。残しておいても後で参照できるとは限りません。

したがって、画像から必要な情報を読み取ったら、結果をテキストのメモ（CLAUDE.md、.claude/context/*.md など）に書き出し、以降は同じ画像を再送しないようにします。ただし、要約では画像の細部が失われます。細部が後から必要になった場合は、該当領域だけをクロップして再度渡します。

UI の実装前後比較のような、連続してスクリーンショットを撮る用途では、毎回フルスクリーンショットを渡すのではなく、変更された領域だけを差分として渡す運用が有効です。Playwright などで自動スクリーンショットを撮るエージェント環境では、差分画像の生成までを前処理に組み込んでおくと、ターンごとの画像トークンを一定に抑えられます。

用途別の最初の一手

実務では、「解像度を下げるかクロップする」「テキストや構造化データに置き換えられるものは置き換える」「同じ画像を再送しない」の 3 つをまず徹底するだけで、大半の無駄を減らせます。

一方で、画像を減らしすぎると再質問や再送が増えて、結果的にコンテキストを多く使ってしまうこともあります。同じ画像と同じ質問で、入力トークン数と回答の正確さを比べながら、過剰にならない範囲で調整するのが確実です。最終的な評価基準はトークン削減量ではなく、1 タスクを完了するまでに使った総トークン数です。

以上、画像のトークン消費はファイルサイズではなくピクセル寸法で決まることを確認し、縮小・クロップ・テキスト化・履歴に残さない運用で渡す情報を絞る方法を整理した、現場からお送りしました。

参考情報

• Anthropic Vision ドキュメント
• ImageMagick 公式サイト
• Mermaid 公式サイト
• Codex に画像を渡すときのコンテキスト消費を減らす — GPT-6.1 / GPT-6 / GPT-5.6 系の 32×32 px パッチと detail: low / high / original でトークンを削る