视觉

本指南介绍如何在 Claude 中使用图像，包括最佳实践、代码示例以及需要注意的限制。



如何使用视觉功能

您可以通过以下方式使用 Claude 的视觉能力：

• claude.ai。像上传文件一样上传图像，或直接将图像拖放到聊天窗口中。
• Console Workbench。每个 User 消息块的右上角都会出现一个添加图像的按钮。
• API 请求。请参阅本指南中的示例。

单个请求中可以包含多张图像，Claude 在生成响应时会对这些图像进行联合分析。这对于比较或对比图像非常有用。



上传前须知



一般限制

每条消息或每个请求的最大图像数量为：

• 在 claude.ai 上每条消息 20 张。
• 对于具有 20 万令牌上下文窗口的模型，通过 API 每个请求 100 张。
• 对于所有其他模型，通过 API 每个请求 600 张。

每张图像的最大尺寸为 8000x8000 像素。

如果单个 API 请求包含超过 20 张图像，则会应用更严格的单张图像尺寸限制。在 Amazon Bedrock 和 Vertex AI 上，PDF 等文档块也会计入此阈值。超过该更严格限制的图像将被拒绝，并返回 invalid_request_error 错误，其消息中会提及 "many-image requests" 并说明当前的像素限制。要在所有平台上保持在限制范围内，请将每张图像调整为任一维度均不超过 2000 像素，或将请求中的图像和文档块总数控制在 20 个或更少。

每张图像的最大大小为：

• 直接使用 Claude API 时为 10 MB（base64 编码）。
• 在 Amazon Bedrock 和 Vertex AI 上为 5 MB（base64 编码）。
• 在 claude.ai 上为 10 MB。



评估图像大小

Claude 以图块（patch）而非像素的方式查看图像。每个图块是图像中一个 28×28 像素的区块，称为一个视觉令牌（visual token）。因此，一张图像的成本为 ⌈width / 28⌉ × ⌈height / 28⌉ 个视觉令牌。

如果 Claude 接收到过大的图像，会对其进行缩放。最大原生图像分辨率为：

• 对于 Claude Fable 5 和 Claude Mythos 5：4784 个令牌，长边最多 2576 像素。
• 对于 Claude Opus 4.8：4784 个令牌，长边最多 2576 像素。
• 对于 Claude Opus 4.7：4784 个令牌，长边最多 2576 像素。
• 对于其他模型：1568 个令牌，长边最多 1568 像素。

为了最大限度地减少延迟并简化基于坐标的工作流程，建议您在上传图像之前先对其进行缩放。



计算图像成本

您在请求中包含的每张图像都会计入您的令牌使用量。要计算大致成本，请将图像的视觉令牌数量（参见评估图像大小）乘以您所使用模型的每令牌价格。

以下是在 API 尺寸限制范围内不同图像大小的令牌化示例和大致成本，基于 Claude Sonnet 4.6 每百万输入令牌 3 美元的价格：

请注意，最后三张图像超过了原生分辨率，在处理前会被缩小（分别缩小至 1456x819 px、1270x952 px 和 1456x819 px），这限制了它们的令牌成本上限。4K 图像的成本不会高于 1920x1080 图像，因为两者都会缩小到相同的尺寸；额外的分辨率会被丢弃。



高分辨率图像支持

Claude Opus 4.7 是首个支持高分辨率图像的 Claude 模型；Claude Opus 4.8、Claude Fable 5、Claude Mythos 5 及更高版本的模型也支持此功能。最大图像分辨率为长边 2576 像素，高于之前模型的 1568 像素。这为视觉密集型工作负载带来了性能提升，对于计算机使用、屏幕截图理解和文档分析尤为有价值。

Claude Opus 4.7 及更高版本的模型会自动启用高分辨率支持，无需 beta 标头或客户端选择加入。

在 Claude Opus 4.7、Claude Opus 4.8、Claude Fable 5 和 Claude Mythos 5 上，高分辨率图像使用的图像令牌最多可达之前模型的约 3 倍（每张图像 4784 个令牌对比 1568 个令牌）。如果您不需要额外的保真度，请在发送前对图像进行降采样以控制令牌成本。

以下是相同图像大小在 Claude Opus 4.7 和 Claude Opus 4.8 上的令牌化情况，基于其每百万输入令牌 5 美元的价格：

只有最后一张图像超过了更高的限制：4K 图像在处理前会被缩小至 2576x1449 px。高分辨率支持提高了分辨率限制，但并未移除限制；长边超过 2576 像素（或 4784 个视觉令牌）的图像仍会被缩小。



确保图像质量

向 Claude 提供图像时，请注意以下几点以获得最佳效果：

• 图像格式：使用支持的图像格式：JPEG、PNG、GIF 或 WebP。
  不支持动画，只会使用第一帧。
• 图像清晰度：确保图像清晰，不要过于模糊或像素化。
• 文本：如果图像包含重要文本，请确保文本清晰可读且不要太小。避免为了放大文本而裁剪掉关键的视觉上下文。
• 缩放：请注意，如果图像过大，可能会被缩放（见上文）；例如，这可能会使文本变得不易辨认。建议预先缩放图像、裁剪图像，或两者兼用。
• 图像压缩：在发送图像之前使用有损格式（如 JPEG 或 WebP 有损模式）对其进行压缩，可以通过减小请求大小来降低延迟。但是，这可能会引入对模型性能有害的伪影，尤其是在应用多次压缩时。例如，重度 JPEG 压缩可能会使文本难以阅读。请通过检查实际发送到 API 的图像来确认您的压缩设置适合当前任务。



处理坐标和边界框

Claude 可以定位和标注图像中的区域（例如，返回表格、表单字段、图表元素或 UI 组件的边界框）。

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



Claude 如何缩放和填充图像

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

1. 边长限制： 任一边都不超过最大边长（大多数模型为 1568 px，Claude Opus 4.7 及更高版本的模型为 2576 px）。
2. 视觉令牌限制： 图像的令牌成本 ⌈width / 28⌉ × ⌈height / 28⌉ 不超过模型的视觉令牌预算（大多数模型为 1568 个令牌，Claude Opus 4.7 及更高版本的模型为 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 most models. For Claude Opus 4.7 and later 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 Claude Opus 4.7 and
    later 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)

填充仅应用于底部和右侧边缘，因此原点不会移动，按轴进行线性重新缩放即可。



提示示例

许多适用于与 Claude 进行基于文本交互的提示技巧也可以应用于基于图像的提示。

以下示例演示了涉及图像的最佳实践提示结构。



关于提示示例

以下示例演示了如何使用各种编程语言和方法来使用 Claude 的视觉能力。您可以通过三种方式向 Claude 提供图像：

1. 在 image 内容块中作为 base64 编码的图像
2. 作为指向在线托管图像的 URL 引用
3. 使用 Files API（上传一次，多次使用）

base64 示例提示使用以下变量：

以下是如何使用 base64 编码图像和 URL 引用在 Messages API 请求中包含图像的示例：



Base64 编码图像示例



基于 URL 的图像示例



Files API 图像示例

对于您将重复使用的图像，或者当您希望避免编码开销时，请使用 Files API。上传图像一次，然后在后续消息中引用返回的 file_id，而无需重新发送 base64 数据。

有关更多示例代码和参数详情，请参阅 Messages API 示例。



限制

虽然 Claude 的图像理解能力处于前沿水平，但仍有一些限制需要注意：

• 人物识别：Claude 不能用于识别图像中人物的姓名，并会拒绝此类请求。
• 准确性：在解读低质量、旋转或小于 200 像素的极小图像时，Claude 可能会产生幻觉或出错。
• 空间推理：Claude 的坐标和定位输出是近似值。请遵循处理坐标和边界框中的指导，并在依赖输出之前进行验证。
• 计数：Claude 可以给出图像中物体的大致数量，但可能并不总是精确准确，尤其是在有大量小物体的情况下。
• AI 生成的图像：Claude 不知道图像是否由 AI 生成，如果被问及可能会给出错误答案。请勿依赖它来检测虚假或合成图像。
• 不当内容：Claude 不会处理违反可接受使用政策的不当或露骨图像。
• 医疗保健应用：虽然 Claude 可以分析一般医学图像，但它并非设计用于解读复杂的诊断扫描（如 CT 或 MRI）。Claude 的输出不应被视为专业医疗建议或诊断的替代品。

请始终仔细审查和验证 Claude 的图像解读，尤其是在高风险用例中。对于需要完美精度或敏感图像分析的任务，请勿在没有人工监督的情况下使用 Claude。



常见问题



深入了解视觉功能

准备好开始使用 Claude 构建图像应用了吗？以下是一些有用的资源：

• 多模态 cookbook：此 cookbook 包含图像入门技巧和最佳实践技术，以确保图像处理的最高质量性能。了解如何有效地使用图像向 Claude 提示以执行任务，例如解读和分析图表或从表单中提取内容。
• API 参考：Messages API 的文档，包括涉及图像的 API 调用示例。

如果您有任何其他问题，请联系支持团队。您还可以加入开发者社区，与其他创作者交流并获得 Anthropic 专家的帮助。