Anthropic Files API 实战 2026：上传一次 vs 每次粘贴，Token 账单谁更便宜？

Anthropic 推出 Files API 后，很多人以为「上传一次文件、按 ID 引用」能省 token——毕竟不用每次把文档塞进请求了。但实测数据给出了相反的结论：上传文件的全部内容依然会在每个请求中被处理，每问题大约 3,050 个输入 token，而且引用文件还要额外加约 25 token 的开销。5 个请求下来，上传一次比每次粘贴反而多花 125 个输入 token。Files API 省的是时间，不是钱。本文用对照实验给出完整数据。

1. 实验设计：一份文档，三种姿势

为了搞清楚上传一次到底省不省钱，我造了一份约 1,200 词的假 API 参考文档（Ledgerline 开票 API），涵盖认证、限流、幂等、webhook、批量端点与沙箱。然后设计了 5 个开发问题，每个问题在文档里都有唯一正确答案——包括容易漏掉的细节：token scope 创建后不能编辑、批量端点有独立的限流。三组跑完全相同的 5 个问题，模型统一用 claude-sonnet-5，指令完全一致。

// The experiment setup: a 1,200-word fake API reference
// (Ledgerline invoicing API) and five developer questions.
// Every question has a specific correct answer in the doc,
// including details that are easy to miss.

const questions = [
  "Can token scopes be edited after creation?",
  "What is the rate limit for the bulk endpoint?",
  "How does the webhook signature comparison work?",
  "What happens to idempotent retries after 5 minutes?",
  "Which sandbox endpoints allow test payments?",
];

// Three arms, identical instructions, claude-sonnet-5:
// Arm 1: paste the doc into every request
// Arm 2: upload the doc once via Files API, reference by ID
// Arm 3: prompt caching on the stable prefix

2. 两个小坑：temperature 被弃用，thinking block 会崩代码

实验还没开跑就踩了两个坑：脚本原本把 temperature 设为 0 保证可复现，结果 API 直接拒绝——temperature 在 claude-sonnet-5 上已弃用。第二个坑是某个响应以 thinking block 开头而不是文本，打印代码直接崩溃。两个都是一行修复，但提醒我们：新 API 的默认行为可能已经变了，别假设旧参数还能用。

3. Files API 上传本身：顺利得无聊

上传过程波澜不惊：一次调用，拿回一个 file ID，之后每个请求都能用。真正有意思的是 token 计数。官方营销文案不会告诉你：上传文件的内容依然会被处理进每个请求，每问题约 3,050 个输入 token——无论你用哪种方式。引用文件只是在这个基础上加了大约 25 token 的元数据开销。

// Arm 2: Anthropic Files API — upload once, reference by ID.
// One call, one file ID back, and the ID works in every
// following request.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const file = await client.files.create({
  file: fs.createReadStream("ledgerline-api-reference.md"),
  mimeType: "text/markdown",
});

console.log(file.id); // file_01ABC...

// Then use it in any conversation:
const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      { type: "file", file_id: file.id, title: "Ledgerline API Reference" },
      { type: "text", text: "Can token scopes be edited after creation?" },
    ],
  }],
});

4. 实测账单：上传一次反而更贵

5 个请求跑完，粘贴组总共约 15,250 输入 token；Files API 组约 15,375——多了 125 token，纯粹是引用文件的固定开销。没有哪个量级能让上传一次更省钱，因为文件内容每次都在重发。真正的赢家是 prompt caching：把文档作为稳定前缀缓存起来，后续请求只付缓存读取费，成本直接降一个数量级。

// Arm 1: paste the document into every request.
// Simple, no upload step — but the full doc is tokenized
// into every single request.

const doc = fs.readFileSync("ledgerline-api-reference.md", "utf8");
// ~3,050 input tokens per question either way — the file
// contents are still processed into every request.

for (const q of questions) {
  const msg = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: doc + "\n\n" + q }],
  });
  console.log(msg.usage.input_tokens);
}

// Arm 3: prompt caching on the stable prefix — the approach
// that came out of the results. Cache the document prefix once,
// then every follow-up pays only the cache-read fee.

const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      {
        type: "text",
        text: doc, // <-- stable prefix, gets cached
        cache_control: { type: "ephemeral" },
      },
      { type: "text", text: q },
    ],
  }],
});

// First request: full input tokens + cache write.
// Subsequent requests: small cache-read cost instead of
// re-tokenizing the whole document.

5. 准确率：三种方式全部 15/15

最反直觉的结果是准确率：三组 15 个答案全部正确。不可编辑的 token scope、独立的批量限流、常数时间签名比较、5 分钟重放窗口——所有细节三组都答对了。所以选择哪种方式，完全取决于你更在意时间还是钱：要省事选 Files API，要省钱选 prompt caching。

// The measured truth (5 requests, claude-sonnet-5):
// Arm 1 (paste):     ~3,050 input tokens per question
// Arm 2 (files):     ~3,050 + ~25 tokens overhead per request
//                    -> upload-once cost 125 MORE input tokens
// Arm 3 (cache):     cheapest after the first warm-up call
//
// All 15 answers were correct in every arm — accuracy did
// not move. What changed was the bill.

const results = {
  arm1_paste: { correct: 5, inputTokens: 15250 },
  arm2_files: { correct: 5, inputTokens: 15375 },
  arm3_cache: { correct: 5, inputTokens: 5100 }, // after warm-up
};

// Verdict: Files API saves you TIME, not MONEY. For pure
// token economics, prompt caching is the real winner.

6. 实用决策建议

如果文档会频繁更新、你需要长期引用同一份文件，Files API 的便利性值得那点 token 开销；如果文档稳定不变、你要跑大量请求，prompt caching 是压倒性胜利；如果只是偶尔问几个问题，直接粘贴最简单，成本和三组相比也没有实质差别。先量自己的请求量和文档稳定性，再选姿势。