[ ABORT TO HUD ]
SEQ. 1
SEQ. 2

Files API & Token Counting

📎 Citations & Files API⏱ 15 min⭐ 600 BASE XP

Reusable File References

The Files API allows you to upload documents once and reference them across multiple requests using a file_id. This eliminates the need to re-encode and re-upload large files for every API call — critical for applications that repeatedly analyze the same documents.

Three Input Methods

MethodExampleBest For
URL{ type: "url", url: "https://..." }Public documents, quick prototyping
Base64{ type: "base64", data: "..." }Private files, single-use uploads
File ID{ type: "file", file_id: "file_abc123" }Repeated analysis, multi-turn workflows

Token Counting API

Before sending a request, you can use the Token Counting endpoint to predict exactly how many tokens your message will consume. This is essential for:

  • Cost estimation: Calculate expenses before executing expensive queries.
  • Context management: Ensure your combined input stays within the model's context window.
  • Prompt optimization: Compare different prompt structures to find the most token-efficient approach.
// Count tokens before sending
const count = await anthropic.messages.count_tokens({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Your prompt here..." }],
  system: "Your system prompt..."
});
console.log(count.input_tokens); // e.g., 1847
💡 Pro Tip: Combine Token Counting with Prompt Caching to estimate costs accurately. Count tokens first, check if cache hits will apply, then calculate: cached tokens × 0.1 + uncached tokens × 1.0 = actual cost multiplier.
SYNAPSE VERIFICATION
QUERY 1 // 2
What is the advantage of using file_id references?
Files are encrypted
Upload once and reference across multiple requests without re-encoding
Files are stored permanently
It's cheaper than base64
Watch: 139x Rust Speedup
Files API & Token Counting | Citations & Files API — Claude Academy