Claude Fable 5 API 使用教程：新手入门指南

Anthropic 于 2026 年 6 月 9 日发布了 Claude Fable 5。开发者最关注的无疑是其 API 接入。好消息是，它沿用现行的 Messages API，唯一的改动在于模型字符串变为 claude-fable-5。本指南从一条 curl 命令入手，逐步讲解流式传输、工具调用、错误处理及成本估算——确保你能跑通代码并获得真实响应。如果你已有 Claude 开发经验，整体结构会非常熟悉。从旧模型迁移，只需修改模型字符串，如同当年从 Claude Opus 4.8 API 迁移一样简单。

快速上手 (TL;DR)

先去 Anthropic Console 获取 API 密钥，设置为环境变量 ANTHROPIC_API_KEY。然后向 Messages API 发送 POST 请求，传递 model: "claude-fable-5"、max_tokens 以及 messages 数组。推荐直接使用官方 Anthropic Python 或 TypeScript SDK，当然原始 HTTP 请求也能正常工作。对于长输出，流式传输可避免超时。定价：每百万输入 token 10 美元，每百万输出 token 50 美元。

核心是三个请求头：x-api-key 传递密钥；anthropic-version 指定 API 版本（当前稳定版本为 2023-06-01）；content-type 声明请求为 JSON 格式。请求体需包含三个字段：model、max_tokens 和 messages。这就是完整的交互协议。

响应以 JSON 对象返回。重点关注 content 字段，它是一个内容块列表：

{"id": "msg_01ABC...","type": "message","role": "assistant","model": "claude-fable-5","content": [{ "type": "text", "text": "- Predictable, resource-oriented URLs..." }],"stop_reason": "end_turn","usage": { "input_tokens": 18, "output_tokens": 96 }}

注意 content 是列表而非字符串，因为单个响应可混合文本块、工具调用块和思考块。在提取 text 之前，务必遍历列表并检查每个块的 type。stop_reason 指示模型停止原因（end_turn 表示正常结束），usage 提供后续计算成本所需的 token 计数。

在 Python 中调用 Fable 5

官方 Anthropic Python SDK 封装了请求头和 JSON 样板的繁琐工作。先安装：

pip install anthropic

基础调用代码如下。客户端会自动从环境中读取密钥，无需手动传递：

import anthropic client = anthropic.Anthropic() # 从环境变量读取 ANTHROPIC_API_KEY response = client.messages.create( model="claude-fable-5", max_tokens=1024, messages=[ {"role": "user", "content": "Summarize what makes a good REST API."} ], ) for block in response.content: if block.type == "text": print(block.text)

该模式与 curl 调用完全一致。传递 model、max_tokens 和 messages，返回的 content 是块列表。循环中用 block.type == "text" 过滤，确保安全提取文本。

添加系统提示词 (System Prompt)

系统提示词用于设定模型角色和对话基调。将其作为 system 字段单独传入，与 messages 分离：

response = client.messages.create( model="claude-fable-5", max_tokens=2048, system="You are a senior backend engineer. Be concise and use code examples.", messages=[ {"role": "user", "content": "Write a Flask route that validates a JSON body."} ], ) for block in response.content: if block.type == "text": print(block.text)

系统提示词是定义人设、输出格式约束以及跨轮对话保持规则的最佳场所。尽量保持稳定——频繁修改会使后续的提示词缓存失效。

流式传输长输出

任何可能生成较长回答的任务都建议使用流式传输。流式传输在 token 生成时即时推送，便于展示进度，同时避免大型非流式响应导致的请求超时。Fable 5 擅长处理长时任务，因此流式传输应作为实际负载的默认选择：

with client.messages.stream( model="claude-fable-5", max_tokens=4096, messages=[ {"role": "user", "content": "Explain idempotency keys for payment APIs."} ], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) final = stream.get_final_message() print(f"\n\nTokens: {final.usage.output_tokens}")

stream.text_stream 在文本块到达时逐个输出。flush=True 确保每个块立即打印，而非缓冲。流结束后，stream.get_final_message() 返回完整组装的消息，包括最终的 usage 数据——兼顾实时体验和完整对象获取，无需二次请求。

在 TypeScript / Node 中调用 Fable 5

Node SDK 结构几乎一致。先安装：

npm install @anthropic-ai/sdk

随后直接调用。客户端同样自动读取 ANTHROPIC_API_KEY：

import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // 读取 ANTHROPIC_API_KEY const msg = await client.messages.create({ model: "claude-fable-5", max_tokens: 1024, messages: [{ role: "user", content: "List 3 common API security mistakes." }], }); console.log(msg.content);

msg.content 与 Python 和 curl 中看到的块列表相同。按类型过滤提取纯文本：

const text = msg.content .filter((block) => block.type === "text") .map((block) => block.text) .join(""); console.log(text);

流式传输方式与 Python 相同。使用 client.messages.stream({...}) 后迭代事件，或通过 finalMessage() 获取组装结果。若对接前端聊天界面，可通过服务器路由进行流式传输，将数据块转发至浏览器。

Fable 5 的工具调用 (Function Calling)

工具调用允许 Fable 5 执行你定义的函数。通过 JSON schema 描述工具，模型自行决定何时调用，你执行实际函数并将结果回传给模型。Fable 5 在工具调用上表现强劲，非常适合智能体循环。

定义包含名称、描述和 input_schema 的工具：

tools = [ { "name": "get_order_status", "description": "Look up the status of a customer order by ID.", "input_schema": { "type": "object", "properties": { "order_id": {"type": "string"} }, "required": ["order_id"], }, } ]

将 tools 像 messages 一样传入请求：

messages = [ {"role": "user", "content": "What's the status of order A1855?"} ] response = client.messages.create( model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages, )

当模型决定调用工具时，响应中的 stop_reason == "tool_use"，并包含携带工具名称和所选输入的 tool_use 块。处理逻辑直观：追加助手响应，执行工具，然后在新用户轮次中以 tool_result 块形式返回结果：

if response.stop_reason == "tool_use": tool_use = next(b for b in response.content if b.type == "tool_use") # 用模型选择的输入运行你真实的函数 result = lookup_order(tool_use.input["order_id"]) # 你的代码 messages.append({"role": "assistant", "content": response.content}) messages.append({ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": tool_use.id, "content": result, } ], }) # 把结果发回去；模型现在会利用这个结果来回答 followup = client.messages.create( model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages, )

关键点是 tool_use_id：tool_result 块必须引用 tool_use 块的确切 id，以便模型关联结果与调用。对于多步智能体，可封装在循环中，直至 stop_reason 变为 end_turn。Python SDK 还提供了工具运行器自动处理循环，但手动版本展示了底层原理，便于加入审批或日志。

自适应思考与努力程度 (Adaptive Thinking and Effort)

Fable 5 支持自适应思考——模型可自主决定回答前的推理深度。此为可选功能。通过传入 thinking 参数启用，并用 output_config 调整整体深度与 token 消耗：

response = client.messages.create( model="claude-fable-5", max_tokens=4096, thinking={"type": "adaptive"}, output_config={"effort": "high"}, # low | medium | high messages=[ {"role": "user", "content": "Design a retry strategy for a flaky webhook receiver."} ], )

effort 控制模型工作量：低 effort 产生更简洁快速的响应；高 effort 带来更彻底的推理但 token 成本更高。简单查询与简短回答无需启用——额外推理浪费 token。复杂多步问题（Fable 5 为长时规划任务设计）才启用。先保持简单；当遇到需要更强推理的路径时，再添加 thinking。

错误处理与安全回退

实际集成必须优雅处理失败。SDK 抛出类型化异常，最好捕获特定类而非匹配错误字符串。你最常遇到的三个异常对应 HTTP 401、429 和 400：

import anthropic client = anthropic.Anthropic() try: response = client.messages.create( model="claude-fable-5", max_tokens=1024, messages=[ {"role": "user", "content": "Explain CORS preflight requests."} ], ) except anthropic.AuthenticationError: # 401: API 密钥错误或缺失。检查 ANTHROPIC_API_KEY。 print("Invalid API key. Rotate it in the Console and re-export.") except anthropic.RateLimitError as e: # 429: 请求太多。稍后重试。 retry_after = e.response.headers.get("retry-after", "60") print(f"Rate limited. Retry after {retry_after}s.") except anthropic.BadRequestError as e: # 400: 请求格式错误（参数错误、消息为空、结构错误）。 print(f"Bad request: {e.message}")

每个错误含义及应对：

• 401 (AuthenticationError)：密钥缺失、格式错误或已撤销。确认 ANTHROPIC_API_KEY 已在运行环境中设置，且 Console 中密钥仍有效。
• 429 (RateLimitError)：超过每分钟请求次数或 token 数限制。SDK 已自动用指数退避重试 429 和 5xx 错误（默认重试两次）。如需自定义退避逻辑，读取 retry-after 请求头。
• 400 (BadRequestError)：请求格式有误。常见原因包括 messages 数组为空、缺少 max_tokens，或消息角色未正确交替。错误消息通常指明具体字段。

关于安全回退：Fable 5 会将少量敏感查询（网络安全、生物化学、蒸馏尝试）路由到 Claude Opus 4.8 处理。此情况发生在不到 5% 的会话中。并非错误，请求仍会成功，但响应可能标记为不同模型。如果对 response.model 做日志或断言，发现不是 claude-fable-5 时不要报错——请求已被处理，仅底层换模型。若你的应用严格要求知道哪个模型作答，从返回对象读取 response.model，而非假设与传入的一致。

估算单次请求成本

定价为每百万输入 token 10 美元，每百万输出 token 50 美元。每个响应在 usage 中提供确切计数，因此可精确计算每次请求成本，无需猜测：

response = client.messages.create( model="claude-fable-5", max_tokens=1024, messages=[ {"role": "user", "content": "Write a SQL query to find duplicate emails."} ], ) input_tokens = response.usage.input_tokens output_tokens = response.usage.output_tokens input_cost = input_tokens / 1_000_000 * 10 output_cost = output_tokens / 1_000_000 * 50 total = input_cost + output_cost print(f"Input: {input_tokens} tokens = ${input_cost:.6f}") print(f"Output: {output_tokens} tokens = ${output_cost:.6f}") print(f"Total: ${total:.6f}")

输出 token 成本是输入 token 的五倍，因此保持响应简洁是降低成本最有效的方法。一个 2,000 输入 token + 500 输出 token 的请求成本为 2000 / 1M * $10 + 500 / 1M * $50，即 $0.02 + $0.025 = $0.045。乘以请求量即可估算预算。若输出成本占比过高，限制 max_tokens 并在系统提示词中要求简洁回答。输出定价逻辑与 Claude Opus 4.8 一致，只需替换为 Fable 5 的具体数值。