Claude API 用 Python 调用，基本流程是：准备可用的 API Key，安装 Anthropic 官方 SDK，把密钥放到环境变量，再用 Messages API 发送请求并读取响应文本。下面从本地环境配置讲起，并说明模型标识如何核对、常见报错从哪里排查。示例针对 Anthropic 官方 API；第三方平台的地址、密钥和模型名可能不同。
本文依据 Anthropic 官方 Python SDK 与入门文档整理，核查日期：2026 年 10 月 9 日。中国大陆用户在开始前应自行核对官方当前的服务地区、账号权限和可用入口；现有资料无法确认每位用户的具体开放条件，也不应把本文理解为绕过限制的方法。
Claude API 用 Python 调用，先准备什么？
你需要 Python 环境、官方 Claude Console 账号及 API Key。官方 Python SDK 文档要求 Python 3.10 或更高版本，SDK 的安装包名为 anthropic。Claude 网页版订阅与开发者 API 是不同产品；即使有付费订阅，也不能据此假定已具备 API 调用权限或 API 用量已经包含在订阅中。
建议为项目创建虚拟环境，避免把 SDK 装进系统 Python 或与其他项目的依赖混在一起。在终端进入项目目录后，可以按官方快速开始文档给出的方式创建和启用环境：
python3 -m venv .venv
source .venv/bin/activate
pip install anthropic这组启用命令适用于常见的 macOS、Linux shell。若使用 Windows 或其他终端，虚拟环境的启用命令可能不同；请按所用终端的 Python 文档操作。安装后，可运行 python --version 检查当前 Python 版本，并确认终端已启用项目环境。
API Key 怎样配置才不会写进源码？
不要把真实 API Key 直接写在 Python 文件里，也不要提交到公开代码仓库、贴进问题截图或发送给他人。将密钥作为环境变量提供给程序，Anthropic SDK 会读取名为 ANTHROPIC_API_KEY 的环境变量。官方快速开始文档以 shell 命令展示设置方式：
export ANTHROPIC_API_KEY="your-api-key-here"把示例占位文字替换为自己的密钥即可。要留意变量是在运行 Python 程序的那个终端或进程中设置的：如果换了终端、IDE 或运行环境，程序未必能读到原来的设置。以下代码会先检查变量是否存在，避免密钥为空时才在请求阶段报错。
如果密钥已经泄露，应尽快在密钥管理入口撤销或更换，并检查账号用量与权限。若项目需要持久化保存密钥，应使用受控的密钥配置方式；不要把保存密钥的文件纳入版本控制。官方 SDK 文档也提到可以配合 python-dotenv 使用本地 .env 文件，但必须确保该文件不会被提交到代码仓库。
Python 最小调用代码怎么写？
下面示例展示客户端初始化、Messages 请求和读取文本块的基本写法。官方文档所列示例使用 claude-opus-5-5；模型标识和账号可用范围可能变化，运行前应查看当前官方模型目录，并按自己的调用渠道核对，不要把它当成永久不变的型号。
import os
from anthropic import Anthropic
if not os.environ.get("ANTHROPIC_API_KEY"):
raise RuntimeError("请先设置 ANTHROPIC_API_KEY 环境变量")
client = Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=300,
messages=[
{
"role": "user",
"content": "用两句话解释什么是 Python 虚拟环境。",
}
],
)
for block in message.content:
if block.type == "text":
print(block.text)运行前把 model 中的示例标识替换为官方当前文档确认、且你的账号可以使用的模型 ID。messages 中的 role 表示消息角色，入门示例用 user 提交问题；content 是具体文本。max_tokens 用于设置本次请求允许生成的最大输出 token 数，示例设置为 300，不代表每次都会用满。
保存为 quickstart.py 后，在已安装 SDK 且能读取环境变量的同一终端运行 python quickstart.py。若配置正确并成功收到响应，程序会输出文本内容。若模型标识不适用于当前账号，或当前调用的不是 Anthropic 官方 API，应按对应平台的文档核对，不能只靠猜模型名来修复。
响应结果为什么要按内容块读取？
client.messages.create() 返回的是结构化消息对象，不是可以直接当作普通字符串打印的文本。响应的 content 是内容块集合；官方 SDK 示例通过遍历内容块，并在 block.type == "text" 时读取 block.text。这样写比假设响应永远只有一个文本块更稳妥。如果响应含有非文本类型的块，示例会跳过它，而不是把整个响应对象误当成答案。
成功调用与程序输出也要区分：程序没有抛出异常，说明请求获得了正常响应；屏幕上显示的文本才是这次响应中被代码提取并打印的内容。需要核对本次 token 用量时，SDK 响应还提供 message.usage 属性；不要通过猜测字数推算精确 token 数。
Python 调用失败，应该先检查什么？
- 提示缺少密钥或认证失败：检查当前 Python 进程能否读取
ANTHROPIC_API_KEY，确认密钥来自正确的 API 入口且没有复制空格、截断或误用其他平台的凭证。不要把密钥粘贴到公开报错信息中。 - 模型或参数报错：先核对模型 ID 是否在当前官方模型目录中、账号是否可访问，并对照当前 Messages API 文档检查参数名称和格式。第三方兼容服务的模型别名不一定能用于 Anthropic 官方 API。
- 连接失败：确认当前网络环境能访问所配置的 API 服务，并区分网络连接错误与服务返回的 HTTP 错误。对于中国大陆的具体可用性，本文资料不足以作统一判断，应查看官方当前说明。
- 收到 429 或其他状态码：SDK 将速率限制错误作为
RateLimitError，其他非成功状态也会抛出相应 API 错误。先检查账号权限、额度或速率限制信息，再根据错误类型处理；不要通过频繁重试或盲目换模型来掩盖问题。
需要在代码里处理异常时，可以捕获官方 SDK 提供的异常类型，并只记录必要的状态信息。下面示例分别处理连接问题、速率限制和其他 API 状态错误；不要在日志中输出 API Key 或完整的敏感请求内容。
import anthropic
try:
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=300,
messages=[{"role": "user", "content": "你好"}],
)
except anthropic.APIConnectionError:
print("无法连接 API，请检查网络和服务入口。")
except anthropic.RateLimitError:
print("请求受到速率限制，请检查限制信息后再处理。")
except anthropic.APIStatusError as exc:
print(f"API 返回错误，状态码：{exc.status_code}")排查问题时，也可以记录响应的 _request_id，官方 SDK 文档说明该属性可用于定位请求。分享错误信息给支持人员前，先移除密钥、个人数据和其他敏感内容。SDK 对连接错误、429 及部分服务器错误默认会进行有限重试；若需调整重试或超时行为，应依据当前 SDK 文档设置，不建议简单地无限重试。
什么时候需要异步或流式调用？
只想验证 API 是否能返回回答，先用上面的同步示例即可，步骤更少。应用需要并发处理多个任务时，官方 SDK 还提供 AsyncAnthropic 异步客户端；希望长回答逐步显示时，可查看 SDK 的流式响应示例。两者并非第一次调用的必需项，建议先确认密钥、模型和基础请求正常，再按项目需求选择，避免把异步或流式逻辑与基础配置错误混在一起排查。
发布前需要核对哪些变化信息？
本文的 Python 版本要求、SDK 安装方式和调用结构依据 Anthropic 官方 Python SDK 与快速开始文档，核查日期为 2026 年 10 月 9 日。SDK 版本、可用模型、账号开放条件、服务地区与计费政策都可能调整；尤其是模型 ID 和服务可用性，运行前应以官方当前文档和账号页面为准。现有资料不能确认所有地区、账号或第三方平台的实际开放状态，因此本文不对这些条件作保证。