VIBE//CODE

API 与 API Key：两个程序怎样互相办事 ​

这一课不要求你会写后端。目标只有三个：看见 API 不害怕；知道一次请求经过了什么；知道 API Key 绝对不能放在哪里。

第一课：API 到底是什么 ​

先用餐厅来理解 ​

你坐在餐厅里，不能直接冲进厨房翻冰箱。你需要：

  1. 看菜单，知道可以点什么。
  2. 告诉服务员菜名和要求。
  3. 服务员把要求交给厨房。
  4. 厨房做好后，服务员把菜送回来。

换成程序语言：

餐厅里的东西程序里的东西它负责什么
顾客你的前端或另一个程序提出需求
菜单API 文档说明可以调用什么、要提供什么
服务员API按规定接收请求、送回结果
厨房后端、数据库或 AI 模型真正处理任务
一盘菜Response 响应返回的数据或结果

所以 API 可以先读成一句话：一个程序给另一个程序办事时，双方约定好的服务窗口。

再换一个比方：自动售货机 ​

自动售货机的按钮就是公开接口。你不需要知道里面的电机怎样转，只需要按照规则选择商品、付款、取货。API 也会把内部复杂过程藏起来，只让你使用规定好的入口。

网页按钮不是 API ​

“生成图片”按钮是给人点击的界面；POST /api/generate-image 才可能是给程序调用的 API。按钮被点击后，前端代码通常会去调用 API。

text
人点击按钮 → 前端 JavaScript → API → 后端 / AI 模型

第二课：一张 API 点菜单上有什么 ​

看到一段 API 调用时，先找五样东西：

text
POST https://example.com/api/images
↑       ↑
动作    Endpoint（具体地址）

Headers: Authorization、Content-Type
         ↑ 身份证明       ↑ 数据格式说明

Body: { "prompt": "一只猫" }
        ↑ 这次真正交给服务方的内容

Response: { "image_url": "..." }
          ↑ 服务方办完后送回来的结果
  • Endpoint：具体办事窗口的地址，像“3 楼 305 号窗口”。
  • Method：你要做的动作。GET 常是读取，POST 常是新建或提交。
  • Headers：贴在信封外面的说明，例如身份和内容格式。
  • Body：信封里面真正提交的数据。
  • Response：对方处理完成后给你的答复。

第三课：一次请求的真实过程 ​

假设你在漫画工作室里点击“生成分镜”：

  1. 按钮收到点击
    React 的 onClick 找到负责生成的函数。
  2. 前端整理数据
    把提示词、画面比例、模型选择整理成 JSON。
  3. 前端请求自己的后端
    例如请求 /api/generate，此时浏览器的 Network 会出现一条记录。
  4. 后端检查请求
    确认用户身份、参数是否完整，再从服务器环境变量读取 API Key。
  5. 后端调用模型 API
    带着 Key、模型名和 Prompt 请求模型平台。
  6. 模型平台返回结果
    可能立刻返回文字，也可能返回一个“任务已经创建”的编号。
  7. 后端把结果交回前端
    前端更新状态，页面才显示图片、文字或错误提示。

这条路上任何一段都可能失败，所以“生成失败”并不自动等于“模型坏了”。

第四课：API Key 是什么 ​

API Key 是一串秘密字符，用来告诉平台：是谁在调用、有没有权限、费用记在谁的账号上。

三个生活类比 ​

  • 像会员卡：刷卡后，消费记录算在你的会员账户。
  • 像酒店房卡：拿到卡的人就可能进入被授权的房间。
  • 像公司印章：别人盗用后做的事情，系统可能仍然认为是你做的。

因此 API Key 不是“普通配置文字”。别人拿到它，可能消耗你的余额、访问你的资源，甚至造成数据风险。

Key 应该放在哪里 ​

text
浏览器里的 React 代码      ❌ 用户可以下载并查看
提交到公开 GitHub 的文件   ❌ 搜索引擎和机器人可能找到
截图、聊天记录、日志       ❌ 容易被无意转发
服务器环境变量             ✅ 运行时读取，不写进公开代码
Cloudflare / Railway 密钥   ✅ 由部署平台安全注入

本地开发常用 .env：

dotenv
ARK_API_KEY=这里放真实的密钥

同时在 .gitignore 里忽略它：

text
.env
.env.local

.env.example 可以提交，但只能写名字和假值：

dotenv
ARK_API_KEY=your_key_here

如果 Key 已经不小心公开 ​

不要只删除 GitHub 上那一行，因为旧提交里可能还留着。正确顺序是：立刻去平台撤销旧 Key → 创建新 Key → 更新部署环境变量 → 再处理仓库历史。

第五课：读懂 manga_studio 的真实代码 ​

你的 manga_studio/app.py 会在服务器上读取环境变量：

py
ARK_API_KEY = os.environ.get("ARK_API_KEY", "")

逐块读：

text
ARK_API_KEY = os.environ.get("ARK_API_KEY", "")
     ①      ②        ③            ④         ⑤

① 代码里使用的名字
② 把右边得到的结果保存进左边
③ 操作系统提供的环境变量集合
④ 查找名为 ARK_API_KEY 的配置
⑤ 如果没找到，先得到空文字

后面的配置函数把调用需要的东西放在一起：

py
return {
    'base_url': 'https://ark.cn-beijing.volces.com/api/v3',
    'api_key': ARK_API_KEY,
    'model': model_cfg['model_id']
}

可以把它想成服务员出发前拿到的小票：去哪栋楼、出示哪张会员卡、找哪个模型。

真正调用 SDK 时：

py
client = Ark(api_key=cfg['api_key'])
resp = client.chat.completions.create(
    model=cfg['model'],
    messages=messages,
    temperature=temperature,
    max_tokens=max_tokens
)
  • client：一名已经拿到通行证的“专属服务员”。
  • create(...)：现在提交一次生成任务。
  • model：找哪位厨师。
  • messages：这次点单的内容。
  • resp：服务完成后收到的答复。

SDK 只是替你包装了 HTTP 请求。使用 SDK 和调用 API 不是两件互不相关的事；SDK 是更方便的 API 调用工具箱。

第六课：常见 API 报错怎么判断 ​

看到的状态人话最先检查通常不是先改什么
400你交的点菜单格式不对Body、必填参数、JSONDNS
401没认出你的身份Key 是否正确、是否加载页面颜色
403认出你了，但不允许办账号权限、模型权限、地区限制React 布局
404没有这个窗口Endpoint 拼写、路由API 余额
429请求太多或额度不足限流、并发、余额HTML
500服务内部出错后端日志、对方服务状态用户浏览器缓存

一次最实用的排查 ​

  1. 打开浏览器开发者工具的 Network。
  2. 再点一次出问题的按钮。
  3. 点开红色请求，先看 Status。
  4. 看 Request Payload：你到底发了什么。
  5. 看 Response：对方到底说了什么。
  6. 如果请求根本没出现，问题还在按钮或前端函数；如果出现了，再沿状态码继续查。

学完测试 ​

为什么前端不能直接带着秘密 API Key 请求模型平台？

答案：因为前端代码和网络请求会出现在用户浏览器里，别人能读到 Key。更安全的路线是：前端请求自己的后端，后端从服务器环境变量读取 Key，再调用模型平台。

Network 里出现 401 时，应该先检查页面按钮样式还是 API Key？

答案：先检查 API Key、环境变量是否加载，以及认证 Header。401 表示服务没有接受当前身份凭证，通常和按钮样式无关。

写给想驾驭 AI，而不只是依赖 AI 的 Vibe Coder。

持续更新 · 每次只升级一个认知