API 修炼场

API 是什么？—— 给机器用的"对讲机"

你已经会跟 ChatGPT 这类网页聊天了。但网页是给人用的：点按钮、看排版、手动复制粘贴。

如果你正在写自己的项目 —— 一个 Discord 机器人、一个背单词小程序、一个会自动回邮件的脚本 —— 它没有手，点不了网页。它需要一种机器对机器的沟通方式。

一个 AI API 到底在干嘛

你在网页上做的事：打字 → 点发送 → 等回复。
你的程序用 API 做的事，一模一样，只是全部用文字协议完成：

你的程序 ──"你好，讲个笑话"（HTTP 请求）──▶ 炼丹社的模型服务器
你的程序 ◀──"为什么程序员总分不清万圣节和圣诞节……"（JSON 响应）──

也就是说：你的项目从此能"说话"了。它能自动总结文章、扮演角色、批改作业、联网搜索——只要你会发这一段文字。

小测 · 证明你听懂了

拆解一次 API 通话 · 然后领取你的钥匙

一次通话的三件套

1. Base URL（频道）：所有请求都发往 https://freeapi.groovin.cn/v1，后面再接具体动作，比如 /chat/completions。
2. API Key（呼号）：放在请求头里 Authorization: Bearer sk-xxx...。它证明"你是你"，用量也记在它名下。Key 就是密码，别贴进公开仓库。
3. JSON Body（暗号内容）：你要说的话，按约定格式组织。最小的一发对话请求长这样：

{
  "model": "Stella",                    // 选哪个模型
  "messages": [
    {"role": "user", "content": "你好"}   // 你说的话
  ]
}

对面会回你一段 JSON，回复的文字藏在 choices[0].message.content 里。整个互联网上的 OpenAI 兼容 API 都长这个样子——学会这一个，等于学会了绝大多数。

🔑 领取你的免费 API Key

💡 这个 Key 在后面的关卡会真的用来调模型。它只保存在你自己浏览器的 localStorage 里，本道场没有任何后端，什么都不会上传。

小测 · 读懂请求

第一次通话：问服务器"你有哪些模型？"

惯例：学任何 API，先发一发最简单的 GET 请求探探路。我们请求 GET /v1/models——它不需要请求体，只要带上你的 Key。

GET https://freeapi.groovin.cn/v1/models
Authorization: Bearer <你的Key>

你的浏览器现在就充当"你的项目"。把 Key 贴进来，道场会真实地向炼丹社服务器发出这个请求：

让模型开口：第一发对话请求

真正的核心接口：POST /v1/chat/completions。这回要带上 JSON 请求体了——就是你 LEVEL 1 见过的那个结构。

POST https://freeapi.groovin.cn/v1/chat/completions
Authorization: Bearer <你的Key>
Content-Type: application/json

{"model":"Stella", "messages":[{"role":"user","content":"<你想说的话>"}]}

输入任何你想对模型说的话，发送。注意看右侧聊天框——你的项目刚才"说话"了，也"听见"了回答。

（发送后这里会展示真实内容）

灵魂注入：用 system prompt 塑造角色

messages 是一个数组——它可以装下整段对话历史，还有一种特殊消息：role: "system"。它是对模型的"下咒"，决定模型用什么人格、什么立场回答你。

{"model":"Stella", "messages":[
  {"role":"system", "content":"你是一只骄傲的猫娘，句尾带'喵'"},
  {"role":"user",   "content":"今晚吃什么？"}
]}

挑战：写一个 system prompt，让模型的回复里出现"喵"字。用户消息固定问它问题即可。这是所有 AI 应用（客服、角色 bot、翻译器）的基本功。

流式输出 & 把 API 接进你自己的项目

① 体验"打字机"：stream = true

网页版 AI 那个一个字一个字蹦出来的效果，就是流式（SSE）：请求里加 "stream": true，服务器每生成一点就推一点。点下面试试：

② 带走：三种语言的接入模板

把下面的代码抄进你自己的项目，换掉 Key 就能跑。这就是"让自己的项目说话"的全部秘密：

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://freeapi.groovin.cn/v1",
    api_key="你的Key",
)

r = client.chat.completions.create(
    model="Stella",
    messages=[{"role": "user", "content": "你好！"}],
)
print(r.choices[0].message.content)

const r = await fetch("https://freeapi.groovin.cn/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 你的Key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "Stella",
    messages: [{ role: "user", content: "你好！" }],
  }),
});
const data = await r.json();
console.log(data.choices[0].message.content);

curl https://freeapi.groovin.cn/v1/chat/completions \
  -H "Authorization: Bearer *** \ \
  -H "Content-Type: application/json" \
  -d '{"model":"Stella","messages":[{"role":"user","content":"你好！"}]}'