API 是什么？OpenAI API、兼容接口与 API Key 入门说明
简答：API 是应用之间按约定格式交换请求和响应的接口；OpenAI API 则是调用模型、生成文本或使用其他能力的程序接口。只想聊天可以使用网页应用，需要把 AI 接入程序时才使用 API；兼容接口通常让已有 OpenAI SDK 或工具改动较少，但具体模型、参数和功能仍需按服务商文档核验。
定义：API（Application Programming Interface，应用程序编程接口）是一组约定好的请求、认证、参数和响应规则，让一个程序能够调用另一个程序提供的能力。
先看结论：API、网页应用和兼容接口有什么区别
截至 2026-11-01，OpenAI 官方文档将 API 定义为面向程序调用的接口，并提供 Responses、Realtime、管理接口等不同 API 面向。API 调用通常需要凭据、请求地址、模型或能力标识，以及符合接口要求的请求体。OpenAI API Reference
| 对象 | 适合做什么 | 是否需要自己写请求 | 关键注意事项 |
|---|---|---|---|
| ChatGPT 等网页应用 | 直接对话、临时使用 AI 功能 | 通常不需要 | 由网页应用负责界面、登录和请求流程 |
| OpenAI API | 把模型能力接入网站、脚本、应用或自动化流程 | 需要，或使用 SDK | 需要自行管理 API Key、模型、请求错误和用量 |
| OpenAI 兼容接口 | 让部分现有 SDK、客户端或工具复用类似的请求结构 | 通常需要配置 | “兼容”不代表模型、参数、工具调用和流式能力完全一致 |
| API Router | 在多个模型或供应商之间统一入口、切换或路由 | 通常需要配置路由层 | 要分别核验上游权限、模型名、价格、限速和返回格式 |
最简单的判断方法是：只想在页面里聊天，不必先学 API；要让程序自动发请求、读取响应或批量处理任务，就需要 API；要把一个已有 OpenAI SDK 接到其他服务，则需要确认该服务是否提供 OpenAI 兼容协议以及兼容范围。
四个常见字段：API Key、Base URL、Endpoint、Model
API Key 是用于识别和授权请求的秘密凭据。OpenAI 官方建议不要把密钥放进浏览器、移动端或公开代码，而应通过服务器端环境变量或密钥管理服务加载。官方认证说明
Base URL 是接口服务的基础地址。使用官方接口时，应从当前官方文档复制；使用兼容接口时，应从对应服务的控制台或文档复制。不要看到某个地址包含 /v1 就自行补全，最终路径要以接口文档为准。
Endpoint 是具体功能的请求路径，例如创建响应、列出模型或发送嵌入请求。不同协议的路径、请求体和返回结构可能不同，不能仅凭“兼容”二字判断所有 Endpoint 都可用。
Model 是要调用的模型标识。模型 ID、上下文窗口、最大输出、价格、工具支持和生命周期会变化，发布或部署前应从当前模型目录或服务控制台复制并核验。本文不把未经当前页面核验的模型名写成可直接使用的固定值。OpenAI 模型目录
| 字段 | 它解决的问题 | 新手常见错误 |
|---|---|---|
| API Key | 证明请求来自有权限的调用方 | 把 Key 提交到 Git 仓库、前端代码或聊天记录 |
| Base URL | 确定请求发往哪个服务 | 复制了错误域名、路径或环境地址 |
| Endpoint | 确定要调用哪项能力 | 把不同协议的路径混用 |
| Model | 确定由哪个模型处理请求 | 模型已下线、拼写错误或当前项目无权限 |
第一次调用：先用官方文档核验，再运行最小请求
下面示例只展示请求结构，不提供可直接使用的密钥或未经核验的固定模型名。运行前，请从当前服务文档或控制台复制真实的 API_KEY、BASE_URL、MODEL_ID，并将它们替换到本地环境变量中。OpenAI 官方快速入门采用环境变量保存密钥，并提供官方 SDK 和首次请求示例。OpenAI Developer quickstart
- 创建或获取项目 API Key，并确认它属于目标项目。
- 将密钥保存到服务器环境变量，例如变量名可以使用
OPENAI_API_KEY；不要把真实值写入代码。 - 从当前文档复制 Base URL、Endpoint 和 Model ID，确认它们属于同一个协议和服务。
- 先发送一个最小请求，再根据响应体、响应头和日志扩展参数。
环境变量示例：export OPENAI_API_KEY="示例值，发送前核实"
curl 结构示例：curl "$BASE_URL/具体Endpoint" -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"MODEL_ID","input":"请回复：测试成功"}'
上面的路径、字段名和模型字段必须以目标接口文档为准；如果服务使用 Chat Completions、Responses 或其他协议，不能直接照搬同一请求体。成功判定至少包括四项：HTTP 状态码符合文档预期、响应体包含目标接口规定的结果字段、结果字段中确实出现模型文本、客户端或脚本能正确显示文本而不是只显示原始 JSON。
如果使用官方 SDK，基本流程是安装 SDK、从环境变量读取密钥、创建客户端、调用目标方法并输出响应字段。官方快速入门中的 SDK 示例使用 Responses API，但具体模型和字段仍应以当前文档为准。
OpenAI 兼容接口为什么常改三个地方，但不能只改三个地方
所谓 OpenAI 兼容接口，通常是服务商提供了与部分 OpenAI 请求格式相似的访问层，使原本使用某类 SDK 或客户端的程序可以少改一些配置。常见变化包括 Base URL、API Key 和 Model，但这只是迁移起点，不是完整兼容证明。
- 先改 Base URL：使用服务商当前文档给出的完整基础地址，确认 SDK 会不会自动追加版本路径。
- 再改 API Key：使用该服务签发的密钥，不要把一个服务的 Key 用到另一个服务。
- 最后改 Model：从服务商控制台复制可用模型 ID，不要凭模型显示名猜测请求值。
- 逐项测试能力：文本输入、流式输出、工具调用、图片输入、结构化输出、上下文长度和错误格式都可能存在差异。
如果只是普通文本请求，兼容层可能足够；如果程序依赖工具调用、文件搜索、计算机操作、推理参数或严格的流式事件，就必须按照目标服务的能力表逐项核验。没有对应官方说明的功能，应标记为“需核实”，不要把 SDK 能发出请求等同于功能已经可用。
按响应排查：401、404、模型不存在、余额或权限错误
排错时不要只看状态码。先查看响应体中的错误类型、消息和参数位置，再结合响应头、请求 ID、最终 URL、实际模型名和项目权限判断。OpenAI 官方错误文档也将认证错误、请求格式错误、权限或用量限制等情况分别处理。OpenAI API 错误代码说明
| 症状 | 优先核对顺序 | 可执行动作 |
|---|---|---|
| 401 | Key 是否为空、过期、撤销、带空格，项目是否匹配 | 检查环境变量实际读取结果但不要打印完整密钥；必要时创建新 Key 并重新测试 |
| 403 | 项目权限、组织或区域限制、接口权限 | 查看响应体和控制台权限，不要仅凭 403 推断为 Key 错误 |
| 404 | 最终 URL、Endpoint、模型 ID、版本路径 | 打印脱敏后的最终请求地址，逐项与当前文档对照 |
| 模型不存在 | 模型 ID 拼写、项目可见范围、模型生命周期 | 从模型目录或控制台复制可用 ID，不要使用展示名称替代 ID |
| 429 或余额相关错误 | 用量、账户状态、限速、并发和项目额度 | 查看响应体与限速响应头，降低并发并确认账户或项目状态 |
| 超时或流式中断 | 网络、客户端超时、服务端响应、残余缓冲 | 记录请求 ID和错误体；对可安全重试的请求采用有边界的重试策略 |
官方 API Reference 说明了请求 ID和限速相关响应头的用途。生产环境建议记录请求 ID、最终使用的模型 ID、接口路径和耗时，但绝不要记录完整 API Key 或包含敏感内容的请求体。请求调试与响应头说明
API Key 安全：本地测试和生产环境分别怎么做
- 本地测试：使用环境变量或本地密钥文件，并将密钥文件加入忽略规则；不要把真实密钥写进示例代码。
- 服务器部署：让请求经过自己的后端，由后端保存密钥；浏览器和移动端只调用自己的后端接口。
- 团队协作：尽量让每位成员使用独立密钥，并根据项目权限和有效期进行管理。
- 成本控制：启用用量监控、支出限制或项目级控制；限制告警不等于立即阻断流量，仍要定期检查用量。
- 疑似泄露：立即撤销或轮换密钥，检查用量和日志，替换部署环境中的旧值，并排查代码仓库和构建产物。
OpenAI 的密钥安全建议包括使用环境变量、避免提交代码仓库、设置有效期、轮换密钥、监控用量以及设置支出限制。API Key 安全最佳实践
新手自查清单
- 我是否明确要调用网页应用，还是要把模型接入程序？
- 我是否从当前官方文档或控制台复制了 Base URL、Endpoint 和 Model ID？
- API Key 是否只保存在服务器环境变量或密钥管理服务中？
- 最小请求是否使用了与目标协议匹配的请求体？
- 我是否检查了 HTTP 状态码、响应字段、实际文本和客户端显示？
- 出现错误时，我是否查看了响应体、响应头、请求 ID 和最终 URL？
- 如果使用兼容接口，我是否单独核验了流式、工具调用、图片、结构化输出和限速？
如果这些问题都能回答清楚，通常就具备了从一次测试请求进入正式集成的基础；具体模型、价格、额度和权限仍应以目标服务当前页面为准。
常见问题
API 是不是只有程序员才需要？
如果只是使用网页应用聊天，通常不需要理解 API；如果要让网站、脚本、客户端或自动化流程自动调用模型，就需要了解 API Key、请求地址、请求体和响应处理。
OpenAI API 和 ChatGPT 有什么区别？
ChatGPT 是面向用户的应用形态，OpenAI API 是面向程序调用的开发接口。两者的登录方式、计费关系、可用模型、权限和功能范围不能仅凭名称互相推断，应分别查看对应文档和账户页面。
OpenAI 兼容接口是不是完全等于 OpenAI API？
不是。兼容通常表示部分请求格式或 SDK 使用方式相似，具体模型、Endpoint、参数、工具调用、流式事件、限速、返回结构和错误格式仍可能不同，必须按目标服务文档逐项核验。
API Key 应该放在哪里？
本地测试可放在环境变量或受保护的本地密钥文件中；生产环境应放在服务器端环境变量或密钥管理服务中。不要放进前端代码、移动端安装包、公开仓库或截图。
为什么会出现 401 或 404？
401 优先检查 Key 是否为空、错误、过期、撤销或项目不匹配；404 优先检查最终 URL、Endpoint、版本路径和 Model ID。应先查看响应体和请求日志，再决定是凭据、路径、模型还是权限问题。