把 Claude 接进自己的程序，最直接的入口是 Anthropic 官方 SDK 和它背后的 Messages API。它不依赖任何框架，十几行 Python 就能完成第一次模型调用；后面的工具调用、思考模式、提示缓存等高级能力，全部建立在这同一套调用之上。这也是本系列用 12 篇篇幅从零讲到中级的原因——地基打正了，后面每一篇都只是在这条主线上加东西。
本文是《Anthropic SDK 从入门到实战》第 1 篇，只做三件事：装好环境、跑通第一次 Messages API 调用、建立三个后面反复要用到的心智模型。全文按"系列地图 → 心智差异 → 环境搭建 → 首次调用 → 响应结构 → 报错速查 → 总结"组织。
1、系列地图：从零到中级
先给全景。本系列共 12 篇：前 3 篇打基础，中间 6 篇讲核心能力，最后 3 篇面向生产。
- 第 1 篇：环境与首次调用（本篇）
- 第 2 篇：流式输出，逐字呈现响应
- 第 3 篇：结构化输出与 JSON 校验
- 第 4 篇：工具调用（Function Calling）
- 第 5 篇：多轮对话与上下文管理
- 第 6 篇：思考模式与推理深度调节
- 第 7 篇：提示缓存，输入成本最多省九成
- 第 8 篇：Batch 批处理，异步任务半价
- 第 9 篇：模型选型与成本核算
- 第 10 篇：MCP（Model Context Protocol）接入
- 第 11 篇：错误处理与可观测性
- 第 12 篇：综合实战项目
每篇独立可读，但主线只有一条：client.messages.create() 这一个调用，会随着系列推进越长越丰富。本篇先把它最短的形态跑通。
为什么用 Python 版 SDK 讲解？它是上手人数最多的版本，概念与 TypeScript、Java 等其他语言实现一一对应，学明白之后迁移只是换语法。系列每一篇都带可直接运行的示例，建议照着敲一遍再往下读——本篇的示例十行出头，跑通只需要几分钟。
2、与 OpenAI 的两处差异
不少读者用过 OpenAI SDK，这既是优势也是坑——两家在关键参数的形状上不同，照搬旧代码会直接报错。两个 SDK 首次调用的差异对比如下：
| 对比项 | OpenAI SDK | Anthropic SDK |
|---|---|---|
| 系统提示 | messages 里 role 为 system 的一条 |
顶层独立参数 system |
| 输出上限 | max_tokens 可省略，有默认值 |
max_tokens 必填，缺失报 400 |
| 取回复文本 | choices[0].message.content |
遍历 content 块数组 |
两处设计差异值得多说一句。Anthropic 把系统提示视为对话开始之前的配置，而不是对话的一部分——所以 system 独立于 messages 存在，消息数组里不会出现 system 角色（中途插入系统指令是另一个能力，第 3 篇再讲）。max_tokens 必填则是把成本控制权显式交给你：模型这次最多生成多少 token，由每次调用自己声明，不写就不执行。
从 OpenAI 代码迁移，三步就能完成首次调用的改造：把 system 那条消息从数组里搬出来，变成顶层参数；给每次调用补上 max_tokens；把取文本的写法从下标取字符串，换成遍历块数组。三步分别对应表里的三行，后面几节会逐一落地。
第三行差异（块数组）是结构性的，放在第 5 节展开——它决定了后面工具调用与思考模式长什么样。
3、环境搭建与密钥管理
SDK 要求 Python 3.10 及以上（1.0 版本起收紧，2.x 延续）。建议每个项目一个独立虚拟环境，命令如下：
python -m venv .venv
source .venv/bin/activate # macOS 与 Linux
.venv\Scripts\activate # Windows PowerShell
pip install anthropic python-dotenv
解读：前三行创建并激活 venv，最后一行安装 SDK 与读取 .env 用的 python-dotenv。截至 2026 年 10 月，anthropic 包在 PyPI 的最新版本是 2.3.0，源码仓库在 GitHub 维护——2.0 是配合 2026-10-21 API 版本的大版本升级，新项目直接装最新版即可，pip show anthropic 可随时确认本地版本。
密钥在 Anthropic 控制台的 API keys 页创建，是一串 sk-ant- 开头的字符。把它放进项目根目录的 .env 文件：
ANTHROPIC_API_KEY=sk-ant-xxxx
解读：SDK 初始化时会自动读取名为 ANTHROPIC_API_KEY 的环境变量，代码里不出现密钥本身。.env 必须加进 .gitignore：密钥一旦推进公开仓库，任何看到的人都能消耗你的额度；发现泄露，第一件事是去控制台吊销重发。
提醒：不要把密钥写死在代码里，也不要用
api_key="..."显式传参。环境变量是唯一推荐姿势，团队协作时每人一份自己的 Key。
4、第一次调用 Messages API
调用前先选模型。当前一代 Claude 全系提供 100 万 token 上下文窗口与 128K 最大输出，档位与定价如下（2026 年 10 月官方标准价，输入价按每百万 token 计）：
| 档位 | 模型 ID | 定位 | 输入价 |
|---|---|---|---|
| 旗舰 | claude-fable-5-1 |
能力天花板，最难的任务 | 10 美元 |
| 旗舰 | claude-opus-5-5 |
主力旗舰，智能体与复杂编码 | 4 美元 |
| 均衡 | claude-sonnet-5-5 |
日常主力，速度与质量平衡 | 2 美元 |
| 轻量 | claude-haiku-5-5 |
最快最便宜，分类与抽取 | 0.1 美元 |
学习阶段推荐 claude-sonnet-5-5：能力足够、单价低、输出稳定；档位与价格以官方模型概览为准。表中的 ID 是完整可用的模型字符串，不需要也不应该再加日期后缀。最小可运行示例如下：
import anthropic
from dotenv import load_dotenv
load_dotenv() # 把 .env 读进环境变量
client = anthropic.Anthropic() # 自动使用 ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024, # 必填：本次回复的生成上限
system="你是一位耐心的编程老师，回答不超过三句话。",
messages=[
{"role": "user", "content": "用一句话解释什么是 API"}
],
)
print(response.content[0].text) # 第一个文本块的内容
print(response.stop_reason) # 模型为什么停止生成
print(response.usage.output_tokens) # 本次消耗的输出 token
逐行拆解。Anthropic() 无参构造，凭环境变量完成认证；create() 是整个系列的主角，model 与 max_tokens 是每次调用都绕不开的两个参数；system 写人设与规则，它的效力高于任何一条用户消息，在这里定基调，比在每条消息里重复要求干净得多；messages 是对话数组，首条必须是 user，此处的 content 是纯字符串，第 5 节会看到它的块形态。完整参数清单见官方 Messages API 参考。
运行输出如下：
API 是应用程序之间约定的通信接口：一方按规则发起请求，另一方返回
数据，就像餐厅服务员在顾客与后厨之间传菜。
end_turn
47
解读：end_turn 表示模型自然说完，这是 stop_reason 最常见的值；如果是 max_tokens，说明回复被上限截断，句子可能断在半截——练习里会专门制造一次。此外还有 tool_use（模型要调用工具，第 4 篇的主角）与 refusal（安全原因拒答）等取值，写生产代码时应先判断 stop_reason 再消费内容。另外，create() 默认等到全部生成完才返回，长回复会干等一段时间；逐字拿结果的流式版本，是第 2 篇的内容。usage 中另有 input_tokens，计费按输入输出分别结算，第 9 篇细讲。
5、心智模型：回复是块数组
初学者最不适应的一点：response.content 不是字符串，是块数组——每个元素带 type 字段，text 块只是其中一种。本篇只需要认识它，但要理解为什么这样设计。
把上一节的响应对象序列化成 JSON，整体结构如下：
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5-5",
"content": [
{
"type": "text",
"text": "API 是应用程序之间约定的通信接口……"
}
],
"stop_reason": "end_turn",
"usage": { "input_tokens": 28, "output_tokens": 47 }
}
解读：顶层是一层元信息，id 是这次调用的唯一编号（向 Anthropic 报告问题时附上它），role 恒为 assistant；真正的内容在 content 数组里，本例只有一个 text 块。所谓块数组，指的就是这个 content 字段的形态；SDK 已把它解析成 Python 对象，属性访问等价于字典取键。
一次回复可能同时携带多种内容：模型先思考再作答，思考过程是 thinking 块；决定调用外部工具时，调用请求是 tool_use 块；工具执行结果作为 tool_result 块回到下一轮输入。内容块家族全景如下：
解读：前两类出现在模型的回复里；后三类出现在输入侧——image 让消息携带图片，tool_result 由你的代码构造后放入下一条消息。块数组就是为这些形态预留的统一容器：今天取文本，第 4、5 篇取工具调用与思考，数据结构不用推倒重来。这也解释了第 2 节对比表的第三行：OpenAI 把文本放在一层对象的属性里，Anthropic 把它放进数组的一个块——多写一行遍历代码，换来的是后面所有能力的扩展空间。
因此取文本的健壮写法是遍历判型，而不是假设第 0 个元素一定是文本：
for block in response.content:
if block.type == "text":
print(block.text)
解读：一次回复可能出现多个 text 块，遍历能一个不漏地取出。"先看 type 再取字段"这个习惯，从第一篇就值得养成。
6、常见报错速查
第一次跑通之前，三种报错几乎人人会遇到。速查如下：
| 报错 | 原因 | 解决 |
|---|---|---|
401 authentication_error |
密钥未设置或已失效 | 核对 ANTHROPIC_API_KEY 与 load_dotenv 顺序 |
400 Field required |
漏传 max_tokens 等必填参数 |
create() 里补齐参数 |
404 not_found_error |
模型 ID 拼写错误 | 对照第 4 节表格使用完整 ID |
读报错有个固定顺序：先看 HTTP 状态码定位类别（401 认证、400 参数、404 资源），再看返回体里的 type 字段确认具体原因，与表中对号入座即可。
另有一类新坑值得单独提醒：2026-10-21 API 版本起，temperature、top_p、top_k 等采样参数已被移除，请求里携带会直接返回 400。网上大量旧教程仍写着 temperature=0.7，照抄必错——遇到莫名的 400，先检查参数是不是已被这一版淘汰。
7、总结
本篇完成三件事：装好 venv 与 SDK（PyPI 最新 2.3.0）、用 .env 管住密钥、跑通第一次 client.messages.create()。这套环境一次装好，后面 11 篇直接复用。三个心智模型请带走：system 是独立顶层参数、max_tokens 必填、回复是带 type 的块数组——整个系列全部建立在这三点上。
留三个练习：把 system 改成"你只会用文言文回答"，观察文风整体切换；把 max_tokens 降到 32 重跑，看 stop_reason 变成 max_tokens、句子断在哪里；换成 claude-haiku-5-5 再跑一次，对比速度与 output_tokens 花费——顺手记录三组数字，对成本就有直观感受了。对于刚起步的开发者，建议今天就动手做完这三组对照——参数的行为，改一次比读十遍记得牢。下一篇讲流式输出：让回复逐字打到屏幕上，等待体验完全不同。
