Claude API 怎么读 PDF：document 块的 url、base64、file_id 写法，600 页和 128 MB 限制，token 怎么估

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

适用于谁

• 想让 Claude 总结合同、论文、财报、说明书，或者从 PDF 里抽取字段的开发者；
• 网页版能拖文件，却不知道 API 里怎么传的人（网页端文件限制见 /guides/claude-file-upload-limits）；
• 想估算一份 PDF 要花多少 token 的人。

结论先说

1. PDF 用 document 内容块传，和 text 块一起放在用户消息的 content 里。
2. 三种来源：url（公开网址）、base64（把文件编码进请求，media_type 写 application/pdf）、file（先传到 Files API，再用 file_id 引用）。
3. 限制：第一方 Claude API 请求总大小 128 MB；每个请求最多 600 页，上下文窗口小于 1M token 的请求最多 100 页；PDF 不能有密码或加密。
4. Claude 同时看文字和图像：每页会转成图像，再配上提取出的文字，所以能读懂图表、示意图。
5. 官方给的估算：每页文字大约 1500 到 3000 token，另加图像的 token；没有额外的 PDF 附加费。

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

一、方式一：url

PDF 已经在公开网址上时，最省事：

python
import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",  # 以官方模型页当天为准
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "url", "url": "https://example.com/report.pdf"},
                },
                {"type": "text", "text": "这份文件的主要结论是什么？"},
            ],
        }
    ],
)
print(message.content[0].text)

网址必须是服务器能访问到的公开地址。

二、方式二：base64

文件在本地时，读取后编码：

python
import base64

with open("report.pdf", "rb") as f:
    pdf_base64 = 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": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                },
                {"type": "text", "text": "请列出文件中所有的日期和金额。"},
            ],
        }
    ],
)

TypeScript 里读文件的写法是 await readFile("report.pdf", { encoding: "base64" })（来自 node:fs/promises），请求结构完全一样。注意 base64 会让请求体变大，要留意前面说的 128 MB 总量。

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

同一份 PDF 要问很多次，或者文件很大时，官方建议用 Files API 先上传，之后只引用编号：

python
uploaded = client.files.upload(
    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
                {"type": "text", "text": "请总结这份文件。"},
            ],
        }
    ],
)

上传、删除、过期等管理方法见 /guides/claude-api-files-api。

四、它到底“看”到了什么

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

官方描述的处理过程有三步：

1. 系统把 PDF 的每一页转成一张图像，同时提取每页的文字；
2. 文字和图像一起交给 Claude，所以图表、示意图、版面也能被理解；
3. Claude 回答时可以引用文字内容，也可以引用视觉内容。

这带来两个直接后果：

• 费用是两部分之和：文字 token（官方估算每页约 1500 到 3000，看内容密度）加上图像 token（按图片规则计算，见 /guides/claude-api-image-input）。官方强调标准 API 价格适用，没有额外的 PDF 费用；
• 文字多、图表多的 PDF 会很快占满上下文窗口，可能还没到页数上限就失败。官方的建议是把大文件拆成几段；每页都按图像处理，所以降低内嵌图片的分辨率也有帮助。

想事先知道一份 PDF 会用多少 token，可以用 token 计数接口，但它对 PDF 只接受 base64 来源，不接受 url 或 file，详见 /guides/claude-api-count-tokens。

五、官方的几条性能建议

• 把 PDF 放在文字提问之前；
• 使用标准字体，文字要清晰可读；
• 页面方向要摆正，扫描件先把页面旋转好；
• 在提示词里用 PDF 阅读器里显示的“逻辑页码”来指页，不要用印在页面上的页码；
• 大文件分块处理；
• 重复分析同一份文件时开启提示词缓存。

六、规模化：缓存与批量

• 提示词缓存：对同一份 PDF 多次提问，可以给 document 块加缓存标记，之后的请求读缓存，节省输入成本和延迟。缓存的完整写法见 /guides/claude-prompt-caching；
• 批量处理：几百份 PDF 要一起处理又不赶时间，可以用 Message Batches，官方文档里有现成的 PDF 批量示例，批量接口的用法见 /guides/claude-api-message-batches。

七、不是 PDF 的文件怎么办

document 块不接受 xlsx、docx 这类二进制格式。官方的建议：

• txt、csv、md 这类纯文本，可以直接读出文字放进 text 块，或用 text/plain 上传到 Files API 后引用；
• docx、xlsx 先转成文字，或者转成 PDF；官方特别提醒，含图片的 docx 先转 PDF，才能用上 PDF 的图像解析和引用功能。

八、一个实用的小流程

把上面的内容串起来，处理一份新 PDF 时可以这样走：

1. 先看文件大小和页数，超过限制就先拆分；
2. 只问一次的小文件用 url 或 base64，要反复提问的大文件先传到 Files API；
3. 请求里把 document 块放在 text 块之前，问题里用逻辑页码指明范围，例如“只看第 3 到 5 页”；
4. 先在少量样本上试，用返回的 usage 字段核对实际 token 用量，再决定要不要批量跑；
5. 同一份文件的后续提问加上缓存标记，省下重复读取的成本。

这些都是把官方各条建议串起来的做法，不是官方规定的固定流程，你可以按自己的文件情况调整。

常见问题

Q：为什么提示请求太大或页数超限？

对照上面的限制：128 MB、600 页（窗口小于 1M token 的请求是 100 页）。拆分文件，或改用 Files API 减小请求体。整体排查见 /guides/claude-api-error-codes。

Q：加密或设了密码的 PDF 能读吗？

官方要求是标准 PDF，不能有密码或加密。

Q：能让回答附上出处吗？

document 块有可选的 citations 字段，启用后可以获得引用，细节官方有专门页面，本文不展开。

Q：费用怎么算？

文字和图像都按输入 token 计，价格以官方价格页当天为准。

参考资料

• Claude 官方：PDF support — https://platform.claude.com/docs/en/build-with-claude/pdf-support
• Claude 官方：Files API — https://platform.claude.com/docs/en/build-with-claude/files
• Claude 官方：Token counting — https://platform.claude.com/docs/en/build-with-claude/token-counting