什么是 API

它解决什么问题

让两个程序交换数据，而不必知道对方内部怎么实现。

你不需要知道对方用什么语言、什么数据库、跑在哪台机器上；只要按约定发请求，就能拿到结果。换实现、扩容、迁移，对调用方都是透明的。

一次请求由五部分组成

1. 地址（endpoint）：请求发到哪里，例如 /v1/chat/completions。
2. 方法：GET 取数据，POST 提交数据。
3. 请求头：认证信息（如 Authorization）、内容类型（Content-Type: application/json）。
4. 请求体：JSON，放具体参数。
5. 响应：状态码 + 响应体。状态码说「这次调用本身」成不成功，响应体才是业务结果。

一个最小例子

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "你好"}]}'

$API_KEY 从环境变量读，不要写死在命令或代码里——为什么见 什么是 API Key。

三个常见误解

• 「浏览器能打开，程序就能调」：不一定。网页可能靠登录态或跨域限制；API 往往要求单独的凭证。
• 「API 就是 SDK」：不是。API 是约定，SDK 是把这个约定包成函数。SDK 出问题时，最终还是要看它发了什么请求。
• 「返回 200 就是成功」：不是。有的服务把业务错误放在响应体里，状态码仍是 200。判断成功要同时看状态码和响应体。

和相邻概念的区别

对比	API	SDK	网页界面
面向谁	程序	程序（包一层）	人
形态	地址 + 格式约定	语言里的函数库	可视页面
变更影响	字段或版本变了就断	随 SDK 版本	用户自己适应

延伸阅读

• 服务端怎么认出调用方：什么是 API Key
• 亲手发一次请求：第一次 API 调用