# API 入门：怎么跟计算机"说人话"？

> 💡 **写在前面**：这一章不教写代码，只教**"怎么跟别人的软件打交道"**。
> 
> 你可能听说过 "API" 这个词一万次了，但它到底是个啥？别被它的英文全称吓到，把它当成**"连接器"**或者**"传声筒"**就好。

<ApiQuickStartDemo />

## 0. 为什么需要 API？

想象一下，你想用 DeepSeek 的 AI 能力，但 DeepSeek 的核心程序跑在他们自家机房的超级电脑里。
你总不能直接跑去他们机房，插上键盘敲代码吧？

所以，DeepSeek 需要开一个**"窗口"**，让你在千里之外也能用上他们的 AI。

这个**"窗口"**，就是 **API**。

---

## 1. 核心概念：餐厅里的潜规则

为了让你秒懂，我们还是得请出那位经典的**"服务员"**。
但这次我们换个角度：**你是一个只会吃、不会做的顾客**（就像我们只会用 AI、不会写 AI 模型一样）。

### 1.1 你面临的三个问题

当你走进一家外国餐厅（陌生的软件系统），你只想吃饱，但你面临三个问题：

1.  **跟谁说？**（谁是服务员？）
2.  **怎么说？**（用中文还是英文？要填单子还是直接喊？）
3.  **结果咋样？**（菜上了还是卖完了？）

在 API 的世界里，这三个问题对应了三个术语：

| 餐厅里的问题 | 计算机里的术语 | 黑话 (行话) |
| :--- | :--- | :--- |
| **跟谁说？** | **Endpoint (端点)** | "接口地址"、"URL" |
| **怎么说？** | **Request (请求)** | "传参"、"Payload" |
| **结果咋样？** | **Response (响应)** | "返回值"、"返回包" |

### 1.2 互动演示：点一道 AI 料理

别光看字，来亲自试一下"点菜"的感觉。
下面这个小工具模拟了你向 AI **"点一道笑话"** 的过程。

<ApiConceptDemo />

---

## 2. 两种"点菜"流派：外卖 vs 堂食

你在教程里经常会看到两种调用方式：**HTTP** 和 **SDK**。
很多新手会被绕晕，其实它们就是**"点外卖"**和**"堂食"**的区别。

### 2.1 HTTP API（点外卖）

这是最原始、最通用的方式。就像**填一张外卖单子**。

*   **特点**：**死板但通用**。
*   **怎么做**：你需要严格按照格式，填好地址（URL）、选好菜（参数）、贴好邮票（API Key），然后通过网络发出去。
*   **谁在用**：所有编程语言都能用，甚至你在浏览器地址栏里敲一行字也是一种 HTTP 请求。

### 2.2 SDK（堂食/VIP服务）

SDK (Software Development Kit) 就像是餐厅派给你的**专属管家**。

*   **特点**：**省心但挑人**。
*   **怎么做**：你不需要自己填单子、贴邮票。你只需要跟管家说："来份宫保鸡丁"。管家会自己在后台帮你填单子、发请求、处理报错。
*   **谁在用**：通常针对特定语言（比如 Python 版管家、Node.js 版管家）。

<RealWorldApiDemo />

> **新手建议**：能用 SDK 就用 SDK，**把麻烦事留给别人，把时间留给自己**。

---

## 3. 进阶：GET 和 POST 到底有啥区别？

在看文档时，你总能看到这俩词。
其实很简单，就看**"你是否想改变世界"**。

### 3.1 GET：只看不买

*   **含义**：**获取**信息。
*   **场景**：刷朋友圈、看新闻、查天气。
*   **特点**：你做这件事一万次，服务器里的数据也不会变（除了访问量+1）。
*   **比喻**：你看菜单，看一眼是看，看一百眼还是看，菜单不会变。

### 3.2 POST：搞点事情

*   **含义**：**提交**信息。
*   **场景**：发朋友圈、注册账号、**让 AI 写文章**。
*   **特点**：你做这件事，服务器里就会**多出**一条记录，或者**生成**一段新的内容。
*   **比喻**：你下单点菜。你下一次单，厨房就得忙活一次，你的钱包就得瘪一次。

<ApiMethodDemo />

---

## 4. 怎么看 API 文档？

文档就像**"说明书 + 菜单"**。
你不需要从头读到尾，只需要学会**"查字典"**。

### 4.1 文档里的"藏宝图"

打开任何一个 API 文档（比如 OpenAI 或 DeepSeek），你只需要找这几样东西：

1.  **Base URL**：根地址（餐厅在哪？）。
2.  **Authentication**：怎么证明你是会员？（通常是加个 `Authorization: Bearer sk-...` 头）。
3.  **Endpoints**：具体的菜品列表。
    *   `/v1/chat/completions` -> 对话（最常用的）
    *   `/v1/images/generations` -> 画图
4.  **Parameters**：必填项有哪些？
    *   `model`: 选哪个厨师？
    *   `messages`: 你想聊啥？

<ApiDocumentDemo />

### 4.2 常见的"餐厅黑话"（状态码）

服务员（API）回复你的时候，通常会先喊一个数字代码：

*   **200 OK**：菜齐了，慢用。（成功）
*   **400 Bad Request**：你点的菜菜单上没有，或者你没填辣度。（你填错了）
*   **401 Unauthorized**：会员卡过期了，或者假卡。（没权限）
*   **404 Not Found**：找不到这道菜，或者找不到这家店。（地址错了）
*   **429 Too Many Requests**：你点太快了，厨师炒不过来了。（限流）
*   **500 Internal Server Error**：厨房炸了，不是你的锅。（服务器崩了）

---

## 5. 练手场：弄坏它也没关系

光说不练假把式。
这里有个模拟 API。你可以随便填参数、随便改地址，看看会发生什么。
试着触发一下 **401**（假装没带钱）或者 **404**（瞎填地址）。

<ApiPlayground />

---

## 6. 总结

别把 API 想得太高大上。
在 AI 编程的时代，你只需要记住：

1.  **API 就是传声筒**：帮你把话传给 AI 模型。
2.  **SDK 是好管家**：能用管家就别自己跑腿。
3.  **看文档找三样**：地址、密钥、参数。

这就够了。剩下的，交给 IDE 去写吧。