视觉

本指南介绍如何向 Claude 发送图像、适用的限制和费用，以及在哪里可以找到有关基于坐标的工作流的指导。

向 Claude 发送图像

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

• claude.ai。像上传文件一样上传图像，或将图像直接拖放到聊天窗口中。
• Claude Console 中的 Playground。将图像直接添加到任意 User 消息块中。
• API 请求。请参阅以下示例。

在 API 中，以 image 内容块的形式向 Claude 提供图像，可使用以下三种来源类型之一：

1. 嵌入在请求正文中的 base64 编码图像
2. 指向在线托管图像的 URL 引用
3. 由 Files API 返回的 file_id（上传一次，多次引用）

Base64 编码图像示例

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

基于 URL 的图像示例

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Files API 图像示例

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

client = anthropic.Anthropic()

# 上传图像文件
with open("vision-example.jpg", "rb") as f:
    file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))

# 在消息中使用已上传的文件
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

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

多张图像

您可以在单个请求中包含多张图像，Claude 会对它们进行联合分析。这对于比较图像、询问差异或处理一系列内容（例如文档的各个页面）非常有用。发送多张图像时，请为每张图像添加一个简短的文本标签（Image 1:、Image 2: 等）作为引导，以便您在提示和后续轮次中按名称引用它们。

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 1:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Image 2:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image2_data,
                    },
                },
                {"type": "text", "text": "How are these images different?"},
            ],
        }
    ],
)
print(message)

在多轮对话中，以相同方式在后续的 user 轮次中添加新图像。Claude 可以访问之前轮次中的每一张图像，因此诸如"这些与前两张相似吗？"之类的后续问题无需在新轮次的内容中再次包含之前的图像即可正常工作。

图像限制和费用

请求限制

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

• 在 claude.ai 上，每条消息 20 张。
• 在 API 上，对于具有 200k 令牌 "context window"（上下文窗口）的模型，每个请求 100 张。
• 在 API 上，对于所有其他模型，每个请求 600 张。

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

如果单个 API 请求包含超过 20 张图像，则该请求中的每张图像都适用更严格的单图尺寸限制。请求中的所有 image 块都计入此阈值，包括您重新发送的之前对话轮次中的图像，以及嵌套在 tool_result 内容中的图像（例如返回给计算机使用工具的屏幕截图）。在 Amazon Bedrock 和 Google Cloud 上，PDF 等文档块也计入此阈值。超出更严格限制的图像将被拒绝，并返回 invalid_request_error，其消息会提及"many-image requests"并以像素为单位说明当前限制。要在所有平台上保持在限制范围内，请将每张图像调整为任一边均不超过 2000 px，或将请求中的图像和文档块数量控制在 20 个或以下。

每张图像的最大大小为：

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

支持的格式

Claude 支持 JPEG、PNG、GIF 和 WebP 图像（image/jpeg、image/png、image/gif、image/webp）。不支持动画，仅使用第一帧。

分辨率和令牌费用

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

每个模型都有一个最大原生图像分辨率，以长边限制和视觉令牌限制来表示。超过任一限制的图像会在处理前被缩小；有关确切规则，请参阅 Claude 如何调整图像大小和填充图像。例外情况是您返回给计算机使用和浏览器使用工具集的屏幕截图和缩放图像：对于超出模型限制的 tool_result 图像，API 会以验证错误拒绝，而不是将其缩小，因此请在返回这些图像之前在您的应用程序中调整其大小。若要让任何其他超大图像以错误形式被拒绝而不是被缩小，请设置图像块的 transformations 字段。

在所列模型上，高分辨率支持是自动启用的，无需 beta 标头或客户端选择加入。

下表显示了每个层级上几种图像尺寸的缩小后分辨率和视觉令牌费用：

当图像被缩小时，Claude 会在保持其宽高比的同时，将其缩放到符合该层级限制的最大尺寸。这限制了令牌费用的上限。有关精确规则和参考实现，请参阅 Claude 如何调整图像大小和填充图像。

要估算费用，请将令牌数乘以您所使用模型的每令牌价格。例如，按 Claude Haiku 4.5 每百万输入令牌 $1 USD 的价格（标准层级）计算，1000×1000 的图像每千张约花费 $1.30 USD。按 Claude Opus 5 每百万 $5 USD 的价格（高分辨率层级）计算，同一图像每千张约花费 $6.48 USD，而 4K 图像每千张约花费 $23.92 USD。

与在标准层级模型上的同一图像相比，高分辨率图像最多可使用约三倍的视觉令牌。如果您不需要高分辨率为计算机使用、屏幕截图理解和密集文档所提供的额外保真度，请在发送前对图像进行降采样以控制令牌费用。为了最大限度地降低 "latency"（延迟）并简化基于坐标的工作流，建议在上传图像之前调整其大小。

图像质量指南

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

• 图像清晰度： 确保图像清晰，不要过于模糊或像素化。
• 文本： 如果图像包含重要文本，请确保其清晰可读且不会太小。避免仅为了放大文本而裁剪掉关键的视觉上下文。
• 调整大小： 请注意，如果图像过大，可能会被调整大小（请参阅分辨率和令牌费用）；例如，这可能会降低文本的可读性。请考虑预先调整图像大小、裁剪图像，或两者兼而有之。若要让超大图像以错误形式被拒绝而不是被调整大小（这对于坐标工作流很重要），请使用 "oversized_image": "error" 标记图像块。
• 图像压缩： 在发送图像之前使用有损格式（例如 JPEG 或 WebP（有损模式））对其进行压缩，可以通过减小请求大小来降低延迟。但是，这可能会引入对模型性能不利的伪影，尤其是在进行多次压缩时。例如，重度 JPEG 压缩可能会使文本难以阅读。请通过检查实际发送到 API 的图像，确认您的压缩设置适合该任务。

坐标和边界框

有关边界框、点和像素坐标，请参阅坐标和边界框。Claude 返回的是相对于其在调整大小后所看到图像的绝对像素坐标；该指南介绍了 Claude 如何调整图像大小和填充图像，以及如何预先调整大小或重新缩放，使坐标与您的原始图像对齐。

局限性

尽管 Claude 的图像理解能力处于前沿水平，但仍有一些局限性需要注意：

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

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

常见问题

后续步骤