Anthropic has taken its Files API out of beta and introduced a browser‑use toolset, allowing a document to be uploaded once and then referenced by a file ID in every subsequent request. This shift matters because it separates document management from token‑cost optimisation, while a separate feature—prompt caching—can dramatically lower billed input for repeated queries.
How the Files API Works
The API accepts a single upload call that returns a file identifier. Subsequent calls include that identifier instead of the raw text. The service supports formats that cannot be pasted directly, such as PDFs or images, and offers optional expiration settings for stored files. Crucially, the uploaded content is still processed for each request, adding roughly 25 extra tokens per call. In the test, the Files API arm used 15,371 input tokens versus 15,246 when the full reference was pasted each time, indicating a slight token overhead rather than a saving.
Prompt Caching Mechanics and Savings
Prompt caching treats the document as a cached prompt fragment. The first request incurs a cache write billed at 2,990 tokens (with a 25 % premium over normal input). Subsequent reads are billed at about one‑tenth the rate of regular input, so the four following queries cost only 11,960 cache‑read tokens. The cache expires after five minutes of inactivity, so the cost model assumes a steady request stream. Implementing caching requires moving the document into the system prompt and adding a cache marker, which changes request structure.
Empirical Comparison
A controlled experiment ran five developer‑support questions against three configurations on claude‑sonnet‑5:
- Arm 1 – Paste every time: 15,246 input tokens, 1,399 output tokens.
- Arm 2 – Files API: 15,371 input tokens, 1,434 output tokens.
- Arm 3 – Prompt caching: 271 cache‑write tokens, 2,990 cache‑write, 11,960 cache‑read, 1,642 output tokens.
All three arms produced identical, correct answers, confirming that answer quality is unaffected by the chosen method. The Files API did not reduce token usage; prompt caching cut billed input to roughly a third of the paste‑every‑time approach.
Operational and Security Considerations
From an architecture perspective, the Files API is valuable when a team needs a single, versioned source for large or non‑text assets, or when expiration policies are required. Since the content is re‑processed on each call, there is no cost advantage, so the decision should be driven by maintainability rather than economics.
Prompt caching offers a clear cost benefit for static reference material that is queried repeatedly. The trade‑offs include a five‑minute cache lifetime, the need to restructure prompts, and the potential for cache‑miss latency. No new security controls are introduced by either feature, but storing files externally may require alignment with data‑handling policies.
Related CloudNinjas coverage: AI engineering.
What This Means For Practitioners
- Use the Files API when you need a reusable, centrally managed document—especially for PDFs, images, or when you want expiration control.
- Enable prompt caching for static reference texts that are queried often; expect up to a two‑thirds reduction in billed input.
- If both problems apply, combine the two: upload the file and reference it with a cache marker.
- Be aware of the five‑minute cache expiry; design your request patterns accordingly or accept occasional cache writes.
- Update CI/CD scripts to handle the one‑time upload step and to include the cache marker when appropriate.
