座標とバウンディングボックス

Claudeは画像内の領域を特定してラベル付けできます（たとえば、表、フォームフィールド、チャート要素、UIコンポーネントのバウンディングボックスを返すなど）。このガイドでは、Claudeが画像を処理する前にどのようにリサイズするか、および返されるピクセル座標の扱い方について説明します。これにより、ボックスやポイントを元の画像に正しく合わせることができます。

これは、OCRパイプライン、フォーム抽出、チャート解析、UI要素の位置特定、および画像の特定領域に対して操作を行うあらゆるタスクで必要になります。画像の送信方法、サポートされている形式、モデルごとの解像度制限については、ビジョンを参照してください。

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



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

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

1. 辺の制限： どちらの辺も最大辺長（標準ティアでは1568 px、高解像度ティアでは2576 px）を超えないこと。
2. ビジュアルトークン制限： 画像のトークンコスト ⌈width / 28⌉ × ⌈height / 28⌉ がモデルのビジュアルトークン予算（標準ティアでは1568トークン、高解像度ティアでは4784トークン）を超えないこと。

どのモデルがどのティアに属するかについては、解像度とトークンコストを参照してください。

ほとんどの写真やスクリーンショットでは、辺の制限がリサイズのトリガーになります。縦長のドキュメントでは通常、ビジュアルトークン制限が先にトリガーされ、これを見落とすことが座標のずれの最も一般的な原因です。たとえば、130 DPIでスキャンされたA4ページは1075×1520ピクセルです。両辺とも1568 px未満ですが、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 the standard resolution tier. For high-resolution-tier
    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 high-resolution-tier
    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)
# 　

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



関連情報

• コンピュータ使用ツールでは、スクリーンショットがすでに画像サイズ制限内に収まっている必要があります（サイズ超過のスクリーンショットはリサイズされず拒否されます）。クライアント側のリサイズと座標スケーリングのパターンについては、そのスケーリングガイダンスを参照してください。
• PDFサポート：ページはサーバー側でユーザーが制御できない寸法でラスタライズされるため、PDFコンテンツで座標が必要な場合は、自分でページをラスタライズし、事前リサイズのアプローチを使用してください。