本指南描述了如何在 Claude 中使用图像,包括最佳实践、代码示例和需要记住的限制。


如何使用视觉功能

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

  • claude.ai。像上传文件一样上传图像,或直接将图像拖放到聊天窗口中。
  • Console Workbench。如果您选择接受图像的模型(仅限 Claude 3 和 4 模型),每个用户消息块的右上角会出现添加图像的按钮。
  • API 请求。请参阅本指南中的示例。

上传前须知

基础知识和限制

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

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

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

评估图像大小

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

如果您的输入图像太大需要调整大小,它会增加首个令牌时间的延迟,而不会给您任何额外的模型性能。任何边缘小于 200 像素的非常小的图像可能会降低性能。

为了改善首个令牌时间,我们建议将图像调整为不超过 1.15 兆像素(并且在两个维度上都在 1568 像素内)。

以下是我们的 API 接受的不会被调整大小的常见纵横比的最大图像尺寸表。使用 Claude Sonnet 3.7 模型,这些图像使用大约 1,600 个令牌,每 1K 张图像约 $4.80。

纵横比图像尺寸
1:11092x1092 px
3:4951x1268 px
2:3896x1344 px
9:16819x1456 px
1:2784x1568 px

计算图像成本

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

如果您的图像不需要调整大小,您可以通过此算法估算使用的令牌数:令牌 = (宽度像素 * 高度像素)/750

以下是基于 Claude Sonnet 3.7 每令牌价格每百万输入令牌 $3 的 API 大小约束内不同图像尺寸的大概令牌化和成本示例:

图像尺寸令牌数每张图像成本每 1K 张图像成本
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 提供图像:

  1. 作为 image 内容块中的 base64 编码图像
  2. 作为对在线托管图像的 URL 引用
  3. 使用 Files API(上传一次,多次使用)

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

    # 对于基于 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 调用中使用

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

Base64 编码图像示例

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-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "'"$BASE64_IMAGE_DATA"'"
            }
          },
          {
            "type": "text",
            "text": "描述这张图像。"
          }
        ]
      }
    ]
  }'

基于 URL 的图像示例

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-20250514",
    "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": "描述这张图像。"
          }
        ]
      }
    ]
  }'

Files API 图像示例

对于您将重复使用的图像或当您想避免编码开销时,请使用 Files API

# 首先,将您的图像上传到 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 "file=@image.jpg"

# 然后在您的消息中使用返回的 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-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "file_abc123"
            }
          },
          {
            "type": "text",
            "text": "描述这张图像。"
          }
        ]
      }
    ]
  }'

请参阅 Messages API 示例 了解更多示例代码和参数详细信息。


限制

虽然 Claude 的图像理解能力是前沿的,但有一些需要注意的限制:

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

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


常见问题


深入了解视觉功能

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

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