座標與邊界框

Claude 可以定位並標記影像中的區域（例如，回傳表格、表單欄位、圖表元素或 UI 元件的邊界框）。本指南說明 Claude 在處理影像之前如何調整影像大小，以及如何處理它回傳的像素座標，讓邊界框和點能與您的原始影像對齊。

您在 OCR 管線、表單擷取、圖表解析、UI 元素定位，以及任何需要對影像特定區域採取動作的任務中都會需要這些資訊。關於傳送影像、支援的格式以及各模型的解析度限制，請參閱視覺。

座標遵循標準影像慣例：原點 (0, 0) 位於影像的左上角，x 向右遞增，y 向下遞增。Claude 回傳的座標是 Claude 所看到影像中的像素位置：也就是 Claude 將您的影像調整大小以符合模型原生解析度之後的影像（請參閱 Claude 如何調整影像大小與填補影像）。若要取得可直接使用的座標，您可以在上傳前預先調整影像大小，讓座標與您手上的影像一對一對應（請參閱上傳前調整影像大小），或是重新縮放 Claude 回傳的座標（請參閱無法預先調整大小時重新縮放座標）。

Claude 如何調整影像大小與填補影像

Claude 會找出同時滿足模型兩項影像限制、且保持長寬比的最大尺寸：

1. 邊長限制： 任一邊都不超過最大邊長（標準層級為 1568 px，高解析度層級為 2576 px）。
2. 視覺 token 限制： 影像的 token 成本 ⌈width / 28⌉ × ⌈height / 28⌉ 不超過模型的視覺 token 預算（標準層級為 1568 個 token，高解析度層級為 4784 個）。

請參閱解析度與 token 成本以了解各模型所屬的層級。

對於幾乎所有的照片和螢幕截圖，決定最終尺寸的是視覺 token 限制。只有在全景圖或長條形手機截圖等狹長影像上，邊長限制才會起主導作用。請使用參考實作計算尺寸，而不要手動依邊長縮放：一張 1920×1080 的螢幕截圖會調整為 1456×819，而非 1568×882，若假設適用邊長限制，會讓每個座標明顯偏離目標。

即使任一邊都未超過邊長限制，token 限制也可能觸發調整大小。忽略這一點是座標錯位最常見的原因。例如，以 130 DPI 掃描的 A4 頁面為 1075×1520 像素：兩邊都小於 1568 px，但它需要 39 × 55 = 2145 個視覺 token，因此 Claude 會將其調整為 924×1307。

接著，Claude 會將每張影像（無論是否經過調整大小）在底部和右側邊緣填補至下一個 28 像素的倍數（在此範例中，924×1307 會變成 924×1316）。填補區域不含任何內容：Claude 感知的是填補後的影像，但頁面內容永遠只佔據未填補的調整後區域。請一律以調整後的尺寸進行正規化或重新縮放，而非填補後的尺寸；以填補後的尺寸相除會使每個座標產生少量的縮放偏差。

上傳前調整影像大小

最可靠的方法是在上傳前自行調整影像大小，如此您手上的影像就正是 Claude 所看到的影像，Claude 回傳的座標也無需轉換。

首先確認您的模型屬於哪個解析度層級（請參閱解析度與 token 成本），並傳入對應的邊長與 token 限制。以下參考實作可計算 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"

請重新縮放至回報的目標尺寸後重新傳送：該目標是在您影像的長寬比下，請求中指定的每個模型都能接受的最大尺寸。已標記影像與伺服器端備援 beta 的互動方式於該功能中說明；在任何模式下，已標記的影像都絕不會以調整大小後的形式提供。

此設定是針對每張影像的。"oversized_image": "downsize"（省略該欄位時的預設值）會維持本頁所述的自動調整大小。每個影像區塊只會依其自身的設定進行檢查，因此同一個請求可以混合尺寸具關鍵意義的影像（您將點擊的螢幕截圖）與調整大小無妨的影像（標誌）。此設定會改變與不會改變的事項：

• 填補（永遠不會捨棄內容）、格式轉換與方向校正照常進行。
• 硬性限制（最長邊 8000 px，以及多影像請求中更嚴格的每張影像限制）屬於另外的拒絕條件；此設定絕不會讓影像繞過這些限制。
• 以 URL 或檔案 ID 提供的影像會在其位元組擷取完成後進行檢查；這些拒絕帶有相同的訊息，但沒有開頭的位置資訊，因此無法識別是哪張影像失敗；只有內嵌的 base64 影像會在錯誤中以位置標示。
• PDF 頁面會在伺服器端以您無法控制的尺寸點陣化；document 區塊不接受此欄位（巢狀於文件內容中的影像區塊則與其他影像區塊一樣接受此欄位）。
• 無法判定尺寸的已標記影像會遭拒絕，而非直接放行：該拒絕會回報無法判定影像的來源尺寸，而非上方引述的調整大小訊息。任何設定了 "error" 的影像都不會以調整大小後的形式送達模型。

Token 計數端點同樣遵循 transformations，會以與 Messages API 完全相同的方式拒絕內嵌圖片，因此您可以在執行推論之前，檢查內嵌圖片是否能在不調整大小的情況下符合限制。計數端點會直接拒絕透過 URL 或檔案 ID 提供的圖片，而不會擷取它們，因此來自這些來源的被標記圖片只會在呼叫 Messages 時進行檢查。

無法預先調整大小時重新縮放座標

如果您無法預先調整大小（例如，影像來自您無法修改的上游系統），請使用上傳前調整影像大小中的調整大小輔助函式來還原 Claude 所看到的尺寸，然後將 Claude 回傳的座標對應為正規化座標，或對應回您的原始影像。除非影像選擇改為回傳錯誤，否則在 API 的請求限制範圍內，Claude 會調整過大影像的大小而非拒絕它們。超出這些限制時，請求會改以驗證錯誤失敗。請傳入與您所呼叫模型相符的層級限制：錯誤層級的限制會還原出錯誤的調整後尺寸，並悄悄地使每個座標偏移。此方法需要知道您所上傳影像的像素尺寸，因此不適用於 PDF 上傳。

您回傳給電腦使用與瀏覽器使用工具集的螢幕截圖與縮放影像是自動調整大小的例外。API 會以驗證錯誤拒絕超出模型限制的 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)


# Claude 在調整大小後的 A4 頁面上回傳位於 (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 顯示器），還需除以顯示縮放係數。電腦使用工具的縮放指引涵蓋了該模式。

後續步驟