模型调用报“不可用”？多半是API端点选错了

一、问题的表象与本质

在接入AI API的过程中，不少开发者都遇到过类似的困惑：

• 模型列表里明明能看到某个模型，一调用却返回错误；
• 同一个模型，在A工具里能正常对话，换到B客户端就失败；
• API Key 有效、账户余额充足，却依然提示模型不可用；
• 一份文档写的是某个路径，另一个工具却要求填另一个路径，到底该信谁？

这些现象表面上像是在说“模型挂了”，但绝大多数情况下，模型服务本身是健康的。真正的问题出在调用链路的入口选错了——也就是 API 端点（Endpoint）与请求格式不匹配。

一次成功的 AI API 调用，至少要同时满足三个条件：

模型标识正确
端点路径正确
请求体格式与端点匹配

三者中任意一个不满足，服务端都可能返回错误。而错误信息往往被统一包装成“模型不可用”“请求无效”“端点不支持”之类的模糊提示，于是排查方向就被误导了。

二、三类常见聊天端点及其定位

当前业界围绕对话式 AI 的 API，形成了若干种常见的请求风格。它们看起来都和“聊天”“生成回复”有关，但背后是不同设计理念下的接口约定，不能随意混用。

1. Chat Completions 风格

这是目前兼容性最广、生态支持最多的一类端点。它的核心特征是：请求体中以 messages 数组承载对话历史，每条消息带有 role（如 system、user、assistant）和 content 字段，响应中返回一个 choices 列表。

{
  "model": "your-model-name",
  "messages": [
    {"role": "system", "content": "你是一个严谨的技术助手"},
    {"role": "user", "content": "解释一下什么是端点"}
  ]
}

大量第三方客户端、聚合网关、自建代理工具所宣称的“兼容主流 API 格式”，通常指的就是这一套约定。因此，当你使用一个通用型客户端、自定义 Base URL 的中转服务，或者不确定对方支持哪种风格时，优先尝试 Chat Completions 风格，成功率最高。

2. Responses 风格

这是一类相对较新的端点设计，强调以更结构化的方式描述“一次生成任务”，在请求组织和响应结构上与 Chat Completions 有明显差异。它并非简单地换了个路径，而是对输入输出模型做了重新抽象。

典型表现是：请求体不再以 messages 为核心，响应也不再是简单的 choices 列表。如果工具明确声明自己使用这一类接口，就应当按它的文档构造请求；反之，把一个 Chat Completions 格式的请求体硬塞给这类端点，通常会得到请求体校验失败或字段不识别之类的错误。

3. Messages 风格

这是一类面向特定模型家族原生 SDK 的端点约定。它的请求体同样使用 messages 数组，但字段命名、系统提示的传递方式、响应结构都与 Chat Completions 不同。例如系统提示往往不是作为一条 role 为 system 的消息，而是独立字段；响应内容也常以内容块数组的形式返回。

{
  "model": "your-model-name",
  "system": "你是一个严谨的技术助手",
  "messages": [
    {"role": "user", "content": "解释一下什么是端点"}
  ],
  "max_tokens": 1024
}

注意这个例子与前面的 Chat Completions 示例在结构上的差异：系统提示的位置不同，参数命名也不同。这类端点必须搭配对应的原生 SDK 或明确支持该风格的工具使用。

4. 快速选型参考

你使用的工具类型	大概率应选用的端点风格
通用兼容型客户端、聚合网关、自定义 Base URL	Chat Completions 风格
明确声明使用 Responses 风格接口的工具	Responses 风格
特定模型家族的原生 SDK 或配套工具	Messages 风格

用一句话概括：通用兼容工具走 Chat Completions，声明新式接口的走 Responses，原生 SDK 走 Messages。 完全不确定时，先从 Chat Completions 方向试起。

三、为什么端点错了会伪装成“模型不可用”

服务端在处理请求时，会依次进行多层校验：路由是否匹配、请求体是否符合该端点的 schema、模型标识是否在该端点支持下可用。任何一层失败，都可能被上层统一转换为一个笼统的错误码。

常见错误提示及其真实含义：

• model unavailable：不一定是模型下线，也可能是该端点不承载这个模型；
• unsupported endpoint：路径本身就不对，或者方法与路径组合不被接受；
• invalid request body / schema mismatch：请求体是另一套 API 的格式；
• 404 not found：Base URL 与端点路径拼接后指向了不存在的地址。

这里还有一个高频陷阱：Base URL 与完整端点的混淆。很多工具要求填的是 Base URL（例如以版本号结尾的基础路径），由工具自己再拼接具体端点；而有些工具要求填的是完整端点路径。如果把完整路径填进了 Base URL 输入框，最终拼接出来的地址就会重复或错位，表现为 404 或路由不匹配。

正确：Base URL = https://example-host/api/v1
      工具内部拼接 → .../api/v1/chat/completions
错误：Base URL = https://example-host/api/v1/chat/completions
      工具再拼接 → .../api/v1/chat/completions/chat/completions

同理，把 Chat Completions 的请求体发给 Messages 风格端点，字段名对不上，就会得到 schema 校验失败；反之亦然。这些错误在客户端看来，都长得像“模型有问题”。

四、系统化排查流程

遇到“模型明明有却调不通”，建议按以下顺序排查，避免盲目更换模型或重建密钥：

第一步：确认端点风格与工具匹配。 查看工具的配置项名称：写的是 Base URL 还是完整端点？文档声明支持哪种请求格式？据此选定风格，不要凭直觉填。

第二步：确认路径拼接结果。 把 Base URL 与工具最终请求的完整路径手工拼一遍，确认没有重复段、没有缺失版本号、没有多余斜杠。

第三步：用最小请求体验证。 抛开业务代码，用最简单的请求体直接调用一次，观察返回的是路由错误、schema 错误还是模型错误，从而判断问题出在哪一层。

第四步：核对模型标识与端点支持范围。 某些模型只在特定风格端点下开放，换个端点就查不到，这属于正常的服务端能力边界，而非故障。

第五步：核对鉴权方式。 不同风格端点的鉴权头字段可能不同，密钥有效不代表请求头格式正确。

五、配置检查清单

为减少重复踩坑，可以把以下检查项固化为团队规范：

• 明确记录每个工具使用的端点风格，而非只记录“能用的地址”；
• 区分 Base URL 与完整端点，配置项旁注明期望格式；
• 请求体模板按风格分文件管理，避免混用字段；
• 错误日志中保留完整请求路径与响应体，便于定位是路由层还是 schema 层失败；
• 新接入工具时，先用最小请求验证连通性，再接入业务逻辑。

六、小结

“模型不可用”是一个高度概括的错误表象，它背后可能是路由、格式、鉴权、模型支持范围等任一环节的问题。掌握三类常见端点的定位与差异，理解 Base URL 与完整端点的拼接逻辑，再配合一套固定的排查顺序，就能把大部分“玄学故障”还原为可复现、可修复的配置问题。模型通常没有挂，挂住的往往是我们填写配置时的那一行。