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

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

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

座標は標準的な画像の規則に従います。原点 (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のスクリーンショットは1568×882ではなく1456×819にリサイズされます。辺の制限だけを前提にすると、すべての座標がターゲットから目に見えてずれます。

トークン制限は、どちらの辺も辺の制限を超えていない場合でもリサイズを引き起こすことがあります。これを見落とすことが、座標がずれる最も一般的な原因です。たとえば、130 DPIでスキャンしたA4ページは1075×1520ピクセルです。両辺とも1568 px未満ですが、コストは 39 × 55 = 2145 ビジュアルトークンになるため、Claudeはこの画像を924×1307にリサイズします。

次にClaudeは、リサイズの有無にかかわらず、すべての画像の下端と右端に「padding」（パディング）を追加し、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. 返された座標は、送信した画像に対してそのまま使用します。正規化座標が必要な場合は、送信した画像の寸法で割ってください。元の画像の寸法やパディング後の寸法で割ってはいけません。

transformations でリサイズをエラーにする

事前リサイズで座標を保護できるのは、パイプラインが正しいサイズの画像を生成し続けている間だけです。新しい画像ソースを追加したり、異なる解像度ティアのモデルに切り替えたりすると、サーバー側のリサイズが気づかないうちに再び発生する可能性があります。このような気づきにくいずれを目に見えるエラーにするには、Messagesリクエストの画像コンテンツブロックに、オプションの transformations フィールドを設定します。

{
  "type": "image",
  "source": { "type": "base64", "media_type": "image/png", "data": "..." },
  "transformations": { "oversized_image": "error" }
}

マークされた画像（"oversized_image": "error" を設定したブロック）がリサイズの対象になる場合、そのリクエストは400 invalid_request_error で拒否されます。エラーには、画像の寸法と、制限内に収まる最大の寸法が示されます。画像が拒否されるかどうかは、リクエストで指定されたすべてのモデルの制限によって決まります。以下の1920×1080の例は、標準ティアのモデルでは拒否されますが、高解像度ティアの制限内には収まります。

messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"

報告されたターゲットサイズに再スケーリングして、再送信してください。ターゲットサイズは、画像のアスペクト比を保ったまま、リクエストで指定されたすべてのモデルが受け入れる最大のサイズです。マークされた画像とサーバー側フォールバックベータとの関係については、その機能のページで説明しています。どのモードでも、マークされた画像がリサイズされた状態で処理されることはありません。

この設定は画像ごとに指定します。"oversized_image": "downsize"（フィールドを省略した場合のデフォルト）を指定すると、このページで説明したとおり自動リサイズが行われます。各画像ブロックは自身の設定に対してのみチェックされます。そのため、1つのリクエストの中で、寸法が重要な画像（クリック操作の対象となるスクリーンショットなど）と、リサイズされても問題のない画像（ロゴなど）を混在させることができます。この設定によって変わる点と変わらない点は次のとおりです。

• パディング（コンテンツを破棄することはありません）、形式変換、向きの補正は通常どおり行われます。
• ハード制限（最長辺8000 px、および多数の画像を含むリクエストに適用される、より厳しい画像ごとの制限）による拒否は、この設定とは別に行われます。この設定によって、画像がこれらの制限を回避できることはありません。
• URLまたはファイルIDで指定された画像は、バイトデータが取得された時点でチェックされます。これらの画像が拒否された場合、エラーメッセージの内容は同じですが、先頭の位置情報が含まれないため、どの画像が失敗したかは特定できません。エラーで位置が示されるのは、埋め込まれたbase64画像だけです。
• PDFページは、ユーザーが制御できない寸法でサーバー側でラスタライズされます。document ブロックはこのフィールドを受け付けません（ただし、ドキュメントのコンテンツ内にネストされた画像ブロックは、他の画像ブロックと同様にこのフィールドを受け付けます）。
• 寸法を特定できないマークされた画像は、そのまま通過せずに拒否されます。この場合のエラーは、上記のリサイズに関するメッセージではなく、画像のソース寸法を特定できなかったことを示します。"error" を設定した画像が、リサイズされた状態でモデルに届くことはありません。

トークンカウントエンドポイントも transformations に対応しており、埋め込み画像をMessages APIとまったく同じ条件で拒否します。そのため、推論を実行する前に、埋め込み画像がリサイズされずに収まるかどうかを確認できます。ただし、トークンカウントでは、URLまたはファイルIDで指定された画像は取得されずに拒否されます。そのため、これらのソースから指定したマークされた画像は、Messagesリクエストの時点でのみチェックされます。

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

事前にリサイズできない場合（たとえば、変更できない上流システムから画像が送られてくる場合）は、次の手順で座標を変換します。

1. アップロード前に画像をリサイズするのリサイズヘルパーを使用して、Claudeが見た画像の寸法を求めます。
2. Claudeが返す座標を、正規化座標に変換するか、元の画像上にマッピングし直します。

画像で代わりにエラーを返す設定をしていない限り、Claudeはサイズ超過の画像を拒否せずにリサイズします。ただし、これはAPIのリクエスト制限の範囲内に限られ、制限を超えるとリクエストは検証エラーで失敗します。リサイズヘルパーには、呼び出したモデルに対応するティアの制限を渡してください。誤ったティアの制限を渡すと、誤ったリサイズ後の寸法が求められ、すべての座標が気づかないうちにずれます。この方法では、アップロードした画像のピクセル寸法がわかっている必要があるため、PDFのアップロードには使用できません。

computer use（コンピュータ使用）およびbrowser use（ブラウザ使用）のツールセットに返すスクリーンショットやズーム画像は、自動リサイズの対象外です。モデルの制限を超える tool_result 画像は、リサイズされずに検証エラーで拒否されます。これらの画像は、返す前にアプリケーション側でリサイズしてください。そのうえで、Claudeが返す座標を画面の寸法にスケーリングし直します。

# このヘルパーは本ページのリサイズ例にある 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ディスプレイなど）は、さらにディスプレイのスケールファクターで割ってください。このパターンについては、コンピュータ使用ツールのスケーリングに関するガイダンスで説明しています。

次のステップ