Base URL、API Key、模型名分别是什么？为什么配错一项就可能调用失败

第一次配置 AI API 时，你通常会看到三个输入项：

• Base URL
• API Key
• Model 或模型名

它们不是三种不同叫法，而是一次请求要依次通过的三层：

Base URL 决定请求发到哪里，API Key 证明请求有没有访问资格，模型名决定最终调用哪一个模型。

可以暂时把它们理解为：

• Base URL 是地址；
• API Key 是门禁凭证；
• 模型名是房间号。

地址错了，请求到不了正确的服务；凭证无效，服务不会放行；房间号不存在，已经通过鉴权也找不到模型。

这只是帮助入门的类比。真实调用还会受到接口路径、请求体格式、权限、额度和限速等因素影响。

本文讲的是 OpenAI 风格兼容接口的通用排查思路，并不代表所有平台的路径、鉴权方式和错误格式完全一致。最终配置应以你实际使用服务的当日文档为准。

一、Base URL：请求到底发到哪里

Base URL 是 API 服务的基础地址，例如：

https://api.example.com/v1

它通常还不是最终请求地址。程序还要在后面加上具体端点：

基础地址：https://api.example.com/v1 端点：/responses 完整地址：https://api.example.com/v1/responses

这里最常见的错误，是混淆“基础地址”和“完整请求地址”。

有些客户端要求你只填写基础地址，然后由客户端自动追加/responses；如果你把完整地址填进去，它可能再次追加端点。还有些 SDK 会自动处理/v1，手动再写一次就可能形成重复路径。

因此，填写前先确认两件事：

1. 当前输入框要的是 Base URL，还是完整端点地址？
2. 当前客户端会不会自动追加/v1或具体端点？

不要只凭输入框名称猜，也不要看到别人的配置就原样复制。

二、API Key：证明这次请求是谁发出的

API Key 是访问凭证，不是模型名，也不是网站登录密码。服务端会用它判断：

• Key 是否真实有效；
• Key 是否已撤销；
• Key 是否属于正确的项目；
• Key 是否有权访问当前端点或模型；
• 请求是否受到 IP 等访问策略限制。

OpenAI 风格接口通常把 Key 放在 HTTP 请求头中：

Authorization: Bearer YOUR_API_KEY

Bearer、后面的空格和 Key 本身都不能随意省略。

OpenAI 官方错误指南列出的 401 原因不只包括“Key 写错”，也可能涉及 Key 被撤销、权限不足、项目不匹配或 IP 未获授权。因此，看到 401 时不要立刻判断平台故障，应先检查鉴权层。

三、模型名：告诉服务端具体调用谁

请求中的模型名，更准确地说是 Model ID：

MODEL_ID

它是服务端用于路由请求的精确标识，不是可以随意填写的备注。OpenAI 的模型目录也会把供 API 使用的 Model ID 单独列出。

下面这些情况都可能导致模型无法找到：

• 大小写、横线、点号或版本号写错；
• 开头或结尾多了空格；
• 填入网页展示名，而不是接口使用的 Model ID；
• 当前 Key 没有该模型的访问权限；
• 模型已经下线、改名或只对部分项目开放；
• 模型不支持正在使用的端点。

最稳妥的做法，是从同一服务的模型清单或控制台复制 Model ID，不凭记忆手打。

四、先认清/responses与/chat/completions

OpenAI 当前官方 Quickstart 和文本生成入门以 Responses API 为主要示例，请求使用/v1/responses，正文包含model和input。

但“兼容 OpenAI 格式”不一定等于完整支持 OpenAI 当前所有 API。第三方兼容服务可能只实现/chat/completions，并要求使用messages。

这两类请求体不能混用：

/responses 通常搭配 input /chat/completions 通常搭配 messages

如果一个服务只支持/chat/completions，把/responses示例直接复制过去可能得到 404；只把路径改成/chat/completions、却仍然发送input，也可能因为请求体不符合要求而失败。

所以，先以服务商文档确认端点，再按该端点组织请求体。

五、Bash / cURL 最小测试

下面是/v1/responses的最小连通性示例，适用于 Bash、macOS/Linux 终端或 Git Bash：

curl--requestPOST"https://api.example.com/v1/responses"\--header"Content-Type: application/json"\--header"Authorization: Bearer YOUR_API_KEY"\--data'{ "model": "MODEL_ID", "input": "请只回复：连接成功" }'

这段请求里：

• https://api.example.com/v1是基础地址；
• /responses是具体端点；
• YOUR_API_KEY是鉴权凭证；
• MODEL_ID是模型标识；
• input是发送给模型的内容。

六、Windows PowerShell 最小测试

Windows PowerShell 可以使用原生的Invoke-RestMethod：

$headers= @{Authorization ="Bearer YOUR_API_KEY"}$body= @{model ="MODEL_ID"input ="请只回复：连接成功"}|ConvertTo-JsonInvoke-RestMethod-Method Post `-Uri"https://api.example.com/v1/responses"`-Headers$headers`-ContentType"application/json"`-Body$body

示例中的 Key 只是占位符。实际使用时，优先从环境变量或密钥管理工具读取真实 Key，不要把真实值长期写进脚本。

如果实际服务文档只提供/chat/completions，不要继续照搬以上请求；路径和请求体都要按该服务文档调整。

七、出现 401：优先检查鉴权层

按这个顺序排查：

1. 请求是否真的带上了Authorization请求头；
2. 格式是否为Bearer、一个空格、再接 Key；
3. 复制的是否是 API Key，而不是账号密码或项目编号；
4. Key 是否被撤销、过期或重新生成过；
5. Key 是否属于当前服务和当前项目；
6. 是否存在权限或 IP 限制；
7. 环境变量是否在当前终端或进程中生效。

不同兼容服务可能返回不同错误结构，因此还要阅读响应正文中脱敏后的code和message。

八、出现 404：优先检查地址与端点

404 不足以证明“整个服务挂了”。先检查：

1. 是否误用了官网登录地址，而不是 API 地址；
2. /v1是否重复或遗漏；
3. 客户端是否已经自动追加端点；
4. 服务是否真的支持/responses；
5. 请求方法是否为该端点要求的POST；
6. 返回的是结构化 JSON，还是网站、反向代理或验证页产生的 HTML。

如果返回 HTML，问题往往更接近域名、网站入口或反向代理；如果返回 JSON，则继续查看其中的错误类型。这只是定位线索，不能替代实际服务文档。

九、出现model_not_found：集中检查模型层

依次确认：

1. Model ID 是否逐字正确；
2. 是否误把展示名当成 Model ID；
3. 当前 Key 是否有该模型权限；
4. 模型是否仍然开放；
5. 模型是否支持当前端点；
6. 服务是否提供可用模型清单或查询接口。

不同兼容服务可能把此类问题返回为不同状态码，错误字段也不一定相同。不要仅凭model_not_found就断言平台采用了某一家 API 的完整错误规范。

十、不要同时修改三个变量

排查时一次只改一项：

1. 先确认地址和端点；
2. 再确认鉴权是否通过；
3. 最后确认 Model ID 和模型权限。

如果同时更换 Base URL、Key 和模型名，即使突然成功，也无法知道原问题在哪里；下次遇到同类故障仍然要从头猜。

最短、非流式请求最适合做首次连通性测试。先保存状态码和脱敏错误，再修改单一变量重试。

十一、API Key 绝对不能公开

真实 Key 不应进入：

• 浏览器前端或手机 App 安装包；
• GitHub 等代码仓库，包括私有仓库；
• 教程截图、录屏和终端历史；
• 评论区、群聊和公开工单；
• 网页源码、前端配置和客户端日志。

OpenAI 的 API Key 安全建议明确提醒：不要把 Key 部署到浏览器或移动端，不要提交到代码仓库，应优先使用环境变量或密钥管理服务。

如果怀疑 Key 已泄露，应立即轮换或撤销旧 Key，并检查近期用量。只删除截图、帖子或 Git 提交并不能让已经泄露的 Key 重新变安全。

十二、发起请求前的七项检查

• Base URL 来自当前服务的正式文档；
• 已确认客户端需要基础地址还是完整端点；
• /v1没有重复或遗漏；
• 端点与请求体属于同一种 API；
• 鉴权头格式正确；
• Model ID 来自当前服务的可用模型清单；
• 日志、截图和代码中没有真实 Key。

记住最简单的顺序：

地址决定去哪，Key 决定能否进入，Model ID 决定调用谁。

排查时可以在本地记录：客户端名称、隐藏域名后保留的路径结构（例如/v1/responses）、HTTP 状态码，以及脱敏后的code、message和 Model ID。不要在公开页面发送域名、API Key、完整请求头、账号信息、业务提示词或用户数据。

参考资料

• OpenAI Developer Quickstart
• OpenAI Text generation guide
• OpenAI Models
• OpenAI API error codes
• OpenAI API Key Safety

制作说明：本文使用 AI 辅助整理资料与校对，最终内容已由发布者审核。