ビジョン

このガイドでは、Claudeで画像を扱う方法について、ベストプラクティス、コード例、留意すべき制限事項を含めて説明します。



ビジョンの使用方法

Claudeのビジョン機能は、以下の方法で利用できます。

• claude.ai。ファイルと同様に画像をアップロードするか、チャットウィンドウに画像を直接ドラッグアンドドロップします。
• Console Workbench。各Userメッセージブロックの右上に画像を追加するボタンが表示されます。
• APIリクエスト。このガイドの例を参照してください。

1つのリクエストに複数の画像を含めることができ、Claudeは応答を作成する際にそれらをまとめて分析します。これは画像を比較または対比する際に役立ちます。



アップロード前の確認事項



一般的な制限

メッセージまたはリクエストあたりの画像の最大数は以下のとおりです。

• claude.aiではメッセージあたり20枚。
• APIでは、200kトークンのコンテキストウィンドウを持つモデルの場合、リクエストあたり100枚。
• APIでは、その他すべてのモデルの場合、リクエストあたり600枚。

画像あたりの最大寸法は8000x8000ピクセルです。

1つのAPIリクエストに20枚を超える画像が含まれる場合、より厳しい画像ごとの寸法制限が適用されます。Amazon BedrockおよびVertex AIでは、PDFなどのドキュメントブロックもこのしきい値にカウントされます。より厳しい制限を超える画像は、「many-image requests」を参照し現在のピクセル制限を示すメッセージを含むinvalid_request_errorで拒否されます。すべてのプラットフォームで制限内に収めるには、各画像のどの辺も2000ピクセルを超えないようにリサイズするか、リクエストを20以下の画像およびドキュメントブロックに抑えてください。

画像あたりの最大サイズは以下のとおりです。

• Claude APIを直接使用する場合は10 MB（base64エンコード）。
• Amazon BedrockおよびVertex AIでは5 MB（base64エンコード）。
• claude.aiでは10 MB。



画像サイズの評価

Claudeは画像をピクセルではなくパッチ単位で認識します。各パッチは画像の28×28ピクセルのブロックで、「visual token」（ビジュアルトークン）と呼ばれます。したがって、画像のコストは⌈width / 28⌉ × ⌈height / 28⌉ビジュアルトークンとなります。

Claudeが大きすぎる画像を受け取った場合、リサイズされます。ネイティブの最大画像解像度は以下のとおりです。

• Claude Fable 5およびClaude Mythos 5の場合：4784トークン、長辺で最大2576ピクセル。
• Claude Opus 4.8の場合：4784トークン、長辺で最大2576ピクセル。
• Claude Opus 4.7の場合：4784トークン、長辺で最大2576ピクセル。
• その他のモデルの場合：1568トークン、長辺で最大1568ピクセル。

レイテンシを最小限に抑え、座標ベースのワークフローを簡素化するために、アップロード前に画像をリサイズすることをお勧めします。



画像コストの計算

リクエストに含める各画像はトークン使用量にカウントされます。おおよそのコストを計算するには、画像のビジュアルトークン数（画像サイズの評価を参照）に、使用しているモデルのトークンあたりの価格を掛けます。

以下は、Claude Sonnet 4.6の入力トークン100万あたり$3というトークン単価に基づいた、APIのサイズ制約内でのさまざまな画像サイズのトークン化とおおよそのコストの例です。

最後の3つの画像はネイティブ解像度を超えており、処理前にダウンスケールされます（それぞれ1456x819 px、1270x952 px、1456x819 px）。これによりトークンコストに上限が設けられます。4K画像は1920x1080画像と同じサイズにダウンスケールされるため、コストは同じです。余分な解像度は破棄されます。



高解像度画像のサポート

Claude Opus 4.7は、高解像度画像をサポートする最初のClaudeモデルです。Claude Opus 4.8、Claude Fable 5、Claude Mythos 5、およびそれ以降のモデルもこれをサポートしています。最大画像解像度は長辺で2576ピクセルで、以前のモデルの1568ピクセルから向上しています。これにより、ビジョンを多用するワークロードでのパフォーマンスが向上し、特にコンピュータ操作、スクリーンショットの理解、ドキュメント分析において価値があります。

高解像度サポートはClaude Opus 4.7以降のモデルで自動的に有効になり、ベータヘッダーやクライアント側のオプトインは不要です。

Claude Opus 4.7、Claude Opus 4.8、Claude Fable 5、Claude Mythos 5での高解像度画像は、以前のモデルと比較して最大約3倍の画像トークンを使用する可能性があります（画像あたり4784トークン対1568トークン）。追加の精細度が不要な場合は、送信前に画像をダウンサンプリングしてトークンコストを抑えてください。

以下は、Claude Opus 4.7およびClaude Opus 4.8の入力トークン100万あたり$5というトークン単価に基づいた、同じ画像サイズのトークン化の例です。

より高い制限を超えるのは最後の画像のみです。4K画像は処理前に2576x1449 pxにダウンスケールされます。高解像度サポートは解像度の制限を引き上げますが、制限自体をなくすわけではありません。長辺が2576ピクセル（または4784ビジュアルトークン）を超える画像は引き続きダウンスケールされます。



画像品質の確保

Claudeに画像を提供する際は、最良の結果を得るために以下の点に留意してください。

• 画像形式：サポートされている画像形式（JPEG、PNG、GIF、またはWebP）を使用してください。
  アニメーションはサポートされておらず、最初のフレームのみが使用されます。
• 画像の鮮明さ：画像が鮮明で、ぼやけすぎたりピクセル化しすぎたりしていないことを確認してください。
• テキスト：画像に重要なテキストが含まれている場合は、判読可能で小さすぎないことを確認してください。テキストを拡大するためだけに重要な視覚的コンテキストを切り取らないようにしてください。
• リサイズ：画像が大きすぎる場合はリサイズされる可能性があることを考慮してください（上記参照）。これにより、たとえばテキストが判読しにくくなる可能性があります。事前に画像をリサイズする、トリミングする、またはその両方を検討してください。
• 画像圧縮：JPEGやWebP（非可逆モード）などの非可逆形式を使用して送信前に画像を圧縮すると、リクエストサイズが小さくなりレイテンシを削減できます。ただし、これによりモデルのパフォーマンスに悪影響を与えるアーティファクトが発生する可能性があり、特に複数回の圧縮が適用された場合に顕著です。たとえば、強いJPEG圧縮はテキストを読みにくくする可能性があります。APIに送信される実際の画像を確認して、圧縮設定がタスクに適していることを確認してください。



座標とバウンディングボックスの扱い方

Claudeは画像内の領域を特定してラベル付けできます（たとえば、表、フォームフィールド、チャート要素、UIコンポーネントのバウンディングボックスを返すなど）。

座標は標準的な画像の規則に従います。原点(0, 0)は画像の左上隅で、xは右方向に、yは下方向に増加します。Claudeが返す座標は、Claudeが認識する画像内のピクセル位置です。つまり、モデルのネイティブ解像度に合わせてClaudeがリサイズした後の画像です（Claudeによる画像のリサイズとパディング方法を参照）。直接使用できる座標を取得するには、座標が手元の画像に1対1で対応するように画像を事前にリサイズするか（アップロード前に画像をリサイズするを参照）、Claudeが返す座標を再スケールします（事前リサイズできない場合の座標の再スケールを参照）。



Claudeによる画像のリサイズとパディング方法

Claudeは、モデルの両方の画像制限を満たす、アスペクト比を保持した最大サイズを見つけます。

1. 辺の制限： どの辺も最大辺長（ほとんどのモデルでは1568ピクセル、Claude Opus 4.7以降のモデルでは2576ピクセル）を超えない。
2. ビジュアルトークンの制限： 画像のトークンコスト⌈width / 28⌉ × ⌈height / 28⌉がモデルのビジュアルトークン予算（ほとんどのモデルでは1568トークン、Claude Opus 4.7以降のモデルでは4784トークン）を超えない。

ほとんどの写真やスクリーンショットでは、辺の制限がリサイズのトリガーとなります。縦長のドキュメントでは通常、ビジュアルトークンの制限が先にトリガーされ、これを見落とすことが座標のずれの最も一般的な原因です。たとえば、130 DPIでスキャンされたA4ページは1075×1520ピクセルです。両辺とも1568ピクセル未満ですが、39 × 55 = 2145ビジュアルトークンのコストがかかるため、Claudeはこれを924×1307にリサイズします。

Claudeは、リサイズされたかどうかにかかわらず、すべての画像の下端と右端を次の28ピクセルの倍数までパディングします（この例では924×1307が924×1316になります）。パディングにはコンテンツが含まれません。Claudeはパディングされた画像を認識しますが、ページコンテンツはパディングされていないリサイズ後の領域のみを占めます。常にパディング後の寸法ではなく、リサイズ後の寸法で正規化または再スケールしてください。パディング後の寸法で割ると、すべての座標がわずかにスケールされてしまいます。



アップロード前に画像をリサイズする

最も信頼性の高いアプローチは、アップロード前に自分で画像をリサイズすることです。これにより、手元の画像がClaudeが認識する画像とまったく同じになり、Claudeが返す座標に変換が不要になります。

以下のリファレンス実装は、Claudeが画像をリサイズする正確なサイズを計算します。

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for most models. For Claude Opus 4.7 and later models, use
    max_edge=2576 and max_tokens=4784. Returns (width, height). Images that
    already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # 長辺に沿って二分探索を行い、アスペクト比を保ったまま収まる
    # 最大サイズを求めます。
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# 「Claudeが画像をリサイズ・パディングする方法」のA4の例：
print(resized_size(1075, 1520))  # (924, 1307)

1. resized_sizeが返す寸法に画像をリサイズします。画像がすでにモデルの制限内に収まっている場合、resized_sizeは寸法をそのまま返し、リサイズは不要です。
2. リサイズした画像をAPIに送信します。自分でパディングしないでください。Claudeがパディングを処理し、パディングは座標の原点をシフトしません。
3. プロンプトで、ピクセル座標を明示的に求めます。例：「各表のバウンディングボックスをピクセル座標で[x1, y1, x2, y2]として返してください。」
4. 返された座標を、送信した画像に対して直接使用します。正規化された座標が必要な場合は、元の画像の寸法やパディング後の寸法ではなく、送信した画像の寸法で割ります。



事前リサイズできない場合の座標の再スケール

事前にリサイズできない場合（たとえば、変更できない上流システムから画像が来る場合）、アップロード前に画像をリサイズするのresized_sizeを使用してClaudeが認識した寸法を復元し、Claudeが返す座標を正規化された座標または元の画像にマッピングし直します。このアプローチでは、アップロードした画像のピクセル寸法を知っている必要があるため、PDFアップロードには適用されません。

def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For Claude Opus 4.7 and
    later models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# 元の画像のピクセル空間で座標を表すには、相対座標に元の寸法を掛けます：
# (rel_x * original_width, rel_y * original_height)
# 　

パディングは下端と右端にのみ適用されるため、原点はシフトせず、軸ごとの線形再スケールで十分です。



プロンプトの例

Claudeとのテキストベースのインタラクションで効果的なプロンプト技法の多くは、画像ベースのプロンプトにも適用できます。

これらの例は、画像を含むベストプラクティスのプロンプト構造を示しています。



プロンプト例について

以下の例は、さまざまなプログラミング言語とアプローチを使用してClaudeのビジョン機能を使用する方法を示しています。Claudeに画像を提供する方法は3つあります。

1. imageコンテンツブロック内のbase64エンコードされた画像として
2. オンラインでホストされている画像へのURL参照として
3. Files APIを使用（一度アップロードして複数回使用）

base64の例のプロンプトでは、以下の変数を使用します。

import base64
import httpx

# base64エンコードされた画像の場合
image1_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image1_media_type = "image/jpeg"
image1_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

image2_url = "https://upload.wikimedia.org/wikipedia/commons/b/b5/Iridescent.green.sweat.bee1.jpg"
image2_media_type = "image/jpeg"
image2_data = base64.standard_b64encode(httpx.get(image2_url).content).decode("utf-8")

# URLベースの画像の場合、リクエストでURLを直接使用できます

以下は、base64エンコードされた画像とURL参照を使用してMessages APIリクエストに画像を含める方法の例です。



Base64エンコードされた画像の例

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



URLベースの画像の例

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



Files API画像の例

繰り返し使用する画像や、エンコードのオーバーヘッドを避けたい場合は、Files APIを使用します。画像を一度アップロードし、その後のメッセージではbase64データを再送信する代わりに、返されたfile_idを参照します。

client = anthropic.Anthropic()

# 画像ファイルをアップロードする
with open("image.jpg", "rb") as f:
    file_upload = client.beta.files.upload(file=("image.jpg", f, "image/jpeg"))

# アップロードしたファイルをメッセージで使用する
message = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

その他のコード例とパラメータの詳細については、Messages APIの例を参照してください。



制限事項

Claudeの画像理解機能は最先端ですが、いくつかの制限事項があります。

• 人物の識別：Claudeは画像内の人物を特定するために使用することはできず、そのような要求を拒否します。
• 精度：Claudeは、低品質、回転された、または200ピクセル未満の非常に小さな画像を解釈する際に、幻覚を起こしたり間違いを犯したりする可能性があります。
• 空間推論：Claudeの座標および位置特定の出力は近似値です。座標とバウンディングボックスの扱い方のガイダンスに従い、出力に依存する前に検証してください。
• カウント：Claudeは画像内のオブジェクトのおおよその数を示すことができますが、特に多数の小さなオブジェクトの場合、常に正確であるとは限りません。
• AI生成画像：Claudeは画像がAI生成かどうかを知らず、尋ねられた場合に誤った回答をする可能性があります。偽物や合成画像の検出にClaudeを頼らないでください。
• 不適切なコンテンツ：Claudeは、利用規定に違反する不適切または露骨な画像を処理しません。
• 医療アプリケーション：Claudeは一般的な医療画像を分析できますが、CTやMRIなどの複雑な診断スキャンを解釈するようには設計されていません。Claudeの出力は、専門的な医療アドバイスや診断の代替と見なすべきではありません。

特に重要度の高いユースケースでは、Claudeの画像解釈を常に慎重にレビューし検証してください。人間の監視なしに、完璧な精度や機密性の高い画像分析を必要とするタスクにClaudeを使用しないでください。



FAQ



ビジョンをさらに深く学ぶ

Claudeで画像を使った構築を始める準備はできましたか？以下は役立つリソースです。

• マルチモーダルクックブック：このクックブックには、画像の使い始め方のヒントや、画像で最高品質のパフォーマンスを確保するためのベストプラクティス技法が含まれています。チャートの解釈と分析やフォームからのコンテンツ抽出などのタスクを実行するために、画像を使ってClaudeに効果的にプロンプトを与える方法をご覧ください。
• APIリファレンス：画像を含むAPI呼び出しの例を含む、Messages APIのドキュメント。

その他のご質問がある場合は、サポートチームにお問い合わせください。また、開発者コミュニティに参加して、他のクリエイターとつながり、Anthropicの専門家からサポートを受けることもできます。