API学院

什么是API？

API = Application Programming Interface = 程序之间的"对话规则"。

你不需要知道厨房怎么炒菜，只需要知道怎么点菜。

生活中的 API 例子

为什么需要API？

API 让你站在巨人的肩膀上：

• 不用自己造轮子：想用AI能力？调API就行，不用训练模型
• 快速集成：几行代码就能发邮件、查天气、处理支付
• 专业分工：每个公司做自己最擅长的事，通过API连接

API Key

API Key 是你的"身份证明"，就像银行卡密码一样。调用 API 时需要带上它，服务器才知道你是谁。

// API Key 通常放在请求头里
Authorization: Bearer sk-xxxxxxxxxxxxxxxx

怎么获取 API Key？

1. 注册账号（OpenAI、DeepSeek 等）
2. 进入 API 管理页面
3. 点击"创建新 Key"
4. 复制保存（只显示一次）

REST API

REST 是最常见的 API 设计风格。它的核心思想：用 URL 表示资源，用 HTTP 方法表示操作。

资源（名词）：     /users        /orders        /products
操作（动词）：     GET/POST/PUT/DELETE

GET    /users        → 获取所有用户
GET    /users/123    → 获取ID为123的用户
POST   /users        → 创建新用户
PUT    /users/123    → 更新用户123
DELETE /users/123    → 删除用户123

GET / POST / PUT / DELETE

JSON

JSON（JavaScript Object Notation）是 API 数据传输的通用格式。几乎所有 API 都用 JSON 传数据。

{
  "name": "张三",
  "age": 25,
  "hobbies": ["编程", "游戏"],
  "address": {
    "city": "北京",
    "district": "海淀"
  }
}

JSON 的规则很简单：

• 用 {} 表示对象
• 用 [] 表示数组
• 键值对用 : 分隔
• 每个键值对用 , 分隔
• 字符串用双引号

请求结构

一个完整的 HTTP 请求包含：

POST /v1/chat/completions HTTP/1.1          ← 方法 + 路径 + 版本
Host: api.openai.com                         ← 请求头
Authorization: Bearer sk-xxx                 ← 认证信息
Content-Type: application/json               ← 数据格式

{                                            ← 请求体（Body）
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

拆开看：

• Method：POST（创建数据）
• URL：https://api.openai.com/v1/chat/completions
• Headers：认证信息、数据格式等
• Body：要发送的数据（JSON格式）

响应结构

HTTP/1.1 200 OK                              ← 状态码
Content-Type: application/json               ← 数据格式

{                                            ← 响应体
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮你的？"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

状态码

Streaming 流式输出

你用 ChatGPT 时，文字是一个字一个字"蹦"出来的，这就是 Streaming。

为什么不一次性返回？

• AI 生成一段话需要几秒钟
• 如果等全部生成完再返回，用户要干等
• Streaming 让用户边生成边看，体验好

怎么实现？

// 请求时加上 stream: true
{
  "model": "gpt-4o",
  "messages": [...],
  "stream": true
}

// 返回的是一串数据流，不是一个JSON
data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: {"choices":[{"delta":{"content":"！"}}]}
data: [DONE]

SSE（Server-Sent Events）

SSE = 服务器不断推送数据，客户端只管接收。OpenAI、Claude 的流式 API 都用 SSE。

Rate Limit（限流）

API 通常有调用频率限制，防止被滥用：

超过限制会返回 429 Too Many Requests。解决方案：排队、重试、升级套餐。

OAuth

OAuth 是一种安全的授权方式，让你可以授权第三方应用访问你的数据，而不需要给它密码。

例子：你用 Google 账号登录某个网站，就是 OAuth。

1. 网站跳转到 Google 登录页
2. 你在 Google 登录并授权
3. Google 给网站一个"令牌"
4. 网站用令牌获取你的基本信息

Webhook

Webhook 是"反向 API"——不是你去调别人的 API，而是别人有事时主动通知你。

• API：你去查"有没有新订单？"（轮询）
• Webhook：有新订单时，系统自动发 POST 请求通知你

Webhook 需要你提供一个 URL 接收通知。

实战：从零调用 OpenAI API

第1步：获取 API Key

1. 打开 platform.openai.com
2. 注册/登录
3. 左侧菜单 → "API Keys"
4. 点击 "Create new secret key"
5. 复制保存（格式：sk-proj-xxxxx，只显示一次）

第2步：安装 Python 库

打开终端（Windows: PowerShell，Mac: Terminal），输入：

pip install openai

看到 Successfully installed 就是装好了。

第3步：写第一个 API 调用

创建文件 test_api.py，粘贴以下代码：

Python 版本

import openai

client = openai.OpenAI(api_key="sk-你的key")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "用一句话解释什么是API"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

第4步：运行

1. 把 sk-你的key 替换成你的真实 API Key
2. 终端运行：python test_api.py
3. 你会看到 AI 的回答！🎉

$ python test_api.py
API 是应用程序之间的"对话规则"，让不同的软件能够相互通信和交换数据。

第5步：改成你自己的问题

# 修改 messages 里的内容就行
messages=[
    {"role": "user", "content": "用三句话解释量子力学"}
]

JavaScript / Node.js 版本

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "sk-你的key" });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "你是一个有帮助的助手" },
    { role: "user", content: "用一句话解释什么是API" }
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);

流式输出版本（Python）

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "讲个故事"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

cURL 版本

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的key" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

常见问题

Q: API Key 泄露了怎么办？

立即去平台删除旧 Key，创建新的。大部分平台支持设置消费上限，建议设置。

Q: 调用 API 要多少钱？

按 Token 计费。GPT-4o 大约 $2.5/百万输入Token。一次普通对话约 1000 Token ≈ ¥0.02。详见 模型大全。

Q: 我不会编程，能用 API 吗？

可以！用 Postman（图形化工具）可以直接测试 API。用 n8n、Dify 等低代码平台也可以不用编程就调用 API。