📘 第 2 课：Your first API call（你的第一次 API 调用）

所属课程：the AI Platform 101（课程 003） 官方课时定位：Section 1「What is the the AI Platform?」— Lesson 2 / 共 12 课时 ID：486251 ｜ 官方地址：https://anthropic.skilljar.com/claude-platform-101/486251 形式：Video（视频课 + 文稿） 针对认证：CCAR-P（架构师 Professional） 整理日期：2026-10-14 ⚠️ 语料来源：官方 Skilljar 课程正文（用户提供，需登录）。CC BY-NC-SA 4.0，仅供个人学习。 ⭐ 本课权重提示：全课最小可运行单元课。本课给出了 messages.create 的必填三要素与响应结构（block 数组）—— 这两个知识点是领域 2（13%）与领域 3（19%）最密集的交界，且几乎每年必考「密钥该放哪」与「响应怎么取」两道题。

🎯 本课学习目标

⚠️ 本课官方未提供 What you'll learn 区块。以下按文稿结构反推：

1. 能完成开工准备：取 API key、安全地存放、安装 SDK。
2. 能说出一次请求必填的三个要素。
3. 能读懂并写出一个约 20 行的最小可用调用。
4. 理解 system 提示词塑造人格的作用。
5. ⭐ 理解响应 content 是 block 数组（不是字符串），并知道要循环 + 判类型。
6. 能把同一个调用从脚本包装成产品接口。

📖 一、视频导读

官方原句： Saying hi to the AI might warm your heart, but it's not really useful.* In this lesson we'll send the AI something real and get structured insight back — in just under 20 lines of code*.

精译：跟 AI 打个招呼也许能暖你的心，但它其实没什么用。 这一课我们要给 AI 送点真实的东西，并拿回结构化的洞见 —— 而且用不到 20 行代码。

⭐ 官方一上来就否定了 Hello, the AI 式的调用 —— 呼应第 1 课「不是聊天，是构建」的立场。 structured insight（结构化的洞见）与第 1 课的 structured request / structured response 是同一族词。

🔧 二、开工准备（Get set up）

1. 取 API key

First, grab an API key from platform.claude.com. You'll need to purchase some credits beforehand.

精译：首先，从 platform.claude.com 取一个 API key。你需要事先购买一些额度。

2. ⭐⭐ 把 key 放进 .env.local（本课第一个必考点）

官方原句： Take the API key and store it in a .env.local file so it stays out of your version control. Hardcoding keys in source files is how they end up leaked on GitHub — keep them in environment files instead.

精译：把 API key 存进 .env.local 文件，让它不进你的版本控制。把密钥硬编码进源文件，正是它们最终泄露到 GitHub 上的方式 —— 请改放在环境变量文件里。

⭐⭐ CCAR-P 考点（领域 5 治理安全，14%）： 题干给「开发把 API key 提交到了公开仓库」→ 正解一定是改用环境变量/密钥管理服务 + 轮换已泄露的密钥； 陷阱选项：「把仓库设为私有」「删掉提交历史」「加日志监控」—— 这些都是补救，不是根因修复。根因是密钥进了版本控制。 记忆锚：硬编码 = 泄露的路径。环境文件 = 隔离的机制。

3. 安装 SDK

Next, install the SDK:

npm install @anthropic-ai/sdk

官方在 About 里已说明：示例用 TypeScript SDK（@anthropic-ai/sdk）配 Node 与 npm；平台另有 Python SDK，但本课程示例是 TypeScript。 第 1 课的示例是 Python 风格，本课起改为 TypeScript/Node —— 两处都要认识，考题不保证语言一致。

🧬 三、⭐ 请求的解剖（The anatomy of a request）

官方原句：Every API call goes through the messages.create function. You specify three things:

⭐⭐ 「三个必填」是枚举题的高频考点 —— 必须和第 1 课的「四个控制权」区分开：

⚠️ 关键辨析：system 不在必填三要素里 —— 它是第 4 个、可选的参数（本课后面才加入）。 题干问「一次 messages.create 最少需要什么」→ 选 model + max_tokens + messages； 题干问「平台让你控制什么」→ 选第 1 课那四项。 记忆锚：三个必填是「调用」，四个控制是「平台」。

最小形式（官方代码，保持原样）

import the AI provider from "@anthropic-ai/sdk";

const client = new the AI provider();

const msg = await client.messages.create({
  model: "current-model",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: "Hello, the AI",
  }],
});

⚠️ 抓取件说明：the AI provider 与 model: "current-model" 为去品牌化/环境替换残留（第 1 课为 "current-model-lite"）。实际写法是 SDK 的默认导出类与具体模型名（如 Haiku / Sonnet 档）。不要背这些字符串。 💡 官方自己吐槽了这个调用："Saying hi to the AI ... is not really useful" —— 这段只是结构演示，不是推荐用法。

🐛 四、真实案例：审查有 bug 的代码（Reviewing buggy code）

官方原句：Let's give the AI something a little more interesting than "hello." We'll point it at some buggy code and ask for a review. Here's the whole thing — one file, about 20 lines of code:

精译：我们给 AI 一点比「hello」更有意思的东西。我们把它指向一段有 bug 的代码，并要求一次审查。这就是全部 —— 一个文件，大约 20 行代码。

官方代码（保持原样）

import the AI provider from "@anthropic-ai/sdk";

const client = new the AI provider();

const buggyCode = `
function add(a, b) {
  return a - b;
}
`;

const response = await client.messages.create({
  model: "current-model",
  max_tokens: 1024,
  system: "You are a terse senior code reviewer. Give feedback in one paragraph.",
  messages: [
    { role: "user", content: `Review this code:\n${buggyCode}` },
  ],
});

for (const block of response.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

⭐ 官方点名的「两个注意点」（Two things to notice）

1. system 提示词塑造人格（persona）

The system prompt is where you shape the persona. I want a terse senior reviewer, not a chatty one — so I just say that.

精译：system 提示词就是你塑造人格的地方。 我要的是一个惜字如金的高级审查者，而不是一个话痨 —— 所以我就直接这么说。

⭐ 这是 system 提示词最教科书的用法：角色 + 语气 + 输出约束，一句话三层。 呼应第 1 课：system 是「你定义 AI 扮演的角色」的地方；第 1 课把 tone and guidelines（语气与准则）放进去，本课把人格与格式也放进去。 ⭐⭐ just say that（直接说就好） —— 官方在强调：不需要复杂技巧，把要求直说出来就行。这与考纲领域 2 的「系统提示词、模板与护栏」一致：清晰优于机巧。

2. ⭐⭐ 响应 content 是 block 数组，不是字符串

官方原句： The message.content in the response is an array of blocks, not a string. For a basic text reply there's usually just one block of type text, but the AI can return multiple blocks — text, tool calls, thinking — so we always loop and check the type.

精译：响应里的 message.content 是一个 block 数组，不是字符串。对于一次基础文本回复，通常只有一个 text 类型的 block，但 AI 可能返回多个 block —— 文本、工具调用、思考 —— 所以我们要始终循环并检查类型。

⭐⭐ 这是本课技术含量最高的一句，极可能出代码/结构题： * 为什么必须判类型：因为一次响应可能同时含文本、工具调用、思考 —— 直接当字符串用会漏内容或报错。 * 前向呼应：tool calls → 第 5 课 What is tool use?；thinking → 第 6 课 What is thinking?。本课先把三种 block 的名字给你，后面两课再展开。 * ⚠️ 与第 1 课的对照：第 1 课写的是 draft = response.content（直接整体赋值，教学简化）；本课纠正为「必须循环 + 判类型」。以本课为准。 * 记忆锚：响应不是一句话，是一串积木；不看类型就取，等于蒙着眼拿。

运行结果

Run it, and the AI spots that add is subtracting and tells you in one paragraph. That's it. That's the whole API call.

精译：跑起来，AI 会发现 add 其实在做减法，并用一段话告诉你。就这样。这就是整个 API 调用。

（官方终端输出：AI 指出函数名为 add 却使用了减法，并建议把 return a - b 改为 return a + b。）

🚀 五、⭐ 从脚本到产品（From script to product）

官方原句： In a real product, this same messages.create shape is the engine behind something like a summarize endpoint. Pull a meeting transcript out of the database, hand it to the AI with a system prompt that says "extract insights and risks," save the result back on the row, and return it to the UI. It's the same call — just wrapped in a route handler.**

精译：在真实产品里，同样的这个 messages.create 形态，就是类似"摘要接口"背后的引擎。做法是：从数据库取出一份会议转录，把它交给 AI，配上一句「提取洞见与风险」的系统提示词，把结果存回那一行，再返回给界面。还是同一次调用 —— 只是被包在了一个路由处理函数里。

⭐ 端到端链路（正好对应考纲领域 1 的「输入 → 处理 → 输出 → 反馈回路」）

⭐⭐ 本课最重要的架构论断： It's the same call — just wrapped in a route handler. （还是同一次调用 —— 只是被包在了一个路由处理函数里。）

这句话把「演示脚本」和「生产功能」之间的差距，压缩成了一层包装。它直接回答了第 1 课留下的那个转向 —— 从「问 AI 一个问题」到「AI 成为产品的一部分」，在工程上只需要：数据库取数 → 同一次调用 → 存回 → 返回 UI。

⭐ 注意 save the result back on the row（把结果存回那一行） —— 这是有状态的产品做法，不是无状态的问答。对应领域 1 的反馈回路与领域 6 的生命周期管理。

记忆锚：产品化 = 同一次调用 + 数据进出 + 一层路由。

与第 1 课的案例对照

💡 两次都是同一个 messages.create 形态 —— 这就是官方反复强调的「从这里开始，一切都建立在这个模式之上」。

🔑 六、核心要点（Recap）· 官方五条

1. Your first API call is a messages.create function with a model, a token limit, and messages. 你的第一次 API 调用就是一个 messages.create —— 带一个模型、一个 token 上限和一组消息。
2. Store your API key in a .env.local file to keep it out of version control. 把 API key 存进 .env.local，让它不进版本控制。
3. Add a system prompt to shape the AI's behavior. 加一个系统提示词来塑造 AI 的行为。
4. The response content is an array of blocks — loop and check each block's type. 响应的 content 是一个 block 数组 —— 循环并检查每个 block 的 type。
5. From here, everything builds on this pattern. 从这里开始，一切都建立在这个模式之上。

⭐ 第 5 条是全课的承上启下句：后面 10 节课（tool use / thinking / 内置工具 / Skills / MCP / 上下文管理 / 托管智能体）全部是往这个模式上加东西，不是换模式。

🧠 本课 → CCAR-P 考点映射

🔤 本课新生词（已回灌 30-单词表/03，2026-10-14）

✅ 本课进度

• [x] 全文精译与架构师级拆解（2026-10-14）
• [x] ⭐⭐ 记录必填三要素 vs 第 1 课四个控制权（辨析表）
• [x] ⭐⭐ 记录响应 block 数组与「循环 + 判类型」要求，并标注对第 1 课的修正
• [x] ⭐ 记录「从脚本到产品」端到端链路与 same call, route handler 论断
• [x] ⭐⭐ 记录密钥管理安全考点（.env.local / hardcoding / version control）
• [x] 英文原文已存：17-English-02-Your-first-API-call.md
• [x] 生词回灌 30-单词表/03-考试核心生词与术语表.md（2026-10-14 建表，301 条入速查区，⭐⭐ 28 条精讲）
• [ ] 官方未提供 What you'll learn 区块 —— 若后续页面补全，需回填

🔗 关联

• 本课英文原文：17-English-02-Your-first-API-call.md ✅ 已存
• 上一课：03-第1课-What-is-the-AI-Platform.md（平台定义与三层架构）
• 前向呼应：tool calls → 第 5 课 What is tool use?；thinking → 第 6 课 What is thinking?
• 课程大纲：01-课程导读与大纲全景
• 考纲：00-CCAR-P备考蓝图

⚠️ 语料说明：英文原文中的 the AI provider 与 model: "current-model" 为抓取/去品牌化残留，已在代码段下方说明；其余英文引句均为官方原句，未作改动。