Claude Fable 5.1 于 2026 年 9 月 1 日发布，其 API 模型 ID 的准确字符串为 claude-fable-5-1，不带日期后缀。它的价格与 Fable 5 相同，为每百万输入 token 10 美元、每百万输出 token 50 美元，缓存读取费用降至每百万 0.25 美元，并且带来了三个 Fable 5 所不具备的破坏性变更。
本指南涵盖了全套流程：获取 API key、发送首次请求、控制 effort、流式传输、无需强制 tool_choice 的工具使用、拒绝退避策略（refusal fallbacks）、进度更新，以及读取 usage object 以确认缓存是否正按新费率运行。每个请求都是带有 JSON 的纯 HTTP 请求，因此你可以在将其写入应用程序代码之前，先在 Apifox 中进行构建和调试。
如果你正在迁移现有的 Fable 5 或 Opus 5 服务，而不是从零开始，请结合本指南阅读完整的迁移指南。有关模型的概述，请从了解 Claude Fable 5.1 是什么开始。
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。
首次调用前：会导致 400 错误的三个事项
1. Thinking 无法配置，只能进行引导。 Fable 5.1 会在每个请求上运行自适应 thinking。你可以省略 thinking 字段，或者发送 {"type": "adaptive"}。发送 {"type": "disabled"} 和 {"type": "enabled", "budget_tokens": N} 都会返回 400 错误。如果你是从 Opus 5 迁移过来的（Opus 5 在 high 级别或以下的 effort 接受 disabled），请移除该字段，改为使用 output_config.effort 来控制开销。
2. 强制工具使用已被移除。 设置 tool_choice: {"type": "any"} 和 {"type": "tool", "name": "..."} 会返回 tool_choice: type "tool" and "any" are not supported for this model.。解决办法见下文的工具使用步骤。
3. 你的组织需要开启 30 天数据保留。 Fable 5.1 属于受保护模型（Covered Model）。来自零数据保留的组织或工作区的请求会返回 400 invalid_request_error，且不提供其他线索。如果你的首次调用失败且请求 body 看起来没有问题，请务必先检查数据保留设置。
这三点均已在 Anthropic 的 What’s new in Claude Fable 5.1 中详细说明。
步骤 1：获取 API key
登录 Claude 控制台，打开组织设置中的 API keys 区域，然后创建一个 key。创建后请立即复制，后续将无法再次查看。请将其导出为环境变量，而不是直接粘进代码中：
export ANTHROPIC_API_KEY="sk-ant-..."
在 Apifox 中，将其存为名为 ANTHROPIC_API_KEY 的环境变量，并在 header 中使用 {{ANTHROPIC_API_KEY}} 进行引用，这样 key 就绝不会遗留在保存的请求 body 中。
步骤 2：发送你的首次请求
向 https://api.anthropic.com/v1/messages 发送一个 POST 请求，并包含三个 header：x-api-key、anthropic-version: 2023-06-01 和 content-type: application/json。
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-fable-5-1",
"max_tokens": 16000,
"messages": [
{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}
]
}'在 Python 中使用官方 SDK 进行相同的调用：
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-fable-5-1",
max_tokens=16000,
messages=[{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}],
)
if response.stop_reason == "refusal":
print("declined:", response.stop_details.category if response.stop_details else None)
else:
for block in response.content:
if block.type == "text":
print(block.text)从第一次调用开始，建议养成两个习惯。在读取 content 之前，请务必先检查 stop_reason，因为分类器拒绝（classifier refusal）返回的是 HTTP 200，但带有空的 content 数组。此外，要为 max_tokens 留出足够空间。它同时对思考 token（thinking tokens）和响应 token（response tokens）进行总量限制，而思考功能默认总是开启的，因此如果使用针对无思考模型微调的严格数值，在此处会导致输出截断。
响应包含一个 thinking 块，在默认的 display 设置为 "omitted" 时，其文本为空。这是符合预期的。请在下一轮交互中原封不动地将其传回。
步骤 3：通过 effort 控制成本与深度
effort 参数 是 Fable 5.1 的核心控制杠杆。它位于 output_config 内部而非顶级结构中，可接受 low、medium、high、xhigh 和 max。默认值为 high。
{
"model": "claude-fable-5-1",
"max_tokens": 16000,
"output_config": {"effort": "medium"},
"messages": [{"role": "user", "content": "Summarize this changelog in five bullets."}]
}Anthropic 的建议是：首先从 high 开始，然后根据你自己的评估测试（evals）对其余选项进行对比测试。即使你之前已经在 Fable 5 上做过评估，也需要重新运行一遍测试，因为不同模型中相同级别的名称并不代表相同的思考量。他们声称 medium 级别的性能大致与 Fable 5 相当但成本更低，而 low 级别在单次任务成本上通常比 Opus 和 Sonnet 更具竞争力。关于 effort 参数有两个特定行为需要注意：在 low 级别下，Fable 5.1 调用搜索和检索工具的频率更低，更多地直接从记忆中回答；而在 xhigh 和 max 级别下，它可能会先在思考过程中起草一份长篇交付内容，然后再重新撰写一遍，因此需要为这两者设置充足的 max_tokens。
**对话中途更改 effort (beta)。**在 Fable 5 中，在请求之间更改顶层 effort 会导致缓存前缀失效。而在 Fable 5.1 中，发送一条内容为空且包含 output_config 的 role: "system" 消息，即可从下一个用户轮次开始更改 effort，且不会导致缓存失效。这需要使用 mid-conversation-output-config-2026-07-01 beta header 以及 client.beta.messages 命名空间。
response = client.beta.messages.create(
model="claude-fable-5-1",
max_tokens=16000,
output_config={"effort": "high"},
betas=["mid-conversation-output-config-2026-07-01"],
messages=[
{"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
{"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
{"role": "system", "content": [], "output_config": {"effort": "low"}},
{"role": "user", "content": "Summarize the plan in one sentence."},
],
)通过这种方式降低 effort 是可靠的。如果是提高 effort，在大幅度提升（如从 low 提升至 xhigh）时效果最好。Opus 5 的 effort 参数指南深入探讨了这五个级别，同样的语义在此处也适用。
步骤 4：流式传输响应
Fable 5.1 在较高 effort 下处理复杂任务时，单个轮次可能会运行数分钟，因此对于任何可能较长的内容，请使用流式传输。当 max_tokens 值接近 128,000 的上限时，SDK 要求使用流式传输以避免 HTTP 超时。
with client.messages.stream(
model="claude-fable-5-1",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a test plan for a rate-limited public API."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final = stream.get_final_message()
print(final.stop_reason, final.usage.output_tokens)在 Apifox 中，流式响应会即时渲染，这是直观查看 high effort 轮次在输出第一个文本 token 前思考了多久的最快方式。
步骤 5：添加工具调用（无需强迫）
定义工具的方式与 Fable 5 相同。改变的是确保工具调用的方式。在 Fable 5 中，你可以通过 tool_choice: {"type": "tool", ...} 来强制调用工具。但在 Fable 5.1 中，这样做会返回 400 错误，因为强制调用会跳过思考过程，导致模型将推理过程写入参数中。
替代方案包含三个部分：将 tool_choice 保持为 auto、在指令中明确提及该工具，并在工具上设置 strict: true（严格工具使用）以及在数据模型中配置 additionalProperties: false，以确保参数始终通过校验。
record_summary_tool = {
"name": "record_summary",
"description": "Record the structured summary of the document.",
"strict": True,
"input_schema": {
"type": "object",
"properties": {"summary": {"type": "string"}},
"required": ["summary"],
"additionalProperties": False,
},
}
response = client.messages.create(
model="claude-fable-5-1",
max_tokens=16000,
tools=[record_summary_tool],
tool_choice={"type": "auto"},
messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)如果强制调用的目的仅仅是为了获取返回的 JSON，请完全改用结构化输出（output_config.format），而非使用工具。如果要求在多轮对话的当前轮次中进行特定调用的主体是你的应用程序而非用户，请在最新一轮的用户对话后追加一条 role: "system" 消息，其中标明该工具并指明该调用是必需的，随后在历史记录中保留该消息。tool_choice: {"type": "none"} 对于必须不能调用工具的轮次依然有效。
Agent 循环（agentic loop）本身保持不变：当 stop_reason 为 tool_use 时，执行每个 tool_use 块，在一条用户消息中返回所有 tool_result 块，并将 assistant 轮次按原样追加回去（包含思考块）。出于保留思考指南中解释的原因，最后这一条款在 Fable 5.1 上比在以往任何模型上都更为重要。
需要注意的一个行为：在较长循环中，当下一步的独立读取操作仅由任务隐式表明时，Fable 5 可能会并行批处理多个工具调用，而 Fable 5.1 可能会每轮仅发出一个工具调用。Anthropic 给出的解决方案是在每个 tool-result 消息后追加一句提示：“先在私密状态下列出接下来需要的内容；然后在本次响应中请求所有不依赖于其他结果的项。”（“First privately list what you need next; then request every item that doesn’t depend on another’s result in this one response.”）请将其作为轮次作用域的系统消息发送（clear_at: "next_user_message"，beta header mid-conversation-system-clear-at-2026-08-21），并保留此前的所有副本。
步骤 6：使用 fallback 处理拒绝
Fable 5.1 会运行安全分类器。被拒绝的请求将返回 HTTP 200，其中 stop_reason: "refusal"，并且包含一个标明类别的 stop_details object：cyber、bio、frontier_llm、reasoning_extraction 或 general_harms。在产生任何输出之前的拒绝是不计费的。
建议默认开启 fallback。最简单的形式是使用 fallbacks: "default" 配合 server-side-fallback-2026-07-01 beta header，它会在 Anthropic 针对该类别推荐的模型上重试被拒绝的请求。对于 Fable 5.1，允许的目标模型为 claude-opus-4-8 和 claude-opus-5。
response = client.beta.messages.create(
model="claude-fable-5-1",
max_tokens=16000,
fallbacks="default",
betas=["server-side-fallback-2026-07-01"],
messages=[{"role": "user", "content": "Audit this authentication middleware for logic bugs."}],
)
fallback_ran = any(
entry.type == "fallback_message" for entry in (response.usage.iterations or [])
)
if fallback_ran and response.stop_reason != "refusal":
print("served by", response.model)
响应在其顶层的 model 字段中提供了实际提供服务的模型名称，并且 fallback 内容块会标记接管切换。在回传该轮对话时，请将该块保留在其出现的位置。注意两项限制：fallbacks 会在 Batches API 上被拒绝；此外，它在 Bedrock、Google Cloud 或 Foundry 上不可用，在这些平台上，你需要改在客户端注册 SDK 的 BetaRefusalFallbackMiddleware。拒绝处理指南涵盖了计费、粘性路由以及附带 fallback credit 的手动重试。
步骤 7：在长对话轮次中获取进度更新
在工具调用之间，Fable 5.1 会针对其发现的内容以及下一步计划撰写简短的笔记。每个笔记都作为单独的 thinking 块紧贴在工具调用之前到达，并且在默认的 display 设置下，这些块是空的。通过附带 thinking-display-updates-2026-08-18 beta header 并设置 display: "updates"，你可以在推理过程本身保持隐藏的同时，以文本形式接收这些更新。
{
"model": "claude-fable-5-1",
"max_tokens": 16000,
"thinking": {"type": "adaptive", "display": "updates"},
"tools": [...],
"messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]
}
任何文本非空的 thinking 块都可以作为一条状态行进行渲染。Fable 5.1 生成此类信息的频率低于 Fable 5，因此如果你的 UI 依赖于过程叙述，还需要移除提示词中要求模型将发现保留到最终响应中才输出的相关语句。
步骤 8：读取 usage 对象以享受 $0.25 的缓存费率
Prompt caching（提示词缓存）体现了 Fable 5.1 的价格调整。在稳定的前缀上加上 cache_control，并在 usage 中确认命中情况：
response = client.messages.create(
model="claude-fable-5-1",
max_tokens=16000,
system=[{"type": "text", "text": LONG_STABLE_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
messages=[{"role": "user", "content": "Which endpoints in the spec lack an error schema?"}],
)
u = response.usage
print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)
首次发送时，cache_creation_input_tokens 不为零（在 5 分钟 TTL 内按每百万 token $12.50 计费）。如果在五分钟内进行第二次发送，cache_read_input_tokens 应该不为零，按每百万 token $0.25 计费。如果多次相同的请求中它始终为零，说明前缀中的某些内容每次都在发生改变：例如系统提示词中的时间戳、未排序的 JSON，或者发生变化的 tools 数组。可缓存的提示词最小长度为 512 个 token。
关于该模型有两个特定的缓存事实。由于缓存未命中的成本是命中的 40 倍，保持缓存热度比在 Fable 5 上更加重要；而单条消息级别的 effort 和轮次作用域的 system 消息之所以存在，部分原因就是为了让你能在会话中途进行调整而无需重置。此外，重置缓存的相同编辑操作（例如重建 system、编辑先前的对话轮次）现在也会导致思考块（thinking blocks）失效，因此“仅追加（append-only）”的操作准则能带来双重收益。
在 Apifox 中测试和调试整个流程
将上述每个步骤保存为一个 Apifox 集合中的请求：首次调用、effort 变体、流式传输、工具循环、降级重试（fallback）、缓存检查。为 Key 和 model 使用环境变量，这样只需一次修改即可在 claude-fable-5 和 claude-fable-5-1 之间切换整个集合。然后添加断言：在无害的测试提示词上 stop_reason 不为 refusal，第二次缓存请求时的 usage.cache_read_input_tokens 大于零，并且在使用 thinking-binding header 运行时没有 input_transformations 条目的 reason 为 "prefix_binding_mismatch"。在对测试框架/套件进行任何更改前后运行该集合。下载 Apifox 以进行配置；同一个集合还可以通过 Apifox CLI 用作 CI 检查。
你可能会遇到的错误和坑
- 400
tool_choice: type "tool" and "any" are not supported for this model.切换为auto加上指令说明以及strict: true。 - 针对
thinking: {"type": "disabled"}报 400 错误。 移除该字段，改为降低 effort 值。 - 请求 body 合法但返回 400
invalid_request_error。 检查组织或工作区是否设置了 30 天的保留期。 - 400
Invalid signature in thinking block. The block is bound to a different conversation.你的代码修改了先前的轮次、system prompt 或 tools 数组。请参阅保留思考（preserved thinking）指南。 - 思考文本静默为空。 这是
display: "omitted"下的预期行为。如果你要渲染它，请使用"summarized"或"updates"。 - 缓存读取量为零。 存在不稳定的前缀。检查是否存在时间戳和未排序的 object。
- Priority Tier 请求校验失败。 Fable 5.1 不支持 Priority Tier，而 Fable 5 支持。
常见问题（FAQ）
Claude Fable 5.1 API 的模型 ID 是什么？ claude-fable-5-1。在 Amazon Bedrock 上为 anthropic.claude-fable-5-1；Google Cloud、Microsoft Foundry 以及 AWS 上的 Claude Platform 使用 claude-fable-5-1。
使用 Claude Fable 5.1 需要 beta header 吗？ 不需要。基础模型、自适应思考、effort、tools 和缓存都可以在标准的 anthropic-version: 2023-06-01 header 下正常工作。仅在需要单条消息级别的 effort、轮次作用域的 system 消息、进度更新、服务端降级以及 thinking-binding 控制时才需要 Beta header。
我可以在 Claude Fable 5.1 上强制进行工具调用吗？ 不能。设置 tool_choice 为 any 和 tool 会返回 400 错误。请使用 auto，在提示词中明确指出工具名称，并设置 strict: true 以确保生成符合数据模型的参数，或者使用结构化输出进行 JSON 提取。
Claude Fable 5.1 API 的最大输出是多少？ Messages API 支持最大 128,000 个 Token。对于任何大型内容，请使用流式传输（Stream）。300,000 Token 的 Batch API beta 版未列出 Fable 5.1。
如何查看费用更低的缓存读取？ 查看重复请求中的 usage.cache_read_input_tokens。在 Fable 5.1 上，这些 Token 的计费价格为每百万个 $0.25，而 Fable 5 为 $1，Opus 5 为 $0.50。价格明细中对具体数据进行了推算和展示。
Fable 5 API 指南是否仍然适用？ 大致适用。Fable 5 API 指南涵盖了相同的接口，但其中强制工具使用的示例现在会返回 400，且该指南早于单条消息的 effort 和进度更新功能。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
