Claude学院

Claude API 图片输入怎么传？多模态调用教程

给 Claude 传图片，本质就是在 Messages API 请求的 messages[].content 里放一个 type: "image" 的内容块，图片来源用 base64 编码或公网 URL 二选一，再配一段 type: "text" 的提问即可。Claude Opus 4.8、Sonnet 4.6、Haiku 4.5 都原生支持图片输入（Vision），不需要额外的 beta 头或单独的接口。下面给出 Python 和 Node.js 的可运行代码，并讲清 media_type、多图、分辨率上限这些容易踩坑的细节。

请求结构：content 是一个块数组

纯文本调用时 content 可以是一个字符串；要传图片，就必须把 content 写成一个数组，每个元素是一个内容块。图片块的关键字段是 source，它有两种类型：

  • base64：把图片读成字节、做 base64 编码后内联进请求，需要同时指定 media_type（如 image/jpeg）。适合本地文件、不想暴露公网地址的场景。
  • url：直接给一个 Claude 服务端可访问的公网图片地址，由 Anthropic 侧抓取，请求体更小。

支持的格式为 JPEG、PNG、GIF、WebP，media_type 必须和真实格式一致，写错会直接 400。如果你还不熟悉 Messages API 的基础结构，建议先看 Claude API 怎么调用？从注册到第一次请求完整教程 与 Claude Messages API 全部参数说明（含代码示例）。

Python：base64 传本地图片

用官方 anthropic SDK。先 pip install anthropic，并把密钥放进环境变量 ANTHROPIC_API_KEY（SDK 会自动读取）。

import base64
from anthropic import Anthropic

client = Anthropic()

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

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": img_b64,
                    },
                },
                {
                    "type": "text",
                    "text": "这张图表里第二季度的营收是多少？用一句话回答。",
                },
            ],
        }
    ],
)

print(message.content[0].text)

注意内容块的顺序：实测把图片放在文字提问之前，模型对图的理解更稳定。鉴权由 SDK 自动加上 x-api-key 和 anthropic-version 两个头，你无需手写。

Python：用 URL 来源

如果图片已经有公网地址，用 url 类型更省事，请求体也小很多：

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/photo.jpg",
                    },
                },
                {"type": "text", "text": "描述这张照片的主要内容。"},
            ],
        }
    ],
)
print(message.content[0].text)

用 URL 时不需要写 media_type，由服务端根据响应自动判断；但要保证该地址对公网开放、不需要登录鉴权，否则会抓取失败。

Node.js 示例

Node 用 @anthropic-ai/sdk，安装 npm install @anthropic-ai/sdk。下面演示 base64 来源：

import Anthropic from "@anthropic-ai/sdk";
import { readFileSync } from "node:fs";

const client = new Anthropic();
const imgB64 = readFileSync("./chart.png").toString("base64");

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: imgB64,
          },
        },
        { type: "text", text: "把图里的表格转成 Markdown。" },
      ],
    },
  ],
});

console.log(message.content[0].text);

更多 Node 调用细节（含流式输出）可参考 Claude API Node.js 调用示例：从安装到流式输出。Python 端的环境配置见 Anthropic Python SDK 安装与配置完整教程。

多张图片与图文混排

一条 user 消息里可以放多个 image 块，常用于"对比两张图""按顺序分析多页截图"。建议给每张图前加一句文字标号，模型回答时引用更清晰：

content = [
    {"type": "text", "text": "图 1："},
    {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": img1}},
    {"type": "text", "text": "图 2："},
    {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": img2}},
    {"type": "text", "text": "对比这两张设计稿，列出 3 处差异。"},
]

分辨率、大小与 Token 成本

图片不是按文件大小、而是按像素折算成 Token 计费的。几个要点：

  • 过大的图会被服务端缩放后再处理，超高分辨率不会带来等比例的识别提升，反而多花 Token；
  • 对文字密集的截图、扫描件，清晰但适度的分辨率比超大原图更划算；
  • 多图、高分辨率组合会显著推高输入 Token，批量任务前最好先估算。

具体配额、单价以 Anthropic 官网为准。想精确估算可看 Claude API Token 怎么计算？附在线估算方法，控制成本的方法见 Claude API 怎么省钱？5 个降低 Token 成本的方法。

典型场景

  • OCR / 文档提取：传截图或拍照，让模型输出结构化文本或 JSON；如果要约束输出格式，配合提示词技巧效果更好。
  • 图表读数：把折线/柱状图丢进去，提问具体数值或趋势。
  • UI/设计稿审查：上传界面截图，让模型挑布局或可用性问题。
  • 注意 PDF 不是图片：PDF 要用 type: "document" 的文档块，而非 image 块，两者参数不同。

想让图片任务回答更准、少跑偏，可结合 Claude 提示词怎么避免幻觉？实测有效的 5 个方法 里的写法，明确要求"只根据图中可见信息回答"。

常见问题

传图报错 400 invalid_request_error 怎么办？

多数是 media_type 和真实格式不符（比如 PNG 文件写成了 image/jpeg），或 base64 字符串带了 data:image/png;base64, 这种前缀——data 字段只放纯 base64，不要带 data URI 前缀。另外检查 content 是否写成了数组而不是字符串。

图片输入和工具调用、流式输出能一起用吗？

可以。图片块只是 user 消息里的一种内容，和 Tool Use、SSE 流式输出互不冲突，同一请求可以既带图、又声明工具、又开流式。工具调用见 Claude Tool Use 工具调用怎么用？完整代码实战。

哪个模型处理图片最划算？

对识别精度要求高的复杂图表、密集文档，用 Opus 4.8；日常图文问答用 Sonnet 4.6 速度与成本更均衡；量大且任务简单时可用 Haiku 4.5。三者都支持 Vision，选型思路见 Claude 模型怎么选？Opus / Sonnet / Haiku 选型指南。

← Claude API 开发