Python调用Claude API实战：三种方案对比与避坑指南

半杯拿铁

发布时间：2026-10-12| 3人浏览过

原创

本文实测Python调用Claude API的三种主流方案：官方SDK、OpenAI兼容接口及HTTP请求。详细解析了API Key格式、max_tokens必填项、图片传参及429限流处理等关键细节，提供完整代码示例与避坑建议，帮助开发者快速集成Claude模型。

上个月协助朋友的创业团队搭建客服摘要系统，底层模型指定使用 Claude Sonnet 4.6。本以为调用接口并不复杂，但从注册账号到成功发出首个请求，实际耗时大半天。主要难点在于 Anthropic 官方 SDK 与 OpenAI 兼容接口并存，且相关文档分散，导致踩坑较多。本文将整理并分享三种实际跑通的调用方式，代码可直接复制使用。

目前调用 Claude API 主要有三种方式：Anthropic 官方 Python SDK、OpenAI 兼容接口，以及通过 HTTP 直接发起请求。其中，官方 SDK 使用最简便；OpenAI 兼容接口便于从 GPT 项目迁移；HTTP 方式则提供了最高的灵活性。下文将逐一详细介绍。

先说结论

方案	上手难度	适用场景	是否支持 Streaming
Anthropic 官方 SDK	最简单	纯用 Claude 的项目	✅
OpenAI 兼容接口	简单	从 GPT 迁移、多模型切换	✅
HTTP 直接请求	稍麻烦	不想装 SDK、Serverless 场景	✅

在日常开发中，我更倾向于使用方案二。只需修改 model 参数，即可在 Claude 和 GPT-5.5 之间自由切换，无需维护两套独立的代码逻辑。

环境准备

需要 Python 3.9 或更高版本，并安装以下两个依赖包：

pip install anthropic openai

关于 API Key 的获取，需前往 Anthropic Console 注册账号并绑定支付方式，随后在 Settings → API Keys 页面生成密钥。这里有一个关键细节：Anthropic 的 Key 以 sk-ant-api03- 开头，请注意与 OpenAI 的 Key 格式区分，避免混淆。

方案一：Anthropic 官方 SDK

这是最标准的调用方式，代码简洁明了：

import anthropic

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

message = client.messages.create(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[
 {"role": "user", "content": "用 Python 写一个快速排序，要有注释"}
 ]
)

print(message.content[0].text)

运行过程通常很顺利。但我初次调用时遭遇了一个报错：

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

经过排查，发现原因是粘贴 Key 时多输入了一个空格。这类低级错误往往最耗费排查时间。

以下是 Streaming 版本的代码，开发聊天界面时通常会用到：

with client.messages.stream(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[{"role": "user", "content": "解释一下 RLHF 是什么"}]
) as stream:
 for text in stream.text_stream:
 print(text, end="", flush=True)

关于响应延迟，我在 4 月 22 日晚进行了多次测试，首 token 到达时间大约在 800ms 至 1.2s 之间，波动较为明显。

方案二：OpenAI 兼容接口（推荐）

这是我使用频率最高的方案。原因很简单：我手头同时有 Claude 和 GPT-5.5 的项目，使用 OpenAI SDK 进行统一调用，切换模型仅需修改一行代码。

from openai import OpenAI

client = OpenAI(
 api_key="sk-ant-api03-xxxxx",
 base_url="https://api.ofox.ai/v1"
)

response = client.chat.completions.create(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[
 {"role": "system", "content": "你是一个资深 Python 开发者"},
 {"role": "user", "content": "帮我写一个 Redis 缓存装饰器"}
 ]
)

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

请注意，此处 base_url 指向的是聚合 API 网关。常见的聚合平台包括 OpenRouter、Together AI 和 ofox.ai。其中 OpenRouter 收取 5.5% 的手续费，而 ofox.ai 则按官方价格加价 0%，用户可根据自身需求选择。

该方案的优势在于：此前编写的 OpenAI 调用代码，只需将 model 替换为 Claude 的模型名即可运行。此外，system 消息也能正常支持（Anthropic 原生 SDK 中 system 消息需作为单独参数传递，不包含在 messages 列表中）。

Streaming 版本代码如下：

stream = client.chat.completions.create(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[{"role": "user", "content": "写一篇 500 字的技术博客大纲"}],
 stream=True
)

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

方案三：HTTP 直接请求

在某些场景下，例如 Cloudflare Workers 或极简的 Lambda 函数中，可能不希望安装 SDK。此时可直接使用 requests 库发送请求：

import requests
import json

url = "https://api.anthropic.com/v1/messages"
headers = {
 "x-api-key": "sk-ant-api03-xxxxx",
 "anthropic-version": "2023-06-01",
 "content-type": "application/json"
}

payload = {
 "model": "claude-sonnet-4-6-20260414",
 "max_tokens": 1024,
 "messages": [
 {"role": "user", "content": "什么是向量数据库？简单解释"}
 ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
result = response.json()
print(result["content"][0]["text"])

这里有一个易错点：anthropic-version 这个 Header 是必填项，若不传递会返回 400 错误。版本号并非随意填写，必须使用 Anthropic 文档中列出的有效版本。我第一次随意填写了 2026-01-01，直接返回了错误信息：

{"type":"error","error":{"type":"invalid_request_error","message":"Invalid API version: 2026-01-01. Valid versions: 2023-06-01, 2024-10-22, ..."}}

因此，建议直接使用 2023-06-01，虽然看起来较旧，但一直可用。

整体调用链路

graph LR
 A[你的 Python 代码] --> B{选择调用方式}
 B -->|方案一| C[Anthropic SDK]
 B -->|方案二| D[OpenAI SDK + 聚合网关]
 B -->|方案三| E[HTTP requests]
 C --> F[Anthropic API]
 D --> G[聚合网关 API]
 G --> F
 E --> F
 F --> H[Claude Sonnet 4.6 / Opus 4.7]

踩坑记录

1. max_tokens 是必填参数

与 OpenAI 不同，Claude API 的 max_tokens 若不填写会直接报错，不会提供默认值。我将 GPT 迁移过来的代码全部测试了一遍，不得不逐个添加该参数，过程较为繁琐。

2. 图片传参格式

若需使用 Claude 的视觉能力，图片需进行 base64 编码后放入 messages 中：

message = client.messages.create(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[{
 "role": "user",
 "content": [
 {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": base64_string}},
 {"type": "text", "text": "这张图里画的是什么？"}
 ]
 }]
)

注意 content 从字符串类型变成了列表类型，初次编写时容易遗漏。

3. 429 限流

在高并发调用时，常会遇到 429 错误。Anthropic 的限流策略按 Tier 分级，新注册账号通常为 Tier 1，每分钟仅允许 50 次请求。我在运行批量摘要任务时直接触发了限流：

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

解决办法要么提升 Tier（充值金额越高，Tier 越高，这很现实），要么添加重试逻辑。我使用了 tenacity 库实现：

from tenacity import retry, wait_exponential, stop_after_attempt

@retry(wait=wait_exponential(min=1, max=60), stop=stop_after_attempt(5))
def call_claude(prompt):
 return client.messages.create(
 model="claude-sonnet-4-6-20260414",
 max_tokens=1024,
 messages=[{"role": "user", "content": prompt}]
 )

4. system prompt 长度问题

Anthropic 文档指出 system prompt 支持较长内容，但我实测发现超过 4000 token 后，响应质量会有所下降，不确定是否为个例。目前我的做法是将 system prompt 控制在 2000 token 以内，复杂上下文则放入 user message 中。这是否为最佳实践尚不确定，欢迎有经验的用户在评论区交流。