sanbuphy
153 lines
5.7 KiB
Markdown
153 lines
5.7 KiB
Markdown
# 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 去写吧。
|