Claude Fable 5.1 API Guide: Migrate Without Surprises

The Claude Fable 5.1 API migration looks like a one-line model change. That line is necessary, but it is not a deployment plan. Forced tool selection and mutable conversation histories can turn an otherwise valid integration into an HTTP 400, while a poorly structured prompt can erase the release’s main cost advantage.

Claude Fable 5.1 became generally available on September 1, 2026. This guide builds a working Python request, tunes effort, enables caching, and tests the behaviors that matter before production traffic moves.

Claude Fable 5.1 API facts at a glance

The model ID is claude-fable-5-1. According to the official Fable 5.1 model page, it has a one-million-token context window, supports up to 128,000 output tokens, and uses always-on adaptive thinking.

Setting	Claude Fable 5.1	Migration meaning
API model ID	claude-fable-5-1	Replace the prior model string
Input / output	$10 / $50 per million tokens	Same base rates as Fable 5
Five-minute cache write	$12.50 per million tokens	Costs more than ordinary input once
Cache read	$0.25 per million tokens	One quarter of Fable 5’s cache-read rate
Default effort	high	Benchmark lower levels before changing it
Model retirement	Not before September 1, 2027	Still monitor the lifecycle page

Anthropic positions Fable 5.1 for demanding reasoning and long-horizon agentic work, not as the automatic starting point for every API call. Its launch results include 55.8% on Terminal-Bench 4.0 versus 42.0% for Fable 5. Those are vendor-published measurements, useful for deciding what to evaluate rather than proof that your application will improve. Anthropic’s launch analysis provides the full test context.

Make your first Claude Fable 5.1 API request

Install the current Python SDK and export the API key outside your source code. The Claude API quickstart uses the same client pattern.

python -m pip install anthropic
export ANTHROPIC_API_KEY="your-api-key"

Then send an ordinary Messages API request:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1200,
    messages=[
        {
            "role": "user",
            "content": "Review this deployment plan and identify its riskiest assumption.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Use a small max_tokens value while confirming authentication and model access, then size it for the output your application accepts. A large context window does not require a large response ceiling. Log the request ID, stop reason, usage object, latency, and model name from the first test; those fields become the baseline for the canary later.

Do not add a manual thinking budget copied from an older integration. Fable 5.1 only supports adaptive thinking; thinking: {"type": "enabled", "budget_tokens": ...} returns an error. If you are comparing API design across providers, our reasoning-and-tools API tutorial offers a useful second implementation.

Set effort before optimizing prompts

Effort controls how much reasoning Fable 5.1 applies. The available values are low, medium, high, xhigh, and max. High is the API default, so writing it explicitly is mainly useful when you want configuration to be obvious:

message = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1200,
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": task}],
)

Start at high, then test medium as a cost and latency control. Reserve xhigh or max for tasks where your evaluations show enough improvement to justify more thinking time. Low effort can make fewer search or retrieval calls in agent loops, so it is a poor shortcut when current evidence is part of the job.

Changing request-level effort can also invalidate cached message prefixes. Fable 5.1 supports per-message effort changes that retain earlier cache hits, but that interface is beta. The official migration guide lists the required header and append-only system-message pattern.

Use prompt caching where the savings live

Fable 5.1 kept Fable 5’s input and output rates. Cache reads fell from $1 to $0.25 per million tokens. Anthropic estimates that shift can cut typical workload costs by about 25% and highly agentic workload costs by as much as about 45%, based on four weeks of August 2026 usage at default effort. Your result depends on how much stable context gets reused.

Automatic caching is the simplest starting point:

message = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1200,
    cache_control={"type": "ephemeral"},
    system=LONG_STABLE_SYSTEM_PROMPT,
    messages=conversation_history,
)

print(message.usage.model_dump_json(indent=2))

The default cache lifetime is five minutes. A one-hour entry uses {"type": "ephemeral", "ttl": "1h"} and has a higher write price. The prompt-caching documentation says Fable 5.1 needs at least 512 cacheable tokens. Shorter prefixes run normally but do not produce a cache entry.

The arithmetic explains the opportunity. Processing one million ordinary input tokens costs $10. Writing that same amount to a five-minute cache costs $12.50, but each qualifying read costs $0.25. The first call is more expensive; repeated calls create the advantage. Check cache_creation_input_tokens and cache_read_input_tokens in the response instead of assuming the annotation worked.

For a shared system prompt, explicit breakpoints give more control than automatic caching. Mark the last block that remains byte-identical across requests. Tool definitions come before system content and messages in the cache hierarchy, so changing a tool schema can invalidate everything after it. Stable ordering matters as much as stable wording.

Place timestamps, request IDs, and incoming user text after a stable cached prefix. If changing content sits inside the cached section, every request writes a new entry. The cache flag may be present while the savings are absent.

Fix the three migration traps

1. Stop forcing tool calls

Fable 5 accepted tool_choice values any and tool. Fable 5.1 rejects both with a 400 error. Leave tool selection at auto, identify the required tool in the instruction, and set strict: true on its schema. If the real requirement is schema-conformant JSON rather than a tool side effect, use structured output.

2. Keep conversation history append-only

A Fable 5.1 thinking block is bound to the system prompt, tools, and messages that preceded it. Editing an earlier turn can produce an invalid-signature error. This catches harnesses that rewrite the system prompt, truncate the middle of a transcript, reorder tool definitions, or rebuild earlier messages.

Append new instructions rather than editing old ones. If client-side compaction replaces the history, start a clean summarized conversation without replaying stale thinking blocks. Anthropic also documents a beta control that can drop mismatched blocks, but dropping them on every turn wastes prior reasoning and restarts cache work.

3. Test backward model switches

Fable 5.1 can read thinking blocks produced by several older Claude models. The reverse direction does not work. If a router sends a live Fable 5.1 conversation to an older fallback, the API removes incompatible thinking blocks and the fallback replans, potentially increasing cost and latency.

Treat that route as a distinct test case, not merely a backup model name. Our model fallback testing guide explains why an HTTP success can still violate an application’s quality, tool, or cost contract.

Verify the migration with production-shaped evals

Shadow representative traffic or start with a narrow canary. A toy prompt cannot exercise the tool loop, conversation length, fallback route, and stable context that motivated the model choice. Compare completed tasks—not isolated responses—against the same Fable 5 baseline.

Check	Pass condition
Task quality	Your existing evaluation stays flat or improves
Tool use	No forced-choice 400s; strict inputs validate
History	Long conversations produce no prefix mismatch
Fallback	Older models recover without hidden contract failures
Cache	Repeated workloads report cache-read tokens
Economics	Cost per successful task falls, not merely cost per token
Latency	Time to first response and total duration meet targets
Refusals	The client handles stop_reason: "refusal" explicitly

Record results by effort level. Include easy requests, retrieval-dependent questions, tool-heavy sessions, and at least one conversation that crosses your compaction boundary. Teams governing tool access around Claude Code can pair this API work with our Claude Code gateway setup.

A cheaper cache is not a cheaper model

Does your application reuse enough stable context for Fable 5.1’s lower cache-read rate to reduce cost per successful task? The answer will not be hiding in a launch benchmark. It will appear in cache telemetry beside tool correctness, history integrity, latency, and refusal handling.

Run a 14-day canary, then review those five measures before widening traffic. The model string may take one line; the evidence for keeping it should take considerably more.