这次会话从一个简单的问题开始——我的 Claude token 额度还够用吗？——最终演变成一次对 Claude 计费方式的全面梳理，顺手还修了一个 Python 脚本的结构问题。
这个项目是一个家族历史研究工具：一个 Python 脚本，把扫描好的中文 PDF 文件逐页转换为 Markdown，调用的是 Claude 的视觉 API。每一页先渲染成 PNG 图片，经过 base64 编码后，连同中文 OCR 提示词一起发送给 Claude，响应结果以结构化 Markdown 的形式逐页返回。
我们逐一审查了核心 API 调用 client.messages.create 中的每个参数：model、max_tokens、cache_control，以及同时携带图片和指令文本的多模态 messages 数组。
脚本原本在 API 调用的顶层设置了 cache_control={"type": "ephemeral"}——这是一个自动缓存的快捷方式，会锁定请求中最后一个可缓存的内容块。问题在于：图片排在内容数组的最后。由于每一页图片的字节数据都不同，它的内容直接成了缓存键的一部分，导致每一页都命中不了缓存。
修复方案分两步：
"cache_control": {"type": "ephemeral"}这样一来，缓存键只覆盖固定不变的文本提示词，而每页变化的图片位于缓存断点之后，不再影响缓存命中。
有一点需要坦诚说明：claude-sonnet-4-6 要求缓存断点之前至少有 2048 个 token，才会真正写入缓存。目前这段提示词大约只有 150 个 token，实际上不会触发缓存。但这次修复在结构上是正确的，等提示词内容扩充之后自然会生效。
从 token 额度这个问题出发，我们整理出了一张更清晰的 Claude 计费地图。Claude 有三套独立的计费体系，彼此之间互不共享额度：
Anthropic API 计费 — 按 token、按调用量收费。Python 脚本里每一次 client.messages.create() 都走这条通道，与任何订阅计划完全无关，费用计入你的 API 账户。
Claude Pro 订阅 — 每月 20 美元固定月费。覆盖 claude.ai 网页版聊天，以及用 claude.ai 账号登录时在 VS Code 中使用 Claude Code。有每月消息条数上限，并非无限制使用。
VS Code 中的 Claude Code — 这是最容易被忽视的一套。根据配置方式的不同，它要么消耗你的 Pro 订阅额度，要么按 token 计费到与 Python 脚本相同的 API 账户。编辑器自动带入提示词的每一段代码片段，都会计入你所在的那个计费桶。
我们通过发送一条测试消息，确认 VS Code 插件已正常登录并正常工作。那个上下文标签 </> pdf_to_markdown.py#40-... 表明编辑器已自动把选中的代码作为上下文带入了请求。
由 Claude Code 协助编辑与润色。