视觉 - Claude Docs

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

如何使用视觉功能

通过以下方式使用Claude的视觉功能：

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

上传前

基础知识和限制

您可以在单个请求中包含多个图像（claude.ai最多20个，API请求最多100个）。Claude在制定响应时会分析所有提供的图像。这对于比较或对比图像很有帮助。

如果您提交的图像大于8000x8000像素，它将被拒绝。如果您在一个API请求中提交超过20个图像，此限制为2000x2000像素。

虽然API支持每个请求100个图像，但标准端点有32MB请求大小限制。

评估图像大小

为了获得最佳性能，如果图像过大，我们建议在上传前调整其大小。如果您的图像长边超过1568像素，或您的图像超过约1,600个令牌，它将首先被缩小，保持宽高比，直到在大小限制内。

如果您的输入图像过大需要调整大小，这将增加首个令牌的延迟时间，而不会为您提供任何额外的模型性能。任何边小于200像素的非常小的图像可能会降低性能。

为了改进首个令牌的延迟时间，我们建议将图像调整为不超过1.15百万像素（且在两个维度上都在1568像素内）。

以下是我们的API接受的最大图像大小表，这些图像不会因常见宽高比而被调整大小。使用Claude Sonnet 4.5，这些图像使用约1,600个令牌，每1000个图像约4.80美元。

宽高比	图像大小
1:1	1092x1092 px
3:4	951x1268 px
2:3	896x1344 px
9:16	819x1456 px
1:2	784x1568 px

计算图像成本

您在请求Claude时包含的每个图像都计入您的令牌使用量。要计算大约成本，请将大约的图像令牌数乘以您使用的模型的每令牌价格。

如果您的图像不需要调整大小，您可以通过此算法估计使用的令牌数：tokens = (width px * height px)/750

以下是基于Claude Sonnet 4.5每百万输入令牌3美元的价格，在我们的API大小限制内不同图像大小的大约令牌化和成本示例：

图像大小	令牌数	每个图像成本	每1000个图像成本
200x200 px(0.04百万像素)	~54	~$0.00016	~$0.16
1000x1000 px(1百万像素)	~1334	~$0.004	~$4.00
1092x1092 px(1.19百万像素)	~1590	~$0.0048	~$4.80

确保图像质量

向Claude提供图像时，请记住以下几点以获得最佳结果：

图像格式：使用支持的图像格式：JPEG、PNG、GIF或WebP。
图像清晰度：确保图像清晰，不会太模糊或像素化。
文本：如果图像包含重要文本，请确保其清晰且不会太小。避免仅为了放大文本而裁剪掉关键的视觉背景。

提示示例

许多对Claude的文本交互有效的提示技术也可以应用于基于图像的提示。

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

就像文档查询放置一样，Claude在图像出现在文本之前时效果最好。图像放在文本之后或与文本交错仍然会表现良好，但如果您的用例允许，我们建议采用先图像后文本的结构。

关于提示示例

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

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

base64示例提示使用这些变量：

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

Base64编码的图像示例

基于URL的图像示例

Files API图像示例

对于您将重复使用的图像或想要避免编码开销的情况，请使用Files API：

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

限制

虽然Claude的图像理解能力是最先进的，但需要注意一些限制：

人员识别：Claude不能用于识别（即命名）图像中的人员，并将拒绝这样做。
准确性：Claude在解释低质量、旋转或非常小的图像（小于200像素）时可能会产生幻觉或犯错误。
空间推理：Claude的空间推理能力有限。它可能在需要精确定位或布局的任务中遇到困难，例如读取模拟时钟面或描述国际象棋棋子的确切位置。
计数：Claude可以给出图像中对象的大约数量，但可能不总是精确准确，特别是对于大量小对象。
AI生成的图像：Claude不知道图像是否是AI生成的，如果被问到可能会不正确。不要依赖它来检测虚假或合成图像。
不当内容：Claude不会处理违反我们可接受使用政策的不当或露骨图像。
医疗保健应用：虽然Claude可以分析一般医学图像，但它不是为解释复杂的诊断扫描（如CT或MRI）而设计的。Claude的输出不应被视为专业医疗建议或诊断的替代品。

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

常见问题

深入了解视觉功能

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

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

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

    # 对于基于URL的图像，您可以直接在JSON请求中使用URL
    
    # 对于base64编码的图像，您需要首先对图像进行编码
    # 在bash中将图像编码为base64的示例：
    BASE64_IMAGE_DATA=$(curl -s "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" | base64)
    
    # 编码的数据现在可以在您的API调用中使用

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "'"$BASE64_IMAGE_DATA"'"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

# 首先，将您的图像上传到Files API
curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "[email protected]"

# 然后在您的消息中使用返回的file_id
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "file_abc123"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

如何使用视觉功能

上传前

基础知识和限制

评估图像大小

计算图像成本

确保图像质量

提示示例

关于提示示例

Base64编码的图像示例

基于URL的图像示例

Files API图像示例

示例：一个图像

限制

常见问题

Claude 支持哪些图像文件类型？

Claude 能读取图像 URL 吗？

深入了解视觉功能

示例：多个图像

示例：多个图像和系统提示

示例：两个对话轮次中的四个图像

我上传的图像文件大小有限制吗？

一个请求中我可以包含多少张图像？

Claude 会读取图像元数据吗？

我可以删除上传的图像吗？

我在哪里可以找到有关图像上传数据隐私的详细信息？

如果 Claude 的图像解释似乎有误怎么办？

Claude 可以生成或编辑图像吗？