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

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

0. 为什么需要 API？

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

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

这个"窗口"，就是 API。

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

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

1.1 你面临的三个问题

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

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

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

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

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

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

1. 跟谁说？(Endpoint)

2. 怎么说？(Method)

3. 查什么？(Params)

?type=

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

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

2.1 HTTP API（点外卖）

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

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

2.2 SDK（堂食/VIP服务）

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

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

🤖 真实场景：让 AI 帮你写产品文案

体验两种调用方式的区别

📝你的需求

我想让 AI 帮智能手表写一段吸引人的产品文案

找到网址（打开外卖 APP）

https://api.openai.com/v1/chat/completions

准备订单（填写信息）

Authorization: Bearer 你的API密钥
Content-Type: application/json

下单（发送请求）

{
  "model": "gpt-4",
  "messages": [
    { "role": "system", "content": "你是营销文案专家" },
    { "role": "user", "content": "写智能手表文案" }
  ]
}

等待配送（解析响应）

response.choices[0].message.content
⚠️ 需要自己处理解析错误

💡 HTTP API 特点：

✅ 灵活：任何语言都能用
❌ 复杂：要手动处理很多细节
❌ 容易出错：鉴权、数据格式、错误处理都要自己写

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

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

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

3.1 GET：只看不买

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

3.2 POST：搞点事情

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

🔍 HTTP 方法：GET、POST、PUT、DELETE 是什么？

把它们想象成对数据的"操作方式"

GET

📖 获取（查询）

只看不改 - 从服务器获取数据

• 查询用户信息

• 搜索商品

• 获取文章列表

💡 可以安全重试，不会改变服务器数据

POST

➕ 创建（新增）

新建数据 - 在服务器创建新资源

• 创建新用户

• 提交订单

• 发表评论

⚠️ 不能随意重试，可能会重复创建

PUT

✏️ 更新（替换）

整体替换 - 用新数据完全替换旧数据

• 修改用户全部信息

• 更换文章全部内容

⚠️ 会覆盖整个资源，需要提供完整数据

PATCH

🔧 修改（部分）

局部更新 - 只修改资源的部分字段

• 只修改用户昵称

• 更新文章标题

💡 只传需要修改的字段，更灵活

DELETE

🗑️ 删除

移除数据 - 从服务器删除资源

• 删除用户

• 取消订单

• 删除评论

⚠️ 操作不可逆，删除后无法恢复

📊 快速对比

方法	操作	是否会改数据	能否重试
GET	查询	❌ 否	✅ 可以
POST	创建	✅ 是	⚠️ 不建议
PUT	替换	✅ 是	⚠️ 不建议
PATCH	修改	✅ 是	⚠️ 不建议
DELETE	删除	✅ 是	⚠️ 不建议

💡 新手建议：

先学会 GET（查询）和 POST（创建）就够用了
PUT/PATCH/DELETE 可以慢慢学，理解原理更重要
实际开发中，GET 和 POST 占了 80% 的使用场景

4. 怎么看 API 文档？

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

4.1 文档里的"藏宝图"

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

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

Method:POST

Endpoint:https://api.deepseek.com/chat

Headers:

Authorization: Bearer sk-8f9s...
Content-Type: application/json

Body:

{
"model":"deepseek-chat",
"messages":[...]
}

Response:

Status:200 OK

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（瞎填地址）。

API Console

METHOD

URL

https://api.game.com

HEADERS

Authorization:

👇 点这些按钮试错

6. 总结

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

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

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

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

0. 为什么需要 API？ ​

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

1.1 你面临的三个问题 ​

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

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

2.1 HTTP API（点外卖） ​

2.2 SDK（堂食/VIP服务） ​

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

3.1 GET：只看不买 ​

3.2 POST：搞点事情 ​

4. 怎么看 API 文档？ ​

4.1 文档里的"藏宝图" ​

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

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

6. 总结 ​