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

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

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

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



Claudeが画像をリサイズしてパディングする方法

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

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

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

ほぼすべての写真やスクリーンショットでは、最終的なサイズを決定するのはビジュアルトークン制限です。エッジ制限が優先されるのは、パノラマや縦長のスマートフォンのスクリーンショットなど、細長い画像の場合のみです。エッジ長に手動でスケーリングするのではなく、リファレンス実装でサイズを計算してください。1920×1080のスクリーンショットは1456×819にリサイズされ、1568×882にはなりません。エッジ制限を前提にすると、すべての座標が目に見えてターゲットからずれます。

どちらの辺もエッジ制限を超えていない場合でも、トークン制限によってリサイズが発生することがあります。これを見落とすことが、座標のずれの最も一般的な原因です。たとえば、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)

# リサイズを適用するには、Pillow などの画像ライブラリを使用します：
# image.resize(resized_size(*image.size))

1. リサイズヘルパーが返す寸法に画像をリサイズします。画像がすでにモデルの制限内に収まっている場合、ヘルパーはその寸法をそのまま返し、リサイズは不要です。
2. リサイズした画像をAPIに送信します。自分でパディングしないでください。パディングはClaudeが処理し、パディングによって座標の原点がずれることはありません。
3. プロンプトで、ピクセル座標を明示的に要求します。例：「Submitボタンのクリックポイントを、ピクセル座標で [x, y] として返してください。」
4. 返された座標を、送信した画像に対してそのまま使用します。正規化された座標が必要な場合は、元画像の寸法やパディング後の寸法ではなく、送信した画像の寸法で割ってください。



事前リサイズできない場合に座標を再スケーリングする

事前リサイズができない場合（たとえば、変更できない上流システムから画像が来る場合）は、アップロード前に画像をリサイズするのリサイズヘルパーを使用してClaudeが見た寸法を復元し、Claudeが返す座標を正規化座標に変換するか、元の画像にマッピングし直します。Claudeは、APIのリクエスト制限までは、サイズ超過の画像を拒否せずにリサイズします。その制限を超えると、リクエストはバリデーションエラーで失敗します。呼び出したモデルに対応するティアの制限を渡してください。誤ったティアの制限では誤ったリサイズ後の寸法が復元され、すべての座標が気づかないうちにずれます。このアプローチはアップロードした画像のピクセル寸法を知っている必要があるため、PDFのアップロードには適用できません。

# このヘルパーは本ページのリサイズ例にある resized_size を呼び出します。
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)


# リサイズ後の A4 ページ上で Claude が (462, 653.5) として返す表の角は、
# 1075x1520 の元画像に次のようにマッピングされます：
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

パディングは下端と右端にのみ適用されるため、原点はずれず、軸ごとの線形再スケーリングで十分です。再スケーリングの前に、返された座標をリサイズ後の寸法にクランプしてください。これにより、画像のわずかに外側にあるポイントが元画像の外側にマッピングされることを防げます。

相対座標は、操作対象となるあらゆる面（元の画像、フル解像度のスキャン、画面など）に対して乗算できます。画面に対して操作を行い、スクリーンショットのピクセルが論理座標と異なる場合（HiDPIディスプレイ）は、ディスプレイのスケールファクターでも割ってください。コンピュータ使用ツールのスケーリングガイダンスでそのパターンを説明しています。



次のステップ