坐标与边界框

Claude 可以定位并标注图像中的区域（例如，为表格、表单字段、图表元素或 UI 组件返回边界框）。本指南介绍 Claude 在处理图像之前如何调整图像大小，以及如何处理它返回的像素坐标，以便边界框和点能够与您的原始图像对齐。

在 OCR 流水线、表单提取、图表解析、UI 元素定位，以及任何需要对图像特定区域进行操作的任务中，您都会需要这些内容。有关发送图像、支持的格式以及各模型的分辨率限制，请参阅视觉。

坐标遵循标准图像约定：原点 (0, 0) 位于图像的左上角，x 向右递增，y 向下递增。Claude 返回的坐标是 Claude 所看到的图像中的像素位置：即 Claude 将您的图像调整大小以适应模型原生分辨率之后的图像（请参阅 Claude 如何调整图像大小并填充图像）。要获得可直接使用的坐标，您可以预先调整图像大小，使坐标与您手中的图像一一对应（请参阅上传前调整图像大小），或者对 Claude 返回的坐标进行重新缩放（请参阅无法预先调整大小时重新缩放坐标）。

Claude 如何调整图像大小并填充图像

Claude 会找出同时满足模型两项图像限制的、保持宽高比的最大尺寸：

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. 直接将返回的坐标用于您发送的图像。如果需要归一化坐标，请除以您发送的图像的尺寸，而不是原始图像的尺寸，也不是填充后的尺寸。

使用 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" 的图像都不会以调整大小后的形式到达模型。

令牌计数端点同样遵循 transformations，会像 Messages API 一样拒绝嵌入的图像，因此您可以在运行推理之前检查嵌入的图像是否无需调整大小即可容纳。计数端点会直接拒绝通过 URL 或文件 ID 提供的图像，而不会获取它们，因此来自这些来源的被标记图像只会在调用 Messages 时进行检查。

无法预先调整大小时重新缩放坐标

如果您无法预先调整大小（例如，图像来自您无法修改的上游系统），请使用上传前调整图像大小中的调整大小辅助函数来还原 Claude 所看到的尺寸，然后将 Claude 返回的坐标映射为归一化坐标或映射回您的原始图像。除非图像选择改为报错，否则 Claude 会对超大图像进行调整大小而不是拒绝，直至达到 API 的请求限制。超出这些限制时，请求会以验证错误失败。请传入与您所调用模型相匹配的层级限制：错误层级的限制会还原出错误的调整后尺寸，并悄然使每个坐标发生偏移。此方法需要知道您上传的图像的像素尺寸，因此不适用于 PDF 上传。

您返回给计算机使用和浏览器使用工具集的屏幕截图和缩放图像是自动调整大小的例外。对于超出模型限制的 tool_result 图像，API 会以验证错误拒绝，而不是对其调整大小。请在返回这些图像之前在您的应用程序中调整其大小，然后将 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 显示器）时，还需除以显示缩放因子。计算机使用工具的缩放指南涵盖了这种模式。

后续步骤