Model Tier Comparison
| Model | Input / 1M | Output / 1M | Context | Thinking Default | Notes |
|---|---|---|---|---|---|
| Claude Fable 5 | $10.00 | $50.00 | 1M tokens | Always on - cannot be disabled | Requires 30-day retention; unavailable under ZDR |
| Claude Opus 5 | $5.00 | $25.00 | 1M tokens | On by default; disable allowed only at effort high or below | Own rate-limit bucket, separate from Opus 4.x |
| Claude Sonnet 5 | $2.00 | $10.00 | 1M tokens | Adaptive by default | Balanced production workhorse |
| Claude Haiku 4.5 | $1.00 | $5.00 | 200K tokens | Lightweight | Fastest/cheapest - high-volume, simple tasks |
Output is billed at roughly 5x the input rate on every tier. stop_reason: "refusal" is a normal 200 response on Fable 5 and Opus 5 - check it before reading content. Distractor to reject: "newest/most capable = best default choice" - each tier is a different point on the trade-off curve, not a strict upgrade.
The Four Token Buckets
| Bucket | usage Field | Rate vs. Base Input | When It's Billed |
|---|---|---|---|
| Regular input | input_tokens | 1x | Anything not cached |
| Cache write | cache_creation_input_tokens | ~1.25x (5-min TTL) / ~2x (1-hour TTL) | First time a prefix is cached |
| Cache read | cache_read_input_tokens | ~0.1x | A later call reuses the cached prefix |
| Output | output_tokens | ~5x | Every generated token |
If cache_read_input_tokens stays at zero across repeated, near-identical requests, something is silently breaking the cache (an interpolated timestamp, unsorted JSON, a varying tool list).
Cost Myths vs. Reality
| Myth | Reality |
|---|---|
max_tokens caps cost safely | It's an enforced ceiling the model can't see; hitting it truncates output (stop_reason: "max_tokens") - a failed attempt, not a saving |
| Caching makes repeated input free | Cache reads cost ~0.1x input rate, not zero; cache writes cost *more* than a plain input token |
| Fewer API calls = lower cost | Cost tracks token volume across all four buckets, not call count - 2 bloated calls can cost more than 20 lean ones |
| Image cost scales with what matters in the image | Images are tokenized by pixel area (~1 token per 28x28 patch) - downscale (e.g. to 1280x720, ~1,200 tokens) to cut cost with no accuracy loss |
count_tokens runs inference to estimate cost | It returns an exact input count with no inference run - free pre-flight estimate |
| Checking org-wide spend costs tokens | The Usage and Cost Admin API reports the four buckets in aggregate without spending any tokens - report reads aren't inference calls |
Four Questions for Model Selection
| Question | Points Toward Fast/Cheap Tier | Points Toward Strongest Tier |
|---|---|---|
| Task difficulty | Lookup, template-fill, simple classification | Multi-step reasoning, nuanced judgment, ambiguity |
| Latency budget | Tight (interactive chat turn) | None (nightly/async job → also consider Batches API) |
| Volume | High (multiplies any per-call price gap) | Low (per-call gap stays small in absolute terms) |
| Cost of a wrong answer | Low (human re-routes in seconds) | High (autonomous action, no review, real downstream cost) |
Scenario questions usually turn on identifying which one factor dominates - they don't all point the same direction. "Price the tail, not the median": always test candidate models on deliberately hard edge cases, since cost and error concentrate in the hardest slice of a workload.
Stepping-Down Method (Order Matters)
- Provisionally pick a tier using the four-question framework.
- Sweep
effort(low → high) on that tier against an eval set that includes hard cases. - If a lower effort holds accuracy, take that saving first - no model change needed.
- Only then consider dropping to the next tier down.
- Confirm the new tier's supported parameters and effort levels - they differ by tier.
- Reset effort to that tier's own default; don't carry over a hardcoded value.
- Re-sweep from there, one notch at a time - never several changes at once.
- Revisit periodically: volume grows, and a cheaper tier's capability can close the gap over time.
Distractor to reject: judging keep/revert from a single test run. A difference of a task or two of pass rate on one comparison is noise, not signal - use repeated trials against a fixed eval set.
Three Independent Optimisation Knobs
| Lever | Controls | Where It Lives | Key Caveat |
|---|---|---|---|
| Effort | Thinking depth and tool-call consolidation together | output_config.effort: low/medium/high/xhigh/max | Changing it mid-conversation invalidates the prompt cache |
| Adaptive thinking | Whether the model reasons step-by-step before answering | thinking: {type: "adaptive"} | Replaces the removed budget_tokens on current models (Fable 5, Opus 5, Sonnet 5) |
| Task budget (beta) | Token ceiling for a whole agentic loop, advisory - model paces itself | output_config.task_budget, requires streaming | Floor of 20,000 tokens; changing mid-task invalidates the cache |
Not the same as max_tokens: that's a hard, model-blind ceiling with zero thoroughness effect - hitting it truncates output rather than saving cost.
Effort Pitfalls & Patterns
| Symptom / Situation | Fix | Why |
|---|---|---|
| Want to save cost on a model with thinking on by default (e.g. Opus 5) | Lower effort, don't disable thinking | Disabling thinking can leak a tool call into visible text instead of a tool_use block - no error raised, agentic loop silently breaks |
Code uses budget_tokens on Fable 5 / Opus 5 / Sonnet 5 | Switch to effort + adaptive thinking | budget_tokens is removed on current models and errors |
| Research/knowledge-style task, cost-sensitive | Try low effort first | Accuracy curve tends to be nearly flat - low effort often captures most of the accuracy |
| Long-horizon coding/agentic task | Sweep effort carefully before cutting it | Effort is a genuine trade-off here - dropping it can give up real accuracy |
| Workload has a cheap, reliable pass/fail signal (tests, validator) | Run everything at low effort, re-run only failures at high effort | Captures most of the accuracy of always running high, while paying the higher cost only on the harder tail |
Cost Optimisation Order & Driver Matching
Free wins first (lower cost, no quality loss - apply always): prompt caching (biggest lever in agentic loops - an uncached loop's cost grows roughly with the square of turn count), the Batches API (50% off every token type, async/latency-insensitive work only, no mid-batch tool loop), and input hygiene (retrieval instead of inlining large docs, pruning unused tool schemas, downscaling images).
Trade-offs after that (exchange cost for capability - validate against an eval set each time): effort/task budget tuning, model tier / cheap-tier-first routing, then multi-model architectures.
| Cost Driver | Matching Lever | Not This |
|---|---|---|
| Repeated system prompt / tool schema on every call | Prompt caching | A cheaper model |
| Large reference doc inlined into every prompt | Retrieval tool (input hygiene) | Batching |
| Async work nobody waits on synchronously | Batches API | Effort tuning |
| Bulky tool results piling up in a long loop | Context editing / compaction / pruning | A model downgrade (doesn't touch the accumulation) |
| Thinking/tool-call depth dominates spend, eval headroom exists | Effort first, tier drop only after | Jumping straight to a cheaper model |
| Two-Model Pattern | Pays Off When | Backfires When |
|---|---|---|
| Advisor (cheap model runs loop, escalates hard cases) | Wide capability gap + reliable escalation signal | Escalation signal is weak - can be worse than the strong model alone |
| Orchestrator (strong model plans, delegates bulk sub-tasks) | Genuine bulk fan-out of independent work | A single dependent chain - one tuned model usually beats the delegate/merge overhead |
Distractor to reject: treating caching, batching, and routing as mutually exclusive - a mature system stacks them. Always measure cost per completed task, not per token or per request - a cheaper config that fails more often can cost more overall.