Claude API 图片输入（vision）怎么传：base64、url、file_id 三种写法，数量、大小和 token 怎么算

本文根据 Claude 官方《Vision》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 Anthropic 官方网站。API 是按用量计费的独立服务，与 Claude 订阅分开计算，Key 的获取见 /guides/claude-api-key-console。

适用于谁

• 想让 Claude 识别截图、票据、图表、照片的开发者；
• 在网页或应用里的 Claude 能看图，却不知道 API 里怎么传的人；
• 图片多、请求慢或报错，想弄清上限和 token 的人。

在 claude.ai 里直接上传图片的说明，不属于本文范围，网页端文件限制见 /guides/claude-file-upload-limits。

结论先说

1. 图片放进 image 内容块，和 text 块一起放在用户消息的 content 数组里。
2. 三种来源：base64（把图片编码进请求）、url（给一个公开图片网址）、file（用 Files API 先上传，再引用 file_id）。
3. 支持 JPEG、PNG、GIF、WebP。 GIF 动图只用第一帧。
4. 数量：每个请求最多 100 张（上下文窗口为 200k token 的模型）或 600 张（其他模型）；单张在 Claude API 上最大 10 MB（base64 编码后）。
5. 图片放在文字前面，官方说这样效果更好。

图：本站根据 Claude 官方《Vision》 整理的示意图

一、方式一：base64

把图片读成字节、编码成 base64 字符串，放进请求。Python：

python
import base64
import anthropic

client = anthropic.Anthropic()

with open("chart.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-5-5",  # 以官方模型页当天为准
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "请描述这张图里的主要信息。"},
            ],
        }
    ],
)
print(message.content[0].text)

media_type 要和图片真实格式一致：PNG 写 image/png，JPEG 写 image/jpeg。TypeScript 里把文件读成 base64 的写法是 fs.readFileSync("chart.png").toString("base64")，其余结构完全相同。

二、方式二：url

图片已经在公开网址上，就不必自己编码：

python
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "url", "url": "https://example.com/chart.png"},
                },
                {"type": "text", "text": "这张图表说明了什么？"},
            ],
        }
    ],
)

官方提示：如果你用的是 Amazon Bedrock 或 Google 托管的 Claude 模型，这些平台只支持 base64 来源。所以代码要换平台时，不要默认 url 一定能用。网址必须是服务器能访问到的公开地址。

三、方式三：先上传，再引用 file_id

多轮对话里，每一轮请求都会把完整历史重发一遍。如果图片是 base64，图片字节就会在每一轮重复发送，请求会越来越大、越来越慢。官方的建议是用 Files API 上传一次，之后只引用 file_id：

python
{"type": "image", "source": {"type": "file", "file_id": "file_xxx"}}

上传、管理、限制等细节见 /guides/claude-api-files-api。

四、多张图、顺序和提示词

一个 content 数组里可以放多个 image 块。本站的建议是在每张图前面用文字标一下，例如“图 1：”，再放图片，最后写问题，这样模型更容易分清哪句话指哪张图。这只是一种写法习惯，官方没有强制要求。

提醒两点：

• 官方建议“先图后文”，但先文后图也能正常工作；
• Claude 不会读取图片的元数据（比如拍摄时间、位置），只看画面内容。

五、数量和大小限制

两点补充：

• 超过 20 张图时有更严格的单图尺寸限制。 它按请求里所有 image 块算，包括你重发的历史轮次里的图。被拒绝时错误信息会提到 “many-image requests”。官方给的避免办法是每边缩到 3000 像素以内，或把图片与文档块控制在 20 个以内；
• 图多时请求总大小常比张数先到上限，这时用 Files API 引用 file_id 可以让请求体变小。

六、token 怎么估算

图：本站根据 Claude 官方《Vision》 整理的示意图

官方的算法：图片按 28 乘 28 像素的补丁处理，每个补丁算一个视觉 token，所以一张图约等于

向上取整（宽 ÷ 28）× 向上取整（高 ÷ 28）个 token。

每个模型有“长边上限”和“视觉 token 上限”，超过任一个，图片会先按比例缩小。官方分了两档：

官方表格里的例子：1000 乘 1000 像素的图，两档都是 1296 个 token，不会缩小；1920 乘 1080 的图，标准档缩到 1456 乘 819，约 1560 个 token，高分辨率档不缩小，约 2691 个 token。官方还提醒：高分辨率档同一张图可能比标准档多用约三倍视觉 token，不需要那么高保真时，先自己缩小再发，能省 token、降延迟。

真实费用请用官方的 token 计数接口先量一下，见 /guides/claude-api-count-tokens，价格以官方价格页当天为准。

七、官方列出的局限

• 低质量、旋转过、小于 200 像素的图，容易出错甚至“幻觉”；
• 位置和坐标是近似值，使用前要自己核对；
• 数物体的个数只能给近似值，物体多又小时容易不准；
• 不能判断一张图是不是 AI 生成的，别依赖它做这件事；
• 复杂的医学影像（如 CT、MRI）不是它的设计用途，输出不能替代专业诊断。

压缩图片会减小请求，但 JPEG 压缩过重会让文字难以辨认，官方建议检查实际发出的图片。

常见问题

Q：图片能和 PDF 一起发吗？

可以。PDF 用 document 块，写法见 /guides/claude-api-pdf-support。

Q：同一张图反复问，能省钱吗？

可以配合提示词缓存，见 /guides/claude-prompt-caching。

Q：报错 400 或 413？

图片过大、格式不对、数量超限都可能触发，整体排查见 /guides/claude-api-error-codes。

参考资料

• Claude 官方：Vision — https://platform.claude.com/docs/en/build-with-claude/vision