本指南描述了如何在 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-5",
    "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-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": "描述这张图像。"
          }
        ]
      }
    ]
  }'

​
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 "[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": "描述这张图像。"
          }
        ]
      }
    ]
  }'
请参阅 Messages API 示例 了解更多示例代码和参数详细信息。
最好将图像放在提示中关于它们的问题或使用它们的任务指令之前。要求 Claude 描述一张图像。
角色内容
用户[图像] 描述这张图像。
以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。
Python
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {
                    "type": "text",
                    "text": "描述这张图像。"
                }
            ],
        }
    ],
)
在有多张图像的情况下，用 图像 1: 和 图像 2: 等介绍每张图像。您不需要在图像之间或图像与提示之间换行。要求 Claude 描述多张图像之间的差异。
角色内容
用户图像 1: [图像 1] 图像 2: [图像 2] 这些图像有什么不同？
以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。
Python
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "图像 1:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {
                    "type": "text",
                    "text": "图像 2:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image2_media_type,
                        "data": image2_data,
                    },
                },
                {
                    "type": "text",
                    "text": "这些图像有什么不同？"
                }
            ],
        }
    ],
)
要求 Claude 描述多张图像之间的差异，同时给它一个关于如何响应的系统提示。
内容
系统只用西班牙语回应。
用户图像 1: [图像 1] 图像 2: [图像 2] 这些图像有什么不同？
以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。
Python
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="只用西班牙语回应。",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "图像 1:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {
                    "type": "text",
                    "text": "图像 2:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image2_media_type,
                        "data": image2_data,
                    },
                },
                {
                    "type": "text",
                    "text": "这些图像有什么不同？"
                }
            ],
        }
    ],
)
Claude 的视觉功能在混合图像和文本的多模态对话中表现出色。您可以与 Claude 进行扩展的来回交流，在任何时候添加新图像或后续问题。这为迭代图像分析、比较或将视觉与其他知识结合提供了强大的工作流程。要求 Claude 对比两张图像，然后提出一个后续问题，将第一批图像与两张新图像进行比较。
角色内容
用户图像 1: [图像 1] 图像 2: [图像 2] 这些图像有什么不同？
助手[Claude 的回应]
用户图像 1: [图像 3] 图像 2: [图像 4] 这些图像与前两张相似吗？
助手[Claude 的回应]
使用 API 时，只需将新图像作为标准多轮对话结构的一部分插入到 user 角色的 Messages 数组中。

​
限制

虽然 Claude 的图像理解功能是前沿的，但有一些需要注意的限制：
  • 人员识别：Claude 不能用于识别（即命名）图像中的人员，并且会拒绝这样做。
  • 准确性：Claude 在解释低质量、旋转或小于 200 像素的非常小图像时可能会产生幻觉或犯错误。
  • 空间推理：Claude 的空间推理能力有限。它可能在需要精确定位或布局的任务上有困难，比如读取模拟时钟表面或描述棋子的确切位置。
  • 计数：Claude 可以给出图像中物体的大概数量，但可能不总是精确准确，特别是对于大量小物体。
  • AI 生成的图像：Claude 不知道图像是否是 AI 生成的，如果被询问可能会不正确。不要依赖它来检测虚假或合成图像。
  • 不当内容：Claude 不会处理违反我们可接受使用政策的不当或明确图像。
  • 医疗保健应用：虽然 Claude 可以分析一般医学图像，但它不是为解释复杂的诊断扫描（如 CT 或 MRI）而设计的。Claude 的输出不应被视为专业医疗建议或诊断的替代品。
始终仔细审查和验证 Claude 的图像解释，特别是对于高风险用例。不要在没有人工监督的情况下将 Claude 用于需要完美精度或敏感图像分析的任务。

​
常见问题

Claude 目前支持 JPEG、PNG、GIF 和 WebP 图像格式，具体为：
  • image/jpeg
  • image/png
  • image/gif
  • image/webp
是的，Claude 现在可以通过我们 API 中的 URL 图像源块处理来自 URL 的图像。 只需在您的 API 请求中使用 “url” 源类型而不是 “base64”。 示例：
{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
  }
}
是的，有限制：
  • API：每张图像最大 5MB
  • claude.ai：每张图像最大 10MB
超过这些限制的图像将被拒绝，并在使用我们的 API 时返回错误。
图像限制为：
  • Messages API：每个请求最多 100 张图像
  • claude.ai：每轮最多 20 张图像
超过这些限制的请求将被拒绝并返回错误。
不会，Claude 不会解析或接收传递给它的图像的任何元数据。
不可以。图像上传是临时的，不会存储超过 API 请求的持续时间。上传的图像在处理后会自动删除。
请参阅我们的隐私政策页面，了解我们如何处理上传的图像和其他数据的信息。我们不使用上传的图像来训练我们的模型。
如果 Claude 的图像解释似乎不正确：
  1. 确保图像清晰、高质量且方向正确。
  2. 尝试提示工程技术来改善结果。
  3. 如果问题持续存在，请在 claude.ai 中标记输出（点赞/点踩）或联系我们的支持团队。
您的反馈帮助我们改进！
不能，Claude 只是一个图像理解模型。它可以解释和分析图像，但不能生成、制作、编辑、操作或创建图像。

​
深入了解视觉功能

准备开始使用 Claude 构建图像应用了吗？以下是一些有用的资源： 如果您有任何其他问题，请随时联系我们的支持团队。您也可以加入我们的开发者社区，与其他创作者联系并从 Anthropic 专家那里获得帮助。