Anthropic Files API 正式发布：省时间但不省钱

We’re so glad you’re here. You can expect all the best TNS content to arrive Monday through Friday to keep you on top of the news and at the top of your game.

Check your inbox for a confirmation email where you can adjust your preferences and even join additional groups.

Follow TNS on your favorite social media networks.

Become a TNS follower on LinkedIn.

Check out the latest featured and trending stories while you wait for your first TNS newsletter.

Anthropic 于 8 月 19 日将 Files API 和 computer-use 工具集移出了 beta 阶段，并推出了 browser-use 工具集。它允许开发者上传一次文档，随后在后续请求中通过 ID 引用，而不是每次都将文档内容发送过去。目前常见的替代方案是大多数开发者正在做的事情：将参考资料粘贴到每个 prompt 中。

我想衡量一下一次性上传文件与将文档粘贴到每个请求中这两种方式，在 token 消耗、准确性和设置复杂度上的差异。我构建了一个带有可验证答案的测试，用相同的负载运行了这两种方式，还加入了第三种方案——Prompt Caching，它是从测试结果中发现的。

我为一家名为 Ledgerline 的发票公司编写了一份伪造的 API 参考文档，约 1200 词，涵盖了认证、速率限制、幂等性、webhook、批量端点和沙盒环境。场景是一个开发者支持机器人，它仅使用 Ledgerline API 参考来回答问题。然后我写了五个开发者问题，文档可以回答这些问题：

• 如何区分两种不同的 403 错误，以及各自的修复方法
• 超时后如何安全重试支付创建
• 如何验证 webhook 签名并防止重放攻击
• 一夜之间创建 2000 张发票的正确方式
• 将秘密 API token 提交到公共仓库后该怎么办

每个问题在参考文档中都有特定的正确答案，包括一些容易忽略的细节。一个修复方法取决于知道 token scopes 在创建后无法编辑。另一个则需要了解批量端点独立的速率限制。

我用三种方式运行了相同的五个问题，通过 Python 脚本直接调用 API，使用 claude-sonnet-5 和相同的指令：

• 第一组：将完整参考文档粘贴到每个请求中
• 第二组：通过 Files API 上传参考文档一次，并在每个请求中引用其文件 ID
• 第三组：将参考文档粘贴到系统提示词中一次，并启用 Prompt Caching

API 会在每个响应中报告 token 使用量，因此每个组都产生了自己的计数。

在第一次运行之前有两处 break。脚本最初将 temperature 设置为零以确保可复现性，但 API 拒绝了。Temperature 在 claude-sonnet-5 上已弃用。其次，一个响应以 thinking block 开头而不是文本，导致我的打印代码崩溃。这两个修复都是一行代码。

Files API 上传本身很顺利。一次调用，返回一个文件 ID，后续的每个请求都使用了这个 ID。

针对答案来看，所有三组的十五个答案都是正确的。每个组都捕捉到了那些微妙的细节：无法编辑的 token scopes、独立的批量速率限制、常数时间的签名比较、五分钟的重放窗口。无论组之间发生了什么变化，答案质量都没有改变。

无论组之间发生了什么变化，答案质量都没有改变。

虽然答案质量保持一致，但 token 计数却并非如此。

测试	常规输入 token	缓存写入	缓存读取	输出
第一组，每次粘贴	15,246	0	0	1,399
第二组，Files API	15,371	0	0	1,434
第三组，Prompt Caching	2,712	12,990	11,960	1,642

第二组的计费输入略高于第一组，这很有意思。营销材料中没有提到这一点，但我以为使用一个 API 中的文件可能会需要更少的 token。上传文件的内容仍然会在每个请求中被处理，两种方式每个问题约 3050 个输入 token，而在之上引用文件增加了少量开销，每个请求约 25 个 token。在五次请求中，一次上传比粘贴多花费了 125 个输入 token。在任何数量下，这个差距都不会翻转。

第三组的行为才是我原本假设 Files API 应有的。文档在第一次请求时被全额计费，作为 2990 个 token 的缓存写入。之后四次请求从缓存中读取，缓存读取的计费约为正常输入 token 的十分之一。问题本身每个消耗 48 到 63 个常规输入 token。缓存写入比正常输入多 25% 的费用，所以第一次请求是最昂贵的，后续请求才是节省发生的地方。

关于缓存数字的两个注意事项。缓存在五分钟不活动后过期，所以节省假设请求持续稳定地到来。而且缓存需要重构请求，将文档移到系统提示词中并添加缓存标记。

何时使用哪种方案

有趣的结果是这两个功能解决的是不同的问题。Files API 管理文档。Prompt Caching 降低成本。

当问题本身就是文件时使用 Files API。它让你只需上传一份副本并通过 ID 引用，而不是让文档文本存在于你的代码中；它处理你无法粘贴的格式，如 PDF 和图片；存储的文件现在支持过期设置。它不会改变的是成本。文档在每个请求中都会被处理，而 Anthropic 的公告从未声称并非如此。

当问题是每个请求都在为同一份文档付费时使用 Prompt Caching。在这个工作负载中，它将计费的输入削减到五次请求中约为粘贴的三分之一，而且差距会持续扩大，因为之后的每个请求都以大约正常 rate 的十分之一来读取文档。权衡是五分钟的缓存过期，这假设需要稳定的流量，以及重构你的请求以添加缓存标记。

当两个问题同时存在时，可以将 Files API 和 Prompt Caching 结合使用。Files API 文档可以像粘贴的文本一样添加缓存标记。我分别测试了它们，以隔离各自独立的作用。

在某些情况下粘贴仍然胜出。在原型设计和一次性调用时使用粘贴，此时先上传只是一个额外的步骤。当文档每次请求都会变化时，这也是最好的选择，因为没有任何东西被重用，所以这两个功能都帮不上忙。请记住，这是短参考文本，因为大多数模型的文档如果少于 1024 个 token 就无法缓存。粘贴的移动部件也最少：没有上传步骤、没有文件 ID、没有要管理的存储副本。

我做这个测试时，原本期望找出 Files API 是否在准确性或成本上击败粘贴。结果证明我问错了问题。它们在成本上打平，而那个在成本上胜出的功能是我在最后一刻才加入测试的，试图强制出一个不同的结果。