如何使用 Claude API？3 种接入方案实测，附完整代码（2026）

上个月我接了个私活，甲方要做一个合同的小工具，指定要用 Claude Opus 4.7 来做长文本理解。说实话一开始我是拒绝的——之前用 Claude 都是网页版手动复制粘贴，API 调用还真没正经搞过。折腾了大概两天半，把三种接入方式都试了一遍，踩了不少坑，这里把完整过程记录下来。

直接回答标题问题：使用 Claude API 有三种主流方案——Anthropic 官方 SDK 直连、OpenAI 兼容格式调用、以及通过聚合平台统一接入。如果你只是想最快跑通，往下翻到方案二，改个 base_url 五分钟就能出结果。

先说结论

方案	延迟（P95）	上手难度	适合场景
Anthropic 官方 SDK	420ms	中等	需要原生特性（如 Tool Use beta）
OpenAI 兼容格式	310-350ms	极低	已有 OpenAI 代码想换模型
聚合平台中转	280-340ms	极低	多模型切换、团队协作

环境准备

Python 3.10+，装两个包就行：

pip install anthropic openai

我用的是 Python 3.11.8，macOS Sonoma，测试日期 4 月 22 号。

方案一：Anthropic 官方 SDK 直连

最"正统"的方式。去 console.anthropic.com 注册账号，拿到 API Key。

import anthropic

client = anthropic.Anthropic(api_key="sk-ant-xxxxx")

message = client.messages.create(
 model="claude-sonnet-4-20260514",
 max_tokens=1024,
 messages=[
 {"role": "user", "content": "用一句话解释什么是 RAG"}
 ]
)

print(message.content[0].text)

跑起来没啥问题，但我第一次调的时候直接报了个错：

anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}

原因很蠢——我把 Key 复制的时候多带了个换行符。strip 一下就好了。

Streaming 模式也很简单：

with client.messages.stream(
 model="claude-sonnet-4-20260514",
 max_tokens=1024,
 messages=[{"role": "user", "content": "写一个 Python 快排"}]
) as stream:
 for text in stream.text_stream:
 print(text, end="", flush=True)

实测 Streaming 首 token 大概 180ms 出来，体感还行。但有个问题——如果你之前项目全是用 OpenAI SDK 写的，换 Anthropic SDK 意味着一堆代码要重构。接口格式不一样，返回结构也不一样。

方案二：OpenAI 兼容格式调用

这个方案是我最终选的。Claude 现在支持 OpenAI 兼容协议，你用 openai 这个 Python 包，改一下 base_url 和 model 名字就能调 Claude。

from openai import OpenAI

client = OpenAI(
 api_key="your-key",
 base_url="https://api.ofox.ai/v1"
)

response = client.chat.completions.create(
 model="claude-sonnet-4-20260514",
 messages=[
 {"role": "system", "content": "你是一个合同助手"},
 {"role": "user", "content": "请分析以下合同条款的风险点：..."}
 ],
 max_tokens=2048,
 stream=True
)

for chunk in response:
 if chunk.choices[0].delta.content:
 print(chunk.choices[0].delta.content, end="")

好处很明显：如果你之前写了一堆 GPT-5.5 的调用代码，想试试 Claude 的效果，literally 只需要改 model 参数那一行。其他的 messages 格式、stream 处理、error handling 全部通用。

我那个合同的项目就是这么干的——先用 GPT-5.5 跑通了流程，然后把 model 换成 claude-sonnet-4 对比效果，发现 Claude 在长合同（8000+ 字）的条款理解上确实更稳。

方案三：带 Tool Use 的复杂调用

如果你要做 Agent 类的应用，Claude 的 Tool Use 绕不开。这里用 Anthropic 原生 SDK 演示：

import anthropic
import json

client = anthropic.Anthropic(api_key="sk-ant-xxxxx")

tools = [
 {
 "name": "search_contract",
 "description": "在合同数据库中搜索相关条款",
 "input_schema": {
 "type": "object",
 "properties": {
 "keyword": {"type": "string", "description": "搜索关键词"},
 "contract_type": {"type": "string", "enum": ["劳动合同", "采购合同", "租赁合同"]}
 },
 "required": ["keyword"]
 }
 }
]

response = client.messages.create(
 model="claude-opus-4-20260514",
 max_tokens=4096,
 tools=tools,
 messages=[
 {"role": "user", "content": "帮我查一下我们采购合同里关于违约金的条款"}
 ]
)

# 处理 tool_use 响应
for block in response.content:
 if block.type == "tool_use":
 print(f"调用工具: {block.name}")
 print(f"参数: {json.dumps(block.input, ensure_ascii=False)}")

Opus 4.7 的 Tool Use 准确率比之前高了不少，我测了 50 个 case，只有 2 个出现了参数格式错误。不过 Opus 贵啊——input $15/M tokens，output$75/M tokens。我那个私活预算有限，最后生产环境还是用的 Sonnet 4.6。

整体调用链路

graph LR
 A[你的 Python 代码] -->|OpenAI SDK| B{选择接入方式}
 B -->|方案一| C[Anthropic 官方 API]
 B -->|方案二| D[聚合平台 API 网关]
 D --> E[Claude Sonnet 4.6]
 D --> F[Claude Opus 4.7]
 D --> G[GPT-5.5 / Gemini 3.1]
 C --> E
 C --> F

踩坑记录

坑 1：max_tokens 是必填的

跟 OpenAI 不一样，Claude API 的 max_tokens 是必填参数。不传直接报错：

anthropic.BadRequestError: Error code: 400 - {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': 'max_tokens: field required'}}

挺烦人的，每次都要手动指定。我一般默认给 2048。

坑 2：system prompt 的位置

Anthropic 原生 SDK 里，system prompt 不是放在 messages 数组里的，是单独一个参数：

# 正确写法
client.messages.create(
 model="claude-sonnet-4-20260514",
 system="你是一个合同助手", # 注意这里
 messages=[{"role": "user", "content": "..."}]
)

# 错误写法（会报错）
messages=[
 {"role": "system", "content": "你是一个合同助手"}, # 原生 SDK 不支持这样写
 {"role": "user", "content": "..."}
]

但如果你用 OpenAI 兼容格式调用（方案二），system 放 messages 里反而是对的。这个区别卡了我半小时。

坑 3：429 限流

免费 tier 的 RPM 限制很低，我跑批量测试的时候疯狂 429：

anthropic.RateLimitError: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Number of request tokens has exceeded your per-minute rate limit'}}

解决办法要么加 retry + exponential backoff，要么升级 tier。我后来用聚合平台（OpenRouter、ofox.ai 这类）绕过了这个问题，ofox.ai 是大模型云厂商官方授权服务商，走的是 Anthropic 和 AWS Bedrock 的官方通道，限流阈值比个人账户高不少。

坑 4：中文 token 计算

Claude 的 tokenizer 对中文不太友好，一个汉字大概 1.5-2 个 token。我那个合同场景，一份 5000 字的合同 input 就要吃掉大约 8000-9000 tokens。算成本的时候别按字数算，用 anthropic.count_tokens() 先预估一下。

小结

三种方案各有适用场景。从零开始写新项目并且重度依赖 Claude 特有功能（比如 200K 超长上下文、Tool Use 的 beta 特性），用 Anthropic 原生 SDK。已有 OpenAI 格式的代码想快速切换，或者需要在多个模型之间 A/B 测试，OpenAI 兼容格式省事太多了。

我也不确定 Anthropic 未来会不会把 OpenAI 兼容协议作为长期支持的方向——毕竟他们自己的 SDK 才是亲儿子。但至少 2026 年 4 月这个时间点，两种方式都能稳定跑。

对了，如果你也在做类似的合同/文档类应用，强烈建议先用 Sonnet 4.6 跑通再考虑要不要上 Opus。Sonnet 的性价比真的高太多，大部分场景够用了。