Anthropic Claude API：AI 工程师完全指南（2026）

Anthropic Claude API 提供了对 Claude 模型家族的程序化访问——从轻量级的 Haiku 4.5 到顶级的 Opus 4.8。所有模型均支持文本和图片输入、streaming、tool use、prompt caching 以及 extended thinking。你只需在 console.anthropic.com 注册、获取 API key、将 HTTP 客户端（或 Anthropic SDK）指向 https://api.anthropic.com，即可开始构建。

我们写这篇指南是因为 Anthropic 的模型阵容在 2025–2026 年间快速扩展——Opus 4、4.1、4.5、4.6、4.7、4.8，加上 Sonnet 4、4.5、4.6，Haiku 4.5，以及全新的 Fable 5——选择哪个模型、定价机制、effort 参数的作用、速率限制分层如何运作，都容易让人困惑。这是我们首次将 Anthropic 集成到路由层时最想要的一站式参考。

3 分钟快速开始

第一步：注册账号。 访问 console.anthropic.com 进行注册。Anthropic 支持邮箱注册和 Google OAuth。

第二步：获取 API key。 前往 Settings → API Keys，点击"Create Key"。立即复制——Key 只会显示一次。请安全保存（环境变量、密钥管理器，绝不要写在代码里）。

第三步：发起首次调用。 安装 Anthropic Python SDK：

pip install --upgrade anthropic

然后运行：

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_ANTHROPIC_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "什么是 Claude？"}],
)

print(message.content[0].text)

就这样。注册后你会进入 Start 级别，月度消费上限为 $500——足够原型验证和测试。

使用 OpenAI SDK（兼容模式）

如果你的代码已经在用 OpenAI Python SDK，Anthropic 提供了 OpenAI 兼容接口。安装 openai 包并指向 Anthropic：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ANTHROPIC_KEY",
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "什么是 Claude？"}],
)

print(response.choices[0].message.content)

这在多供应商路由场景下特别有用——通过切换 base_url 和 model，你可以在 Claude、OpenAI、DeepSeek 之间切换，其余代码完全不变。

通过 API 可用的所有 Claude 模型

Anthropic 当前的模型阵容分为三个层级：Opus（顶级智能）、Sonnet（平衡性能）和 Haiku（速度优先）。以下是截至 2026 年 6 月的可用模型：

关键要点：

• Opus 4.7+ 使用新的 tokenizer，相同文本大约多产生 30% 的 token。在与 Opus 4.5 或 Sonnet 模型比较成本时，需要考虑这个因素。
• Opus 4.1 及更早版本已弃用或退役，且定价显著更高（$15/$75 per MTok）。如果仍在使用，建议迁移到 Opus 4.5+。
• Fable 5 是最新且最强的模型，定价 $10/$50 per MTok。它使用 adaptive thinking（始终开启），而非手动 extended thinking。

关于模型弃用时间表的详细信息，请参阅 Anthropic 的模型弃用页面。我们也有一份 Anthropic 弃用节奏迁移指南。

Extended Thinking 与 Effort 参数

Extended thinking 是 Claude 与大多数竞品的核心差异。它让模型在给出最终答案之前进行逐步推理——在 API 响应中以 thinking 内容块的形式可见。

如何启用 Extended Thinking

对于 Opus 4.5、Haiku 4.5 及更早模型，使用手动 budget_tokens：

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=16384,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
    },
    messages=[{"role": "user", "content": "请一步步解决这个问题：..."}],
)

对于 Opus 4.6+、Sonnet 4.6、Opus 4.7 和 Opus 4.8，使用 adaptive thinking 配合 effort 参数：

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    effort="high",
    messages=[{"role": "user", "content": "设计一个分布式缓存系统。"}],
)

对于 Fable 5，adaptive thinking 始终开启——无法禁用。使用 effort 参数控制推理深度。

Effort 级别详解

effort 参数控制 Claude 在推理上花费的 token 数量：

实用建议： 对于 Sonnet 4.6，Anthropic 建议从 medium effort 作为默认值，而不是 high——因为模型默认的 high 对于简单请求可能产生不必要的延迟。

Prompt Caching

Prompt caching 是 Claude API 中最节省成本的功能之一。它缓存常用的 prompt 前缀（系统指令、文档、tool 定义），后续调用仅需支付缓存命中价格——比基础输入定价便宜 90%。

提供两种缓存 TTL：5 分钟（写入更便宜，保留时间短）和 1 小时（写入更贵，保留时间长）。根据调用频率选择。对于流量稳定的生产系统，1 小时缓存通常能快速回本。

速率限制奖励： 对于大多数 Claude 模型，缓存命中的 token 不计入 ITPM（每分钟输入 token 数）限制。在 80% 缓存命中率下，实际处理的总输入 token 量是原始 ITPM 限额的 5 倍。

启用缓存时，在消息内容中添加 cache_control 断点：

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一位专业的代码评审员...",  # 长系统提示
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "评审这个 PR：..."}],
)

Streaming

所有 Claude 模型都支持通过 server-sent events (SSE) 进行 streaming。对于面向用户的应用，streaming 至关重要——它降低感知延迟，让你可以立即显示部分响应：

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "解释量子计算。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

配合 extended thinking 使用 streaming 时，thinking 块会先到达，然后是文本响应。你可以实时查看或展示 thinking 内容。

Tool Use（函数调用）

Claude 在所有当前模型上都支持 tool use（函数调用）。你在 API 请求中定义 tools，Claude 在决定调用时返回 tool_use 内容块：

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "获取城市当前天气",
            "input_schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                },
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "东京现在的天气怎么样？"}],
)

当 Claude 返回 tool_use 块时，在本地执行函数并发送 tool_result 消息继续对话。Claude 可以在单轮中链式调用多个 tool，非常适合 agent 工作流。

速率限制与分级

Anthropic 使用分级速率限制系统。你的组织会随着用量和消费增长而逐步升级：

速率限制在三个维度上衡量：每分钟请求数（RPM）、每分钟输入 token 数（ITPM） 和 每分钟输出 token 数（OTPM），每个模型类别分别设置。

最近变化（2026 年 6 月）： Anthropic 统一了速率限制分级，使 Sonnet、Opus 和 Haiku 共享相同的升级路径。此前，同一级别内不同模型类别可能有不对称的限额。这一简化意味着你的级别现在统一应用于所有 Claude 模型。

命中速率限制时，API 返回 429 错误并附带 retry-after 头。实现指数退避，或将溢出流量路由到备用供应商。

常见错误及修复

thinking 相关错误提示： thinking 的 API 接口演进很快。Opus 4.7+、Opus 4.8 和 Fable 5 不再接受 budget_tokens（返回 400）。请改用 adaptive thinking 配合 effort 参数。Opus 4.5 和 Haiku 4.5 仍然接受 budget_tokens。

生产上线清单

在使用 Claude API 上生产之前，确认以下事项：

1. 使用 prompt caching——对系统提示、tool 定义和重复上下文进行缓存。缓存命中 90% 的成本降低不可忽视。
2. 显式设置 effort 级别——而不是依赖默认的 high。Sonnet 4.6 建议从 medium 开始；agent 循环中的 Opus 使用 high 或 xhigh。
3. 实现 streaming——面向用户的响应必须使用 streaming 降低感知延迟。
4. 处理 429 错误——实现指数退避，可选地路由到其他供应商进行降级。
5. 锁定模型版本——使用 claude-sonnet-4-5 而非通用的 claude-sonnet，避免 Anthropic 发布新版本时行为变化。
6. 合理设置 max_tokens——在使用 extended thinking 的 agent 工作流中，为 thinking token 留出空间——在旧版模型（Opus 4.5、Haiku 4.5）上它们计入 max_tokens。
7. 监控你的级别——在 Settings → Limits 查看当前级别和使用量。在接近限额时主动申请升级。
8. 使用 Messages API——而非旧版 Completions API。Messages API 支持所有当前功能（thinking、tools、caching、vision）。

TheRouter 集成

如果你正在使用 TheRouter 在多个供应商之间路由请求，Claude 模型可通过 Anthropic 供应商获得，支持自动降级。TheRouter 将 OpenAI 兼容请求路由到已配置的供应商，因此你可以通过单一 endpoint 同时访问 Claude、DeepSeek、DashScope 等。

通过 TheRouter 路由 Claude 的主要优势：

• 降级路由： 当 Opus 命中速率限制或返回错误时，TheRouter 可自动路由到备用供应商，如 SiliconFlow 或 Volcengine Ark。
• 统一计费： 通过单一计费界面跟踪 Claude、OpenAI、DeepSeek 和国内供应商的消费。
• 模型别名： 在代码库中使用一致的模型名称，TheRouter 处理供应商特定的映射。

关于降级策略的深入讨论，请参阅我们的 LLM API 降级路由指南。

常见问题

Q：编码应该选哪个 Claude 模型？ Opus 4.8 是 Anthropic 最强的编码模型。如果关注成本，Sonnet 4.6 在 medium effort 下提供了出色的平衡。编码 sub-agent 可选 Haiku 4.5，快速且便宜。详见我们的编码 agent 模型对比。

Q：Claude 定价与 OpenAI、DeepSeek 相比如何？ Claude Sonnet 4.5/4.6 为 $3/$15 per MTok，对标 OpenAI GPT-5.5 的 $2/$8 per MTok 和 DeepSeek V4-Flash 的 $0.14/$0.28 per MTok。Opus 4.8 的 $5/$25 对标 GPT-5.5-Pro。DeepSeek 仍是预算首选；Claude 在能力而非价格上竞争。

Q：能用 OpenAI SDK 调用 Claude 吗？ 可以。Anthropic 提供了 OpenAI 兼容 endpoint。将 base_url 改为 https://api.anthropic.com/v1/，使用 Anthropic API key。部分 Anthropic 专有功能（budget_tokens 形式的 extended thinking、prompt caching 语法）可能无法一一映射。

Q：Extended thinking 和 effort 有什么区别？ Extended thinking（budget_tokens）是旧机制——手动设置 thinking token 预算。Effort 是更新的推荐方式，适用于 Opus 4.6+ 和 Sonnet 4.6——通过单一参数（low/medium/high/xhigh/max）控制所有 token 消耗，包括 thinking。Fable 5 只支持 effort。

Q：如何避免 429 速率限制？ 使用 prompt caching（缓存命中 token 不计入 ITPM）、实现指数退避、考虑将溢出路由到备用供应商。如果持续命中限制，通过 Anthropic Console 申请升级级别。

---

来源：Anthropic 定价（获取于 2026-06-29）、Anthropic 速率限制（获取于 2026-06-29）、Anthropic 模型概览（获取于 2026-06-29）、Anthropic extended thinking 文档（获取于 2026-06-29）、Anthropic effort 文档（获取于 2026-06-29）。