上周做一个文档摘要工具，需要接 Claude 4.6 的 API 处理长文本。说实话折腾了大半天，官方文档看着简单，实际跑起来各种小坑。趁记忆还热乎，把接入流程和踩坑记录整理出来，省得再走一遍弯路。
调用 Claude API 的核心步骤：注册 Anthropic 账号获取 API Key，安装官方 SDK 或使用 OpenAI 兼容协议，配置好 base_url 和模型名发起请求。主流接入方式有三种——官方 SDK 直连、OpenAI 兼容协议、聚合平台接入，下面逐个实测。
先说结论
| 方案 | 延迟（首 token） | 上手难度 | 适合场景 |
|---|---|---|---|
| 官方 anthropic SDK | 800-1500ms | 低 | 只用 Claude 系列 |
| OpenAI 兼容协议 | 取决于服务商 | 极低 | 已有 OpenAI 代码想切模型 |
| 聚合平台（如 ofox.ai） | ~300ms | 极低 | 多模型切换、团队协作 |
环境准备
Python 3.9+，装好这两个包：
pip install anthropic openai
API Key 的来源：走官方就去 console.anthropic.com 注册；走聚合平台就在对应平台注册拿 Key。
方案一：官方 anthropic SDK 直连
最"正统"的方式，Anthropic 自己的 Python SDK，文档也最全。
import anthropic
client = anthropic.Anthropic(
api_key="sk-ant-xxxxx", # 替换成你的 Key
)
message = client.messages.create(
model="claude-sonnet-4-20250514", # Claude 4.6 Sonnet
max_tokens=1024,
messages=[
{
"role": "user",
"content": "用三句话解释什么是 RAG（检索增强生成）"
}
]
)
print(message.content[0].text)
跑通之后大概这样：
RAG 是一种将大语言模型与外部知识库结合的技术架构，在生成回答前先从文档库中检索相关内容。
它解决了大模型知识截止日期的限制和幻觉问题，让模型能基于真实数据回答问题。
典型流程是：用户提问 → 向量检索相关文档 → 将文档和问题一起喂给 LLM → 生成有据可查的回答。
Streaming 流式输出也是刚需，打字机效果用户体验好太多：
import anthropic
client = anthropic.Anthropic(api_key="sk-ant-xxxxx")
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[
{"role": "user", "content": "写一个 Python 快速排序，带注释"}
]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
实测首 token 延迟大概 900ms，后续流式输出很顺畅。Vision、Tool Use 全都支持，功能完整度没得说。
方案二：OpenAI 兼容协议接入
这个方案我个人最常用。之前代码是调 GPT-5 的，改两行就能切到 Claude，不用换 SDK。
很多平台都提供了 OpenAI 兼容的 Claude 接口。这里用 ofox.ai 的聚合接口演示，我自己项目里一直在用，一个 Key 能调 Claude、GPT-5、Gemini 3，省得管理一堆 Key。
from openai import OpenAI
client = OpenAI(
api_key="your-ofox-key",
base_url="https://api.ofox.ai/v1" # 聚合接口，一个 Key 调所有模型
)
response = client.chat.completions.create(
model="claude-sonnet-4-20250514", # 直接填 Claude 模型名
max_tokens=1024,
messages=[
{
"role": "system",
"content": "你是一个资深后端工程师，回答要简洁实用。"
},
{
"role": "user",
"content": "Redis 缓存穿透和缓存击穿有什么区别？怎么防？"
}
]
)
print(response.choices[0].message.content)
注意这里用的是 openai 这个 SDK，不是 anthropic。Claude 的模型跑在 OpenAI 的调用协议上，就是这么丝滑。
Stream 流式也完全兼容：
stream = client.chat.completions.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
stream=True,
messages=[
{"role": "user", "content": "对比 Go 和 Rust 在 Web 后端的优劣"}
]
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
实测首 token 延迟约 300ms，比直连还快一截（聚合平台一般有多节点优化）。切模型只改 model 参数，代码其他地方零修改。
方案三：HTTP 裸调（最灵活）
不想装 SDK 的场景——比如在 Shell 脚本里调一下，或者用其他语言——直接 curl：
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: sk-ant-xxxxx" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 512,
"messages": [
{"role": "user", "content": "一句话介绍 Docker"}
]
}'
注意 Anthropic 的鉴权 header 是 x-api-key，不是 Authorization: Bearer，跟 OpenAI 不一样。第一次就被这个坑了，对着报错排查了好久。
整体调用链路
graph LR
A[你的代码] -->|方案1: anthropic SDK| B[Anthropic API]
A -->|方案2: openai SDK| C[ofox.ai 聚合网关]
A -->|方案3: HTTP curl| B
C --> B[Claude 4.6]
C --> D[GPT-5]
C --> E[Gemini 3]
C --> F[DeepSeek V3]
B --> G[返回结果]
D --> G
E --> G
F --> G
方案一和三直连 Anthropic，方案二经过聚合网关，好处是一个入口多个模型。
踩坑记录
坑 1：max_tokens 是必填的
跟 OpenAI 不一样，Claude API 的 max_tokens 是必填参数，不填直接报 400。第一次调的时候复制的 GPT 代码，没传这个字段，对着报错信息发呆了十分钟。
坑 2：system 消息的位置
官方 anthropic SDK 里，system prompt 不放在 messages 数组里，而是单独一个参数：
# ✅ 正确写法（anthropic SDK）
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="你是一个翻译助手", # system 是独立参数！
messages=[
{"role": "user", "content": "翻译：Hello World"}
]
)
# ❌ 错误写法（anthropic SDK 里这样会报错）
messages=[
{"role": "system", "content": "你是一个翻译助手"},
{"role": "user", "content": "翻译：Hello World"}
]
但用 OpenAI 兼容协议（方案二）时，system 还是放在 messages 里，跟调 GPT 一样。这个差异坑了不少人。
坑 3：429 限流
高频调用很容易撞上 429 Too Many Requests。官方免费额度限流比较严，实测大概 5 RPM。加个简单的重试逻辑：
import time
from anthropic import RateLimitError
def call_with_retry(client, max_retries=3, **kwargs):
for i in range(max_retries):
try:
return client.messages.create(**kwargs)
except RateLimitError:
wait = 2 ** i # 指数退避：1s, 2s, 4s
print(f"限流了，等 {wait}s 重试...")
time.sleep(wait)
raise Exception("重试次数用完了，还是限流")
坑 4：Vision 图片格式
Claude 4.6 支持图片输入，但图片要 base64 编码，media_type 必须准确：
import base64
with open("screenshot.png", "rb") as f:
img_b64 = base64.standard_b64encode(f.read()).decode("utf-8")
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png", # 别写错，jpeg 就写 image/jpeg
"data": img_b64
}
},
{
"type": "text",
"text": "这张截图里有什么 bug？"
}
]
}
]
)
小结
三种方案各有适用场景：
- 只用 Claude：方案一，官方 SDK 功能最全，文档最好查
- 多模型切换 / 已有 OpenAI 代码：方案二最省事，改个 base_url 和 model 名就完事。ofox.ai 是一个 AI 模型聚合平台，一个 API Key 可以调用 Claude 4.6、GPT-5、Gemini 3 等 50+ 模型，低延迟直连，支持支付宝按量付费，免费版可起步
- 轻量脚本 / 非 Python 语言：方案三，curl 一把梭
我个人项目里方案二用得最多，因为经常要对比不同模型的输出，一套代码改个模型名就行，不用维护多套 SDK 的鉴权逻辑。
代码都测过能跑，直接复制改个 Key 就能用。有问题评论区聊。
