学习 Claude API 是走向 Claude Certified Architect 方向时避不开的第一步。很多人以为架构师只需要做方案选型、画架构图、编排流程，真正动手准备前置内容时才发现，所有架构决策最终都要落到 API 请求、Token 计算、错误处理和调用链路上。Part 1 先把 Claude API 这一层打通：理解消息结构、能发起一次真实请求、看得懂响应、会按错误码排查问题。接下来从概念、环境、最小实现、参数、排错到实践清单逐步展开，适合刚开始接触 Claude API 的开发者，也适合准备认证但缺少 API 实操经验的工程师。读完你应该能独立完成一次带系统提示的对话请求，并能在生产环境之前设计出可维护的调用层。
1. 先理解 Claude API 在认证准备里解决什么问题
1.1 Claude API 是什么，和网页聊天有什么不同
Claude API 是 Anthropic 开放的模型调用接口。开发者通过 HTTP/HTTPS 把文本请求发送到模型服务，模型返回文本、结构化内容或后续要用的工具调用结果。网页聊天是产品形态，API 是编程接入方式。两者底层模型可能相同，但 API 强调可控性：你可以指定 system prompt、维护多轮上下文、读取 Token 用量、处理错误，并把模型能力嵌入到自己的业务流程里。
在 Claude Certified Architect 这类学习路径里，前置准备并不要求你先精通机器学习，而是要能准确回答这些问题：一次请求包含哪些字段？上下文窗口如何计算？max_tokens 和输入长度有什么关系？服务端过载时怎么处理？这些都属于 API 基础能力。如果只会打开网页聊天，遇到 529 或 400 错误时无法定位问题，后续的架构设计自然也无法建立。
网页聊天和 API 的差异，可以用下面这张表快速理解：
| 对比项 | 网页聊天 | Claude API |
|---|---|---|
| 调用方式 | 手动输入 | 程序发送结构化请求 |
| 上下文控制 | 产品内部维护 | 开发者自己维护 messages |
| Token 统计 | 不一定完整展示 | usage 返回精确数值 |
| 错误处理 | 页面提示 | 错误码和响应头可供程序处理 |
| 适用场景 | 日常对话、实验 | 应用集成、自动化、架构设计 |
这张表也解释了为什么架构方向要先从 API 入手：只有 API 模式才会把上下文窗口、Token 成本、错误重试这些细节暴露给你，而它们正是系统设计时必须考虑的约束。
1.2 为什么认证方向的前置准备要从 API 开始
架构师设计系统时，要考虑的不只是“哪个模型更强”，还包括调用方式、重试策略、成本、延迟和可观测性。没有真实调用经验，讨论这些会变成空谈。比如你会看到长上下文模型的窗口很大，但如果请求中传入的历史消息太多，输入 Token 就可能逼近窗口上限，再设置一个很大的 max_tokens，请求就会直接失败。这种约束只有通过实际 API 请求才能感受到。
另一个原因是：现代 AI 应用很少只发一次请求。多轮对话、文档摘要、代码生成、工具调用，都是围绕 API 消息结构展开的。先掌握单次请求，再理解多轮消息、流式响应、工具调用，是一条自然递进的学习路径。Part 1 聚焦单次请求，符合认知节奏。
如果跳过 API 层直接学框架，很容易出现一种情况：框架封装了太多细节，导致你无法判断某个报错来自模型参数、网络连接、还是业务代码。认证类题目经常要求从现象判断原因，没有 API 层的真实体感，这类题目几乎只能靠猜。
1.3 学习这份准备清单要具备什么基础
在开始之前，建议先确认自己没有跳过这些前置条件：
- 能熟练使用一种开发语言，Python 或 TypeScript 都可以。
- 能使用命令行，会创建虚拟环境或执行 npm 命令。
- 有可用的 Anthropic API Key，并且了解 Key 的权限范围。
- 能阅读 JSON 结构，至少能区分对象、数组、字符串和数字。
如果这些条件都满足，后面每一节都可以按代码示例直接复现。如果环境不满足，优先补齐语言基础和环境配置，不要直接跳过。很多 API 问题到最后都被证明是环境变量没配好、依赖版本不一致，而不是模型调用本身的问题。
2. 环境准备：拿到 Key、选好语言、装好 SDK
2.1 获取 API Key，并把它放在环境变量里
获取 Claude API 访问权限需要先在 Anthropic 的开发者平台或 Console 中创建账号，然后进入 API Keys 页面创建一个新的 Key。创建成功后，页面只会显示一次完整 Key，之后无法再次查看，所以需要立即复制并保存到安全位置。
安全上第一条规则是不要把 Key 写死在代码里。无论是学习项目还是生产项目，都建议把 Key 放到环境变量中。如果使用.env文件，一定要把它加入.gitignore，避免提交到 Git 仓库。
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxx"上面的sk-ant-api03-只是示例前缀，真实的 Key 会是一长串随机字符。设置完成后，可以在命令行输入以下命令确认：
echo $ANTHROPIC_API_KEY如果输出为空，说明环境变量没有设置成功，需要检查是否使用了正确的终端窗口，或者是否在.env文件里漏写了变量名。
注意：不要把真实 Key 写入博客教程的示例里。公开仓库中的 Key 一旦泄露，应立即在控制台吊销并重新生成。
2.2 使用 Python 准备开发环境
Python 是学习 Claude API 成本最低的语言之一。推荐使用 Python 3.9 或更高版本，并创建独立的虚拟环境，避免污染系统环境。
mkdir claude-api-part1 cd claude-api-part1 python -m venv .venv source .venv/bin/activate pip install anthropic python-dotenv如果你使用的是 Windows PowerShell，激活命令改为：
.venv\Scripts\activate安装完成后，检查 SDK 版本：
pip show anthropic这一步不是为了记版本号，而是确认 SDK 已经安装到当前虚拟环境中。如果系统同时存在多个 Python 环境，很容易出现“pip install 成功，但运行时 import 失败”的情况，检查which python和which pip可以帮你定位。
2.3 使用 Node.js 准备开发环境
Node 环境同样可以调用 Claude API。推荐使用 Node.js 18 或更高版本，项目初始化并安装官方 SDK：
mkdir claude-api-part1-node cd claude-api-part1-node npm init -y npm install @anthropic-ai/sdk dotenv安装后可以在.env文件里加载环境变量，也可以在新版本 Node 中使用--env-file参数。如果你习惯使用 CommonJS，需要require('@anthropic-ai/sdk')；如果使用 ES Module，则用import Anthropic from '@anthropic-ai/sdk'。两种写法都常见，务必要和项目package.json中的"type"字段保持一致，否则会出现模块解析错误。
2.4 用 curl 做一次最快的连通性验证
在写正式代码之前，用 curl 直接请求一次接口，可以最快验证 Key、网络和请求格式是否正常。下面是一个最小请求：
curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ --data '{ "model": "claude-3-5-sonnet-latest", "max_tokens": 100, "messages": [{"role": "user", "content": "用一句话回答：什么是 API？"}] }'请求头中x-api-key用于身份认证，anthropic-version用于指定 API 版本，content-type声明请求体是 JSON。model字段要替换为当前账号可用的模型 ID，下面示例中的claude-3-5-sonnet-latest只是说明写法，实际落地的模型 ID 以控制台展示为准。
如果请求成功，你会得到一个包含content数组和usage对象的 JSON 响应。如果返回 401，说明x-api-key有问题；如果返回 400，说明请求体某个字段不合法。curl 适合快速排错，正式开发建议使用 SDK。
3. 使用 Messages API 跑通一次真实对话
3.1 消息数组的结构和 role 语义
Claude Messages API 的核心是messages数组。数组里的每条消息都有一个role字段，常见值是user和assistant。user表示用户输入，assistant表示模型的历史回复。多轮对话时，两者需要交替出现，不能连续两个user消息，除非你确实需要合并输入。
system并不放在messages数组中，而是作为请求顶层字段传入。它用来设定模型的系统行为，比如语气、角色、约束条件。为什么这么设计？因为system和普通用户消息的语义不同：系统消息需要始终影响后续回复，而用户消息只是一次对话输入。放在顶层可以让 SDK 和排查工具更清晰地区分两者的作用。
可以用下面的表格快速记住三种角色的差异：
| 角色 | 放置位置 | 作用 | 示例 |
|---|---|---|---|
| system | 顶层字段 | 设定全局行为和约束 | “你是一个严谨的技术文档审校” |
| user | messages 数组 | 用户本轮输入 | “请审校这段代码” |
| assistant | messages 数组 | 模型历史回复，多轮上下文 | “我已经看过代码，发现了两个问题” |
3.2 Python 最小可运行示例
在虚拟环境已激活、环境变量已设置的前提下，创建hello_claude.py：
import os from anthropic import Anthropic client = Anthropic( api_key=os.environ.get("ANTHROPIC_API_KEY") ) response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=300, system="你是一个耐心、准确的编程助手。", messages=[ {"role": "user", "content": "请用一句话说明 Messages API 请求结构。"} ] ) print(response.content[
