Claude API 怎么分析本地图片？Python 编码、发送与逐项核对结果

把本地图片交给 Claude API，需要读取真实图像字节，按其格式填写 media_type，编码成 Base64 后放进 user 消息的 image 内容块。图片路径字符串本身不会把文件上传到模型。得到分析结果后，还要回到原图逐项核对，尤其是表格数值和细小文字。

本文面向 Python 开发者，演示直连 Anthropic Messages API 的单张图片输入。示例任务是读取自己制作的演示订单截图，未进行付费 API 实测，也不提供识别准确率承诺。接口和限制于 2026 年 10 月 1 日核对。

准备一张可以人工核对的图片

先制作一张简单图片，在空白底上清楚写出三行：ORDER DEMO-1001、STATUS SHIPPED、DATE 2026-09-30。这是虚构演示内容。用自己熟悉的绘图工具保存为 sample.png，文字不要太小，文件不要含真实客户信息。

这三行给出了明确的核对目标，比“描述这张图”更容易发现误读。跑通后，再换成自己有权处理的界面截图、产品照片或统计图，并按任务设计核对字段。

1. 准备 Python 3.10 或更新版本，安装依赖：python -m pip install requests pillow。
2. 配置 ANTHROPIC_API_KEY 和准确的 ANTHROPIC_MODEL。所选模型必须支持图像输入，可在官方模型说明核对。
3. 将 sample.png 与下面的 analyze_image.py 放在同一目录，运行 python analyze_image.py。

示例会真实发送图片和提示词，生成调用按账户计费。不要把密钥写在图片里或直接嵌进前端页面。

Python 示例：识别格式，编码并发送

import base64
import json
import os
from pathlib import Path
from PIL import Image
import requests

path = Path("sample.png")
media_types = {"JPEG": "image/jpeg", "PNG": "image/png",
               "WEBP": "image/webp", "GIF": "image/gif"}
with Image.open(path) as image:
    media_type = media_types.get(image.format)
    width, height = image.size
    frames = getattr(image, "n_frames", 1)
    image.verify()
if media_type is None:
    raise ValueError("本例只接受 JPEG、PNG、WebP、GIF")
if frames != 1:
    raise ValueError("先把动画转换成需要分析的单张静态图")
if width > 8000 or height > 8000:
    raise ValueError("图像尺寸超出单张限制，请先缩小并检查文字")
raw = path.read_bytes()
encoded = base64.b64encode(raw).decode("ascii")
# 这是本例的保守阈值，避免示例从大图开始；不是官方单图上限。
if len(encoded) > 4_000_000:
    raise ValueError("本例先用 Base64 小于 4 MB 的图片")

payload = {
    "model": os.environ["ANTHROPIC_MODEL"],
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": [
        {"type": "image", "source": {
            "type": "base64", "media_type": media_type, "data": encoded}},
        {"type": "text", "text":
            "请从图片逐项读取 ORDER、STATUS、DATE。"
            "每项用一行输出：字段 | 看到的原文 | 所在位置 | 不确定之处。"
            "没有看清时写未看清，不要补全；保留原始日期和拼写。"},
    ]}],
}
body = json.dumps(payload, ensure_ascii=False,
                  separators=(",", ":")).encode("utf-8")
print("image", width, height, "media_type", media_type,
      "request_body_bytes", len(body))
response = requests.post(
    "https://api.anthropic.com/v1/messages",
    headers={"x-api-key": os.environ["ANTHROPIC_API_KEY"],
             "anthropic-version": "2023-06-01",
             "content-type": "application/json"},
    data=body, timeout=(10, 60),
)
response.raise_for_status()
message = response.json()
print("stop_reason", message.get("stop_reason"))
print("\n".join(b["text"] for b in message["content"] if b["type"] == "text"))

代码从解码得到的真实格式选择 MIME 类型，不依赖文件名后缀。发送结构与先图像、后文字的组织方式依据官方视觉文档。返回内容可能还包含其他类型的块，示例只提取 text 来展示结果。

结果怎么逐项核对

输出文字不要求与示例逐字相同，但三个字段的原始值必须对得上。如果停止原因是 max_tokens，可能只得到一部分结果；调整输出预算并检查完整性后，再用于后续流程。没有看清的字段不能靠“听起来合理”通过。

生产任务可保存文件标识、核对字段、识别原文、人工修正和差异原因。在表格上尤其检查行列对应、负号、小数点、百分比与单位。模型说“不确定”有价值；不要为了让数据表看起来齐全，把它自动补成零或默认值。

常见失败与修复

图片格式报错

先用图像工具打开文件，检查是否损坏或只是被改了后缀。支持的格式是 JPEG、PNG、GIF 和 WebP；动画不作为完整动画分析，官方文档说明只使用第一帧，本例因此要求先转成静态图。SVG、PDF 或视频不能假装成 PNG 的 Base64 数据发送。

文字读不清

扩大需要识别的区域，并保留列标题和单位；若图片被多次有损压缩，尽量回到原始截图。裁剪应帮助看清，同时保留判断需要的上下文。反复发同一张模糊图通常不能补回已经丢失的细节。

请求体过大

Base64 会增加字节占用。本例只使用较小的单张图片；真实多图任务还需检查整个 JSON 请求大小。直连 Messages API 的 32 MB 请求上限见官方错误文档。单张图像与多图的像素、大小限制另按视觉文档核对，不能只看图片数量。

适用边界与相关问答

视觉文档说明，小图、旋转图或低质量图可能出现误读；对象计数和空间位置也可能不准确。因此本教程适合辅助提取可核对的信息，不作为精密测量或未经复核的业务决策依据。识别结果不能证明某张图片是否由 AI 生成，也不能替代专业医疗影像诊断。

本地路径能直接填进 URL source 吗？

不能把 C:\images\sample.png 当作公网 URL。本文使用 Base64 随请求上传；URL 来源要符合官方接口支持的在线地址要求。不要为一次测试随意公开敏感图片。

能返回结构化 JSON 供系统自动录入吗？

可以另设计输出格式和解析校验，但“请返回 JSON”的普通提示不等于格式与内容都保证正确。先验证必填字段、类型、枚举和值域，并保留图像与人工核对环节；本例先用逐行文本观察误读，再考虑自动录入。