「Image was too large」の原因と対処 — Claude Code

Claude Codeに画像を貼り付けて「Image was too large」と出たら、疑うのは縦横のピクセル数です。ファイルの重さではありません。APIが受け付ける画像は、1枚だけなら長辺8000pxまで、リクエスト内の画像が多いと1枚あたり2000pxまでと、上限が状況で切り替わります。この切り替わりの条件が分かりにくいので、Claude APIのビジョンドキュメントとClaude Codeのエラー一覧を突き合わせて確かめました。

Image was too largeとは何のエラーか

表示される文言は次のとおりです。

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

Claude Codeのエラー一覧は、原因を「貼り付けた画像がAPIのサイズか寸法の上限を超えた」と説明しています。Retinaディスプレイや4Kモニターで撮ったスクリーンショットは、見た目が小さくても実ピクセル数が数千pxに達します。画面の一部を切り取っただけでも、長辺が上限に近づくことがあります。

つまり、圧縮ソフトで画像を軽くしても、このエラーは直りません。必要なのは軽くすることではなく、辺の長さを縮めることです。Claude Codeで画像を扱う場面では、まず寸法を疑うのが近道です。

8000pxと2000pxはどこで切り替わるか

切り替わりの境目は、1回のリクエストに入る画像の枚数です。具体的な数値は下の表のとおりで、Claude APIのビジョンドキュメントに載っています。

ここで見落としやすいのは、20枚の数え方です。ドキュメントによると、数えるのは今回貼った画像だけではありません。

• 過去のターンで送った画像も、再送されるぶんは数に入る
• tool_result の中に入った画像(たとえばコンピューター操作ツールが返すスクリーンショット)も数に入る
• Amazon BedrockとGoogle Cloudでは、PDFなどのドキュメントブロックも数に入る

Claude Codeのエラー一覧は、画像を通常は自動で縮小するとも書いています(「Unable to resize image」の節)。それでも本エラーが出る場合の上限として、「1枚なら長辺8000px、画像が多い状況では2000px」を挙げています。一方で「多い」の閾値は、Claude Code側のページには数字がありません。上の20枚はAPI側の記述です。Claude Codeがどの経路で何枚を数えているかは、公式には書かれていません。

20枚を超えた状態で厳しい上限に当たると、APIは invalid_request_error を返します。メッセージに「many-image requests」とピクセル数の上限が出ていれば、枚数側の上限です。縮小のほかに、リクエスト内の画像とドキュメントのブロックを20個以下に抑える手もあります。

ただし、貼り付けた画像は貼り付け時に2000pxへ縮小されます(v2.1.126。次の節の表を参照)。貼った枚数だけで20枚の線を越えて弾かれる経路は、一次ソースでは裏付けられませんでした。20枚の数には、2000pxに縮小された画像も入ります。厳しい上限に引っかかるのは、縮小に失敗して2000pxに収まっていない画像だと考えられます。

APIには、1リクエストあたりの画像枚数の上限もあります。200kトークンのコンテキストウィンドウのモデルでは100枚、それ以外のモデルでは600枚です。ただし、枚数より先に32MBのリクエストサイズの上限に当たることがあります。画像を何度も使い回すなら、Files APIでアップロードして file_id で参照する方法もあります。

2000pxに縮めると読み取りは悪くなるのか

縮めると文字が潰れないか、と心配になります。ビジョンドキュメントによると、モデルには「最大の長辺」と「視覚トークンの上限」があり、どちらかを超えた画像は処理前に縮小されます。標準の解像度帯のモデルは、長辺1568px・視覚トークン1568が上限です。

同じページの換算表では、1920×1080pxの画像は1456×819pxに縮小されて1560トークンになります。標準帯のモデルでは、2000px以内に揃えた画像がそこから読み取り用にさらに縮められることもあります。

Claude 4.7以降のモデルは高解像度帯で、上限は長辺2576px・視覚トークン4784です。換算表の2000×1500pxの画像は、標準帯だと1269×952px(1564トークン)に縮みます。高解像度帯では縮小されず、3888トークンで読み取られます。使うモデルが4.7以降なら、2000pxに揃えた画像が読み取り側でさらに縮められることはありません。

例外が、コンピューター操作やブラウザー操作のツールセットへ返すスクリーンショットです。ドキュメントによると、この tool_result の画像はモデルの上限を超えると縮小されずに検証エラーで拒否されます。これらのツールを自前で実装して画像を返すなら、返す側で縮めておく必要があります。

文字の細かいスクリーンショットでは、全体を縮めるより、読ませたい範囲だけを切り取るほうが文字が潰れません。

すぐに試せる対処

寸法が原因なので、対処は画像を小さくする方向に絞られます。

macOSのsipsで縮める

macOSには sips が標準で入っています。-Z 2000 で長辺を2000pxに揃えられます。

sips -Z 2000 screenshot.png

macOS付属の画像(1234×834px)で試したところ、このコマンドは小さい画像まで2000pxに引き伸ばしました。結果は2000×1351pxで、縮小ではなく拡大です。ピクセル数が増えるぶん、上限に近づく方向に働いてしまいます。ちなみに sips -Z を出力先なしで実行すると、元のファイルをそのまま上書きします。

超えているものだけを縮めるなら、寸法を先に読む形にします。5920×4000pxの画像は2000×1351pxに縮み、1234×834pxの画像はそのままでした。

for f in *.png; do
  w=$(sips -g pixelWidth "$f" | awk '/pixelWidth/{print $2}')
  h=$(sips -g pixelHeight "$f" | awk '/pixelHeight/{print $2}')
  if [ "$w" -gt 2000 ] || [ "$h" -gt 2000 ]; then sips -Z 2000 "$f"; fi
done

この確認は、手元のmacOSのsips-316で行いました。ImageMagickが入っている環境(WindowsやLinux)では、> を付けると縮小だけを行い、拡大はしません。

magick screenshot.png -resize '2000x2000>' screenshot-small.png

ImageMagickの > は縮小専用の指定です。この環境にはImageMagickが入っていないため、実行結果は確認していません。

v2.1.142より前は何が違ったか

失敗したときの挙動は、バージョンで変わっています。Claude Codeのエラー一覧とchangelogに載っている内容は次のとおりです。

v2.1.142より前で詰まった場合、Escを2回押して、画像を貼ったターンの手前まで戻る必要があります。画面のメッセージにある「Double press esc」は、この復旧手順のことです。

v2.1.157のchangelogは、貼り付け・MCP・ダイアログのいずれの経路でも、処理できない画像が会話を落とさなくなったと書いています。v2.1.287で確認した手元のCLIには、画像を扱う専用のオプションはありません。claude --help の出力に画像の項目は出ませんでした。

なお、v2.1.287の更新では、リモートセッションからClaudeが送る長辺8000px超のPNG・JPEG・WebPが送れない問題も修正されています。縮小したコピーを送る動作になりました。これは貼り付けた画像の上限エラーとは別の経路の修正です。

似たエラーとの見分け方

画像まわりで出るエラーには、原因の違う3種類があります。画面の文言で切り分けられます。

「Unable to resize image」は、Claude Codeが画像を縮小できなかったときのエラーです。CMYKのJPEGやアニメーションWebP、破損ファイルが典型で、メッセージに原因が書かれます。詳しくは「Unable to resize image」が出る原因と対処法で扱っています。

「Request too large」は、画像1枚の大きさではなく、会話全体の送信データが32MBを超えたときのエラーです。画像や添付が積み重なった会話で出ます。v2.1.212より前は、画像が溜まった会話でターンごとに失敗し続けていました。

v2.1.229以降は、文言で原因が分かれます。Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents). のように画像やドキュメントの内訳が出る場合は、それらが上限を押し上げています。Claude Codeは画像などを取り除いて再試行します。Request too large for the API's 32MB request limit と出る場合は、メッセージだけで上限を超えており、compacting cannot make it fit とあるとおり再試行されません。この場合は /compact が効かないので、Escを2回押して大きな内容を足したターンの手前へ戻るか、/clear で最初からやり直します。

エラーをまとめて確認したい場合はClaude Codeでよくあるエラー10選も参考になります。

claude.aiのチャット添付との違い

同じ画像でも、claude.aiのチャットとClaude Codeでは、上限の決まり方が違います。ビジョンドキュメントによると、claude.aiは1メッセージあたり画像20枚まで、1枚あたり10MBまでで、寸法の上限は8000×8000pxです。ヘルプセンターは、チャット添付のファイル全般を1ファイル500MB・1チャット20ファイルまでと書いており、画像の10MBとは粒度が違います。ファイル形式ごとのアップロード上限はClaudeのPDF読み込み・画像解析の使い方とアップロード上限で扱っています。

claude.aiは1メッセージの枚数を20枚で止める作りです。Claude Codeは1つの会話の中で画像が積み重なるため、API側の「20枚を超えると厳しい上限」に会話の途中で入り込む余地があります。

画像が多いセッションの組み立て方

20枚の線を越えにくくするには、次の3つが効きます。

1. 画像を貼る前に、長辺を2000px以内に揃える。揃えておけば、20枚を超えても上限に触れない
2. 確認が終わった画像は /compact で落とす。落とした分だけ、数に入る画像が減る
3. 画像を渡す必要がないときは、ファイルのパスで渡して読ませる

3つ目は、公式ドキュメントが「Request too large」の対処として挙げている「大きな内容を貼り付けず、パスで参照する」方針の応用です。画像をパスで読ませたときの寸法の扱いは、公式には書かれていません。

まとめ

エラーの切り分けは、画面の文言と、どの場面で出たかで決まります。1枚だけ貼った場面で出るなら寸法側です。画像を重ねた会話で出るなら、20枚側を疑います。文言が「Request too large」なら、見るのは32MB側です。