Claude API 调用教程：Python 接入 Claude API 完整示例（含流式输出与 429 重试）

Claude API 调用只需要准备三样东西：一个 API Key、一个接口地址（base_url）和一个模型 ID。这篇 Claude API 调用教程用 Python 官方 SDK 从零开始，带你发出第一条消息，再依次加上多轮对话、流式输出、Prompt 缓存和 429 重试，每段代码都可以直接复制运行。

国内开发者如果还没有 Key，可以先看《Claude API 中转怎么用？国内 Claude Code 中转站配置教程》，通过中转站获取 Key 后，本文的代码只需要改一行 base_url。

---

调用 Claude API 前的准备

1. 获取 Claude API Key

Claude API Key 有两种获取方式：

• Anthropic 官方：在 Claude Console 注册开发者账号、预充值后创建 sk-ant- 开头的 Key，需要支持地区的账号和外币信用卡。
• Claude API 中转站：以 SupaStore 为例，登录 控制台 →【令牌管理】→【添加令牌】，勾选可用的 Claude 模型并设置额度上限，复制 sk- 开头的 Key。

两种方式的详细步骤和费用差别，见《Claude API 价格是多少？2026 Claude API 收费标准与省钱指南》。

2. 安装 Claude API Python SDK

建议使用 Python 3.10 及以上版本，安装 Anthropic 官方 SDK：

pip install -U anthropic

3. 用环境变量保存 API Key

不要把 Key 写死在代码里，放进环境变量：

# macOS / Linux
export ANTHROPIC_API_KEY="sk-your-api-key"

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-your-api-key"

SDK 会自动读取 ANTHROPIC_API_KEY，代码里不用再传 Key。

---

第一个 Claude API 调用示例

直连 Anthropic 官方

import anthropic

client = anthropic.Anthropic()  # 自动读取 ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "用三句话解释什么是 Prompt 缓存"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(response.usage)

response.content 是一个内容块列表，先判断 type == "text" 再取文字；response.usage 会返回本次请求的输入、输出和缓存 Token 数，用它就能算出这次 Claude API 调用花了多少钱。usage 各字段的含义见《AI Token 是什么？》。

通过中转站调用 Claude API

国内网络直连官方接口容易超时，改用中转站时只需要多传一个 base_url：

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.supastore.cc/v1",  # 中转站接口地址，需带 /v1
)

SupaStore 的接口地址统一为 https://api.supastore.cc/v1，/v1 不能省略，末尾也不要多加 /（各类工具的填写规则见《Base URL 是什么？API Base URL 怎么填》）。之后的所有代码与直连官方完全一样，只是请求改为发往中转站。

用 cURL 快速验证 Key

在写代码之前，也可以先用 cURL 确认 Key 和模型可用：

curl https://api.supastore.cc/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

返回 JSON 中有 content 和 usage 字段，就说明 Claude API 调用成功。

---

Claude API 常用参数说明

参数	作用	建议
model	模型 ID	日常用 claude-sonnet-5-5，难题用 claude-opus-5-5，高并发简单任务用 claude-haiku-5-5
max_tokens	单次回复的输出上限	不要设得太小，否则回答会被截断；非流式请求建议 16000 左右
messages	对话消息列表	user 和 assistant 交替排列
system	系统提示词	放角色设定和固定规则，适合配合 Prompt 缓存
output_config	输出配置，其中 effort 控制思考强度	简单任务设 {"effort": "low"} 可以减少思考 Token

注意，新一代 Claude 模型的思考按输出 Token 计费；Opus 5.5 的 effort 默认是 medium。各模型的 Claude API 价格见模型广场和《Claude API 价格是多少？》。

---

多轮对话：让 Claude 记住上下文

Claude API 本身不保存会话，多轮对话需要你把历史消息一起发过去：

history = []

def chat(user_text: str) -> str:
    history.append({"role": "user", "content": user_text})
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=16000,
        system="你是一名耐心的 Python 讲师，回答尽量简短并附代码。",
        messages=history,
    )
    history.append({"role": "assistant", "content": response.content})
    return "".join(b.text for b in response.content if b.type == "text")

print(chat("列表推导式怎么写？"))
print(chat("再给一个带条件过滤的例子"))

把 response.content 原样追加到历史里，而不是只存文字，这样思考块、工具调用等内容也能完整保留。对话越长，每次请求的输入 Token 越多，这也是 Claude Code 这类工具费 Token 的原因，详见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。

---

Claude API 流式输出（Streaming）

聊天界面需要边生成边显示，长回答也容易触发 HTTP 超时，这两种情况都应该用流式输出：

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=64000,
    messages=[{"role": "user", "content": "写一篇 500 字的 Python 入门指南"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()

print()
print(final.usage)

stream.text_stream 逐段返回文字，get_final_message() 在结束后拿到完整消息和 usage。max_tokens 很大时，SDK 会要求使用流式请求，以免连接超时。

---

用 Prompt 缓存降低 Claude API 调用成本

如果每次请求都带着相同的长系统提示词或文档，加上 cache_control 就能让重复部分按缓存价计费：

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    cache_control={"type": "ephemeral"},  # 自动缓存最后一个可缓存块
    system=long_product_manual,           # 很长且固定的内容
    messages=[{"role": "user", "content": "退货政策是什么？"}],
)

print(response.usage.cache_creation_input_tokens)  # 写入缓存的 Token
print(response.usage.cache_read_input_tokens)      # 命中缓存的 Token

缓存写入比普通输入贵 25%，命中后 Sonnet 5.5 和 Opus 5.5 只收输入价的 5%，默认有效期 5 分钟。要注意三点：

1. 缓存按前缀匹配，固定内容放最前面，每次变化的问题放最后；
2. 系统提示词里不要放当前时间、请求 ID 这类每次都变的内容；
3. 前缀太短不会被缓存，连续几次请求 cache_read_input_tokens 都是 0，就要检查前缀是否被改动。

手动断点、1 小时 TTL 和缓存命中率排查的完整方法，见《Claude Prompt 缓存怎么用？Prompt Caching 教程》。

---

Claude API 429 限速与重试

429 是什么意思

429（rate_limit_error）表示请求数或 Token 数超过了 Key 或组织的速率限制。响应头里的 retry-after 会告诉你需要等待多少秒。

SDK 自带自动重试

Anthropic Python SDK 默认会对 408、409、429、5xx 和连接错误自动重试 2 次，并做退避等待。你可以调整次数和超时：

client = anthropic.Anthropic(
    max_retries=5,   # 默认 2
    timeout=600.0,   # 单位：秒，默认 10 分钟
)

按错误类型分别处理

重试用完仍然失败时，按错误类型处理，不要用一个宽泛的异常吞掉所有错误：

try:
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=16000,
        messages=[{"role": "user", "content": "你好"}],
    )
except anthropic.RateLimitError as e:
    wait = e.response.headers.get("retry-after", "?")
    print(f"触发限速，建议 {wait} 秒后重试")
except anthropic.APIConnectionError:
    print("网络连接失败，检查 base_url 和网络")
except anthropic.APIStatusError as e:
    print(f"请求失败：{e.status_code} {e.message}")

批量任务频繁 429 时，优先降低并发；不需要实时返回的任务改用 Batch API，速率限制独立且费用减半。

---

Claude API 调用常见报错

状态码	常见原因	处理方法
400	参数错误、模型 ID 拼写错误，或 Key 未勾选该模型	检查请求体，在模型广场核对模型 ID
401	Key 错误、过期，或复制时多了空格	重新复制 Key，检查环境变量是否生效
402 / 余额不足	账户余额或 Key 额度用完	充值或调高 Key 的额度上限
404	base_url 写错，比如漏写了 /v1 或末尾多了 /	严格填写 https://api.supastore.cc/v1
429	触发速率限制	等待 retry-after 秒后重试，降低并发
529	上游服务过载	稍后重试，与你的额度无关

每个错误码的详细原因和新模型特有的 400 报错，见《Claude API 报错怎么办？2026 Claude API 错误码大全》；更多排查步骤见常见问题排查。如果你的项目已经在用 OpenAI SDK，也可以用同一个 Key 通过 OpenAI 兼容接口调用 Claude，见《如何通过单 API Key 统一接入 40+ 主流大模型》。

---

常见问题 (FAQ)

Q: Claude API 调用需要什么？

答： 需要一个 Claude API Key、一个接口地址和一个模型 ID；用 Python 调用时安装 anthropic SDK，把 Key 放进 ANTHROPIC_API_KEY 环境变量，再调用 client.messages.create 即可。

Q: Claude API 有免费额度吗？

答： Claude API 没有长期免费层，新注册的开发者账号可能获得少量测试额度，用完后需要预充值；claude.ai 的 Pro、Max 订阅与 API 分开计费，不能抵扣 API 费用。

Q: Claude API 可以用 OpenAI SDK 调用吗？

答： 可以通过 OpenAI 兼容接口调用，但工具调用、思考、Prompt 缓存等 Claude 特有功能在原生 Messages 接口上支持最完整，新项目建议直接使用 anthropic SDK。

Q: Python 调用 Claude API 报 404 怎么办？

答： 大多是 base_url 写错，使用 SupaStore 时 base_url 应严格填写 https://api.supastore.cc/v1，不能漏掉 /v1，末尾也不要多加斜杠。

Q: Claude API 调用一次多少钱？

答： 费用等于输入、缓存和输出 Token 分别乘以对应单价之和，每次响应的 usage 字段都会返回这几项 Token 数，代入价格表即可算出。