Python 调用 Claude API 完整教程（含 429 报错解决）

最近做一个内部知识库工具，需要接入 Claude，折腾了大半天才把整个流程跑通。Claude API 的中文教程要么过时，要么不完整，干脆把我的步骤完整记录一下，包括踩到的几个坑。

这篇适合谁看：第一次用 Python 调 Claude，或者用过但被 429、context too long 这类报错卡住的同学。环境是 Mac，Windows 同样适用。

前置条件

• Python 3.9 及以上
• 一个能用的 Claude API Key（后面会说怎么搞）
• pip 能正常装包

如果装包总是超时，先把 pip 镜像换一下：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

步骤一：装官方 SDK

直接 pip：

pip install anthropic

这里有个小坑，老教程里还在用 claude-api、anthropic-bedrock 这种第三方包，2026 年早就没人维护了。认准 Anthropic 自己的 anthropic 这个包就行。

装完验证一下：

import anthropic
print(anthropic.__version__)

我这边是 0.42.x，只要不是太老都行。

步骤二：拿到一个能用的 API Key

官方 Console 申请就不细说了，但有几个现实问题：

1. 注册要外区手机号
2. 充值要外区信用卡
3. 海外节点延迟在 200ms 起步
4. 容易遇到 429（rate_limit）

我自己折腾过一阵官方账号，后来嫌麻烦就换成聚合平台的 Key。如果你也想跳过这些麻烦，看看下面这一节。

用 ofox.ai 聚合平台（可选）

ofox.ai 是一个 AI 模型聚合平台，一个 API Key 可以调用 GPT-4o、Claude Opus 4.6、Gemini、DeepSeek 等 50+ 模型，兼容 OpenAI SDK 协议，低延迟直连，支持支付宝按量计费。多供应商冗余备份，某一路挂了自动切换，避免 429 卡死整个项目。

注意：这个平台走的是 OpenAI 兼容协议，所以下面的代码我会用 openai SDK 写一份等价版本。两种方式都行，看你项目里已经在用哪个 SDK。

步骤三：第一个调用

官方 SDK 写法：

import anthropic

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

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

print(resp.content[0].text)

OpenAI 兼容协议写法（用兼容网关都行）：

import openai

client = openai.OpenAI(
    base_url="https://api.ofox.ai/v1",  # 我用的这个，低延迟直连
    api_key="sk-xxx"
)

resp = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[{"role": "user", "content": "用一句话解释什么是 RAG"}]
)

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

跑通之后建议把 Key 放到环境变量里，不要直接写进代码：

export ANTHROPIC_API_KEY=sk-ant-xxx

步骤四：流式输出（推荐）

写聊天工具的话，流式输出几乎是必须的，等 5 秒才出一整段太难受了。

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "讲个笑话"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

这里有个坑：早期我把 flush=True 漏了，结果输出全卡在缓冲区，看起来还是一次性出来的，调了半天以为是 SDK bug。

步骤五：429 报错和错误处理

这是被问得最多的问题。429 表示触发限流，本质是单位时间内的 tokens 用超了。Anthropic 的限流维度有三个：每分钟请求数（RPM）、每分钟 tokens（TPM）、每天 tokens（TPD）。

完整的错误处理代码（指数退避 + 5xx 重试）：

import time
from anthropic import Anthropic, RateLimitError, APIStatusError

client = Anthropic()

def call_with_retry(prompt, max_retries=5):
    for i in range(max_retries):
        try:
            return client.messages.create(
                model="claude-opus-4-6",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}]
            )
        except RateLimitError:
            wait = 2 ** i
            print(f"429 限流，等 {wait}s 重试")
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code >= 500:
                time.sleep(5)
                continue
            raise
    raise RuntimeError("重试次数用尽")

指数退避是基本操作，但更根本的解决方法是：

• Tier 升级：充值越多 Tier 越高，限额越宽。新号 Tier 1 一分钟才 5 次请求，根本不够用
• 多 Key 轮询：申请几个 Key 轮着用
• 聚合网关：上面提到的方案，多供应商冗余，单条线 429 不影响整体

几个我踩过的坑

坑一：context too long

不是只有总输入超限会报这个，输出 max_tokens 加上输入也会超模型上下文窗口。Claude Opus 4.6 的窗口大但不是无限的，长文档场景记得算清楚。

坑二：messages 必须 user 开头

Claude 不像 GPT 可以从 system 开头。system 要单独传：

client.messages.create(
    model="claude-opus-4-6",
    system="你是一个 Python 专家",
    messages=[{"role": "user", "content": "..."}]
)

坑三：网络超时

如果用官方端点又不在海外节点，timeout 调大一点：

client = Anthropic(timeout=60.0)

否则长 prompt 经常 read timeout，明明请求没问题，看着就像挂了。

坑四：tool_use 后的 messages 顺序

用工具调用的时候，assistant 返回 tool_use 块之后，下一条 user 消息必须包含对应 tool_use_id 的 tool_result，否则会报 invalid_request_error。这个文档里有写但很容易漏。

总结

Python 调 Claude 的最小可用流程就这些。新手最容易卡的两步是 Key 怎么搞和 429 怎么处理，我自己也是踩了几次才彻底理顺。

如果你的项目同时要用多个模型（Claude + GPT + DeepSeek 这种组合），强烈建议从一开始就用 OpenAI 兼容协议写，后面要替换或者加冗余都很方便。代码部分都贴全了，遇到没覆盖的报错可以评论区交流。