什么是 API？面向应用构建者的通俗指南
API（应用程序编程接口）是一种约定好的方式，让一个软件向另一个软件请求数据，或让它执行某项操作。你的应用以约定的格式发送请求，例如“给我明天的预约”“从这张卡上收取 20 欧元”“总结这段文字”，另一个系统则返回结构化的响应。API 是应用各个部分相互通信的方式，也是你的应用使用外部服务（支付、邮件、地图和 AI）的方式。
用 AI 建站时 API 为什么重要
几乎每个有用的应用都由通过 API 相互通信的部件组成：
- 在应用内部，浏览器中的界面调用你自己后端的 API 来加载和保存数据。
- 在应用外部，你的后端调用其他公司的 API：用 Stripe 收款，用邮件服务商发送收据，用 AI 模型服务商生成文字。
当你让 AI 建站工具“接入支付”或“添加 AI 摘要”时，它实际上是在编写调用 API 的代码。了解基础知识，可以帮助你明白 AI 需要你提供什么（通常是该服务的账户和 API 密钥），哪里可能出问题，以及会产生多少费用。
日常类比
可以想象一家餐厅。你不会走进厨房自己做饭。你看菜单，用厨房能理解的方式告诉服务员你想要什么，然后服务员把菜端回来——或者告诉你这道菜已经售罄。
- 菜单就是 API 文档：列出你能点什么，以及该怎么点。
- 服务员就是 API：请求进入、响应送出的那一种约定方式。
- 厨房是另一个系统：你不需要知道它内部如何运作。
- 你的订单是请求；端上来的菜是响应。
只要菜单不变，厨房即使更换了炉灶和员工，也不会影响到你。这正是 API 的真正价值：它让两个系统可以协同工作，而双方都不需要了解对方是如何构建的。
Web API 请求如何工作
你会遇到的大多数 API 都是通过 HTTP（浏览器使用的同一种协议）工作的 Web API。每个请求都有几个部分：
| 部分 | 是什么 | 示例 |
|---|---|---|
| 方法 | 操作的类型 | GET（读取）、POST（创建） |
| URL / 端点 | 你要操作的对象的地址 | https://api.example.com/bookings |
| 请求头 | 额外信息，包括你是谁 | Authorization: Bearer <your key> |
| 请求体 | 创建和更新时发送的数据 | {"name": "Lena", "time": "14:00"} |
每个响应则包含：
| 部分 | 是什么 | 示例 |
|---|---|---|
| 状态码 | 表示结果如何的数字 | 200 成功，201 已创建，404 未找到 |
| 响应体 | 返回的数据，通常为 JSON | {"id": 5001, "status": "confirmed"} |
JSON（JavaScript 对象表示法）是一种简单的文本格式，用花括号包裹名称和值。它是 Web API 交换数据的标准方式。
REST：最常见的风格
REST 是设计 Web API 时广泛采用的一种约定。每一类事物都有自己的网址，标准方法则说明你要对它做什么。下面是一个预约应用的 REST API 可能的样子：
| 方法 | 端点 | 作用 |
|---|---|---|
GET | /api/bookings | 列出预约 |
GET | /api/bookings/5001 | 获取一条预约 |
POST | /api/bookings | 创建一条新预约 |
PATCH | /api/bookings/5001 | 修改预约的一部分，例如时间 |
DELETE | /api/bookings/5001 | 取消（删除）预约 |
PUT 也存在，按惯例它会替换整条记录，而 PATCH 只更改你发送的字段。
你最常见到的状态码：
| 状态码 | 含义 |
|---|---|
200 / 201 | 成功 / 已创建 |
400 | 错误请求——你发送的内容有误或缺失 |
401 | 未通过身份验证——没有有效的登录或密钥 |
403 | 禁止访问——系统认得你，但你无权执行此操作 |
404 | 未找到 |
429 | 请求过多——你触发了速率限制 |
500 | 服务器出错 |
当你的应用出问题时，状态码通常是最快的线索。来自支付服务商的 401 通常意味着 API 密钥缺失或错误；429 则表示你调用得太频繁。
REST 并不是唯一的风格——GraphQL 和 RPC 风格的 API 也存在——但大多数服务和 AI 构建的后端使用的都是 REST。
实例：预约确认
当顾客在一款美发应用中预约理发时，可能会在一两秒内发生几次 API 调用：
- 浏览器中的预约页面向你的后端发送
POST /api/bookings，包含服务项目、时间和顾客信息。 - 你的后端检查该时段是否空闲，把预约保存到数据库中，并返回
201 Created。 - 你的后端使用其密钥调用邮件服务商的 API：“把这份确认发送到 lena@example.com。”
- 如果需要支付定金，你的后端会请求支付服务商的 API 创建结账会话，并把顾客引导到那里。
- 稍后，支付服务商会调用你的应用，告知付款已成功。这种反向调用就是一个 Webhook。
前两步是你自己在前端与后端之间的 API。第 3–5 步则是第三方 API。
常见术语解释
| 术语 | 含义 |
|---|---|
| 端点（Endpoint） | API 响应的某一个具体网址。 |
| API 密钥（API key） | 向服务标识你的应用的机密字符串。请像对待密码一样对待它。 |
| 身份验证（Authentication） | 证明调用者是谁——通过密钥、令牌或登录。参见什么是身份验证。 |
| 速率限制（Rate limit） | 在一段时间内你可以发出的请求数量上限。 |
| SDK | 一个现成的代码库，使调用某个特定 API 更容易。 |
| 文档（Documentation） | 那张“菜单”：有哪些端点，它们接受什么、返回什么。 |
| 沙盒 / 测试模式（Sandbox / test mode） | 服务的一个版本，用于在不涉及真钱或真实数据的情况下进行测试。 |
| Webhook | 某件事发生时，另一个服务对你的应用发起的调用。 |
常见错误与误解
- 把密钥放在前端。 任何在浏览器中运行的代码，都可以被访问该网站的任何人看到。密钥必须保留在服务器上，保存在环境变量或密钥中。
- 把密钥粘贴到聊天中。 聊天记录可能会被保存。请改用构建工具的密钥功能，并轮换任何已经暴露的密钥。
- 以为 API 是免费的。 许多 API 按请求次数或用量收费——AI 模型 API 按 token 计费。请查看价格并设置消费上限。参见如何使用 LLM API。
- 不处理失败。 外部服务会宕机、超时并触发限制。请要求给出合理的错误提示和重试机制。
- 信任浏览器。 你自己的 API 必须自行检查权限。隐藏一个按钮并不能阻止别人直接调用端点。
- 测试时使用正式密钥。 在准备上线之前，请使用测试模式的密钥。
向你的 AI 建站工具提出什么要求
- “这个应用使用了哪些外部 API？每一项的费用是多少？”
- “只从服务器调用支付 API。从环境变量中读取密钥。”
- “列出我们 API 中的每一个端点、它的作用，以及允许哪些人调用它。”
- “在更新或删除预约之前，在服务器上检查当前登录用户是否拥有该预约。”
- “如果邮件 API 失败，仍然保存预约，并记录错误。”
- “目前请使用服务商的测试模式。”
Mythex 中的 API
Mythex 可以构建你自己的 API——无论是作为 Web 应用的一部分，还是作为与前端并行运行的独立后端（使用 Node、Python（FastAPI）、C# 或 Java），并编写调用外部服务的代码。你把它们的密钥作为项目密钥添加，而不是直接写在聊天里；它们在预览中以及发布后都可供你的应用使用。文档中有集成任意 API和构建 REST API 后端两个方案。
常见问题
简单来说，什么是 API？
API（应用程序编程接口）是一种约定好的方式，让一个软件向另一个软件请求数据或让它执行某些操作。你的应用以约定的格式发送请求，另一个系统返回响应，例如天气数据、付款结果或 AI 生成的回复。
什么是 REST API？
REST API 是一种常见的 Web API 风格：每一类事物（预约、客户）都有一个网址，你使用标准的 HTTP 方法：GET 用于读取，POST 用于创建，PUT 或 PATCH 用于更新，DELETE 用于删除。数据通常以 JSON 格式返回。
什么是 API 密钥，应该保存在哪里？
API 密钥是一串机密字符串，用来向服务标识你的应用，而且它常常可以用来花钱或访问数据。请把它保存在环境变量或项目的服务器密钥中，绝不要放在在浏览器中运行的代码里，也不要放在公开的代码仓库中。
API 和 Webhook 有什么区别？
使用 API 时，你的应用在需要的时候向另一个服务请求某些内容。使用 Webhook 时，另一个服务在事件发生时调用你的应用，例如支付服务商通知你某笔付款已成功。