视觉 - Claude Docs

本指南介绍如何在 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:1	1092x1092 px
3:4	951x1268 px
2:3	896x1344 px
9:16	819x1456 px
1:2	784x1568 px

计算图像成本

您在请求中包含的每个图像都计入您的令牌使用量。要计算近似成本，请将近似图像令牌数乘以您使用的模型的每令牌价格。如果您的图像不需要调整大小，您可以通过此算法估计使用的令牌数：tokens = (width px * height px)/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 提供图像：

作为 image 内容块中的 base64 编码图像
作为托管在线图像的 URL 引用
使用文件 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 引用在消息 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": "Describe this image."
          }
        ]
      }
    ]
  }'

基于 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": "Describe this image."
          }
        ]
      }
    ]
  }'

文件 API 图像示例

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

# 首先，将您的图像上传到文件 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-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "file_abc123"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

请参阅消息 API 示例了解更多示例代码和参数详情。

示例：一张图像

最好在提示中将图像放在关于它们的问题或使用它们的任务说明之前。要求 Claude 描述一张图像。

角色	内容
用户	[图像] 描述这张图像。

以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。

使用 Base64
使用 URL

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": "Describe this image."
                }
            ],
        }
    ],
)

示例：多张图像

在有多张图像的情况下，使用 Image 1: 和 Image 2: 等标签介绍每张图像。图像之间或图像与提示之间不需要换行。要求 Claude 描述多张图像之间的差异。

角色	内容
用户	图像 1：[图像 1] 图像 2：[图像 2] 这些图像有什么不同？

以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。

使用 Base64
使用 URL

Python

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

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

要求 Claude 描述多张图像之间的差异，同时给它一个系统提示来说明如何响应。

内容
系统	仅用西班牙语回应。
用户	图像 1：[图像 1] 图像 2：[图像 2] 这些图像有什么不同？

以下是使用 Claude Sonnet 3.7 模型的相应 API 调用。

使用 Base64
使用 URL

Python

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="Respond only in Spanish.",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Image 1:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Image 2:"
                },
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image2_media_type,
                        "data": image2_data,
                    },
                },
                {
                    "type": "text",
                    "text": "How are these images different?"
                }
            ],
        }
    ],
)

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

Claude 的视觉功能在混合图像和文本的多模态对话中表现出色。您可以与 Claude 进行扩展的来回交流，在任何时刻添加新图像或后续问题。这为迭代图像分析、比较或将视觉与其他知识相结合的强大工作流程提供了支持。要求 Claude 对比两张图像，然后提出一个后续问题，将第一张图像与两张新图像进行比较。

角色	内容
用户	图像 1：[图像 1] 图像 2：[图像 2] 这些图像有什么不同？
助手	[Claude 的响应]
用户	图像 1：[图像 3] 图像 2：[图像 4] 这些图像与前两张相似吗？
助手	[Claude 的响应]

使用 API 时，只需将新图像插入到标准多轮对话结构中 user 角色的消息数组中。

限制

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

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

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

常见问题

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

Claude 目前支持 JPEG、PNG、GIF 和 WebP 图像格式，具体为：

image/jpeg
image/png
image/gif
image/webp

Claude 可以读取图像 URL 吗？

是的，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 时会返回错误。

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

图像限制为：

消息 API：每个请求最多 100 张图像
claude.ai：每轮最多 20 张图像

超过这些限制的请求将被拒绝并返回错误。

Claude 读取图像元数据吗？

不，Claude 不会解析或接收从传递给它的图像中获取的任何元数据。

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

不可以。图像上传是临时的，不会在 API 请求期间之外存储。上传的图像在处理后会自动删除。

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

请参阅我们的隐私政策页面，了解我们如何处理上传的图像和其他数据的信息。我们不使用上传的图像来训练我们的模型。

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

如果 Claude 的图像解释似乎不正确：

确保图像清晰、高质量且方向正确。
尝试提示工程技术来改进结果。
如果问题仍然存在，在 claude.ai 中标记输出（竖起大拇指/竖起大拇指向下）或联系我们的支持团队。

您的反馈帮助我们改进！

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

不，Claude 仅是图像理解模型。它可以解释和分析图像，但不能生成、生成、编辑、操纵或创建图像。

深入了解视觉

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

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

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

第一步

模型与定价

使用 Claude 构建

功能

工具

代理技能

Agent SDK

API 中的 MCP

Claude 在第三方平台上

提示词工程

测试和评估

加强防护措施

管理和监控

视觉

如何使用视觉功能

上传前

基础知识和限制

评估图像大小

计算图像成本

确保图像质量

提示示例

关于提示示例

Base64 编码图像示例

基于 URL 的图像示例

文件 API 图像示例

限制

常见问题

深入了解视觉

第一步

模型与定价

使用 Claude 构建

功能

工具

代理技能

Agent SDK

API 中的 MCP

Claude 在第三方平台上

提示词工程

测试和评估

加强防护措施

管理和监控

​如何使用视觉功能

​上传前

​基础知识和限制

​评估图像大小

​计算图像成本

​确保图像质量

​提示示例

​关于提示示例

​Base64 编码图像示例

​基于 URL 的图像示例

​文件 API 图像示例

​限制

​常见问题

​深入了解视觉

如何使用视觉功能

上传前

基础知识和限制

评估图像大小

计算图像成本

确保图像质量

提示示例

关于提示示例

Base64 编码图像示例

基于 URL 的图像示例

文件 API 图像示例

限制

常见问题

深入了解视觉