本指南描述了如何在 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 专家的帮助。