模型明明存在，为什么一调用就提示“不可用”？多数是 API 端点填错了

一、问题不在模型，而在“门牌号”

最近不少开发者在接入 AI 接口时，都会遇到一类非常相似的现象：

• 在模型列表里明明能看到某个模型，代码一调用就报错；
• 同一个模型在某个客户端里可以正常使用，换一个工具就提示不可用；
• API Key 检查过没问题，账户额度也充足，但依然返回 model unavailable；
• 有的文档写 /v1/messages，有的工具又要求填 /v1/chat/completions，到底应该听谁的？

这类问题表面上看起来像是“模型挂了”或者“权限没开”，但真正的原因，往往比想象中更简单，也更隐蔽：

API 端点填错了。

更准确地说，是端点、请求格式、SDK 类型三者没有对齐。很多开发者关注的焦点一直放在模型名称和密钥上，却忽略了端点本身就是协议的一部分。端点选错，后面的请求体、响应解析、错误处理都会跟着错。

---

二、先给结论：不确定时，优先这样选

如果你现在正卡在配置阶段，只想尽快把工具跑通，可以先记住下面这个表：

使用场景	通常应选择的端点
OpenAI 兼容工具、中转服务、自定义 Base URL	/v1/chat/completions
明确要求使用新版 Responses 协议的工具	/v1/responses
Claude 原生 SDK 或 Anthropic 风格工具	/v1/messages

用更直白的方式表达：

普通 OpenAI 兼容工具        -> /v1/chat/completions
新版 Responses 协议工具     -> /v1/responses
Claude 原生工具             -> /v1/messages

如果你完全无法判断工具属于哪一类，那么在大多数第三方工具中，优先尝试：

/v1/chat/completions

原因在于，目前市面上大量客户端、插件和中间服务在宣称“支持 OpenAI 兼容 API”时，实际实现的是 Chat Completions 这一套协议。它已经成为事实上的通用约定。

---

三、为什么端点错了，看起来却像“模型不可用”？

一次完整的 AI API 调用，并不仅仅是“选择模型并发送一句话”那么简单。从协议层面看，它至少需要同时满足三个条件：

模型名称正确
端点路径正确
请求体格式正确

三者缺一不可。

而实际开发中，常见的错误组合包括：

• 模型名写对了，但端点不支持当前请求体格式；
• 端点路径正确，但请求体是按照另一套 API 规则构造的；
• 工具内部用的是某类 SDK，却被手动填成了另一类原生接口；
• Base URL 填的是完整端点，而工具本身会自动拼接路径，导致重复或错位。

所以最终看到的现象，往往是下面这些错误中的一种：

model unavailable
unsupported endpoint
invalid request body
schema mismatch
404 not found

从业务侧看，这些错误都指向“模型不可用”；但从工程侧看，它们大多只是说明：

请求没有到达正确的处理逻辑。

模型可能一直在正常运行，只是调用方走错了门。

---

四、/v1/chat/completions：最常见，也最容易接入成功

/v1/chat/completions 是目前最普遍的端点形式。

它的基本思路是：客户端将一段对话历史作为消息数组发送给服务端，服务端返回一个补全结果。请求体通常包含 model 和 messages 两个核心字段。

一个典型的请求结构如下：

{
  "model": "example-model",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Explain the concept of API endpoint."
    }
  ]
}

这种格式的优势在于：

1. 结构简单，容易理解；
2. 生态支持广泛；
3. 大多数兼容工具、客户端和中间层都能识别；
4. 调试时直观，错误信息通常也相对清晰。

因此，如果你只是希望快速接入一个对话模型，并且工具没有特别说明使用哪种协议，/v1/chat/completions 是风险最低的选择。

---

五、/v1/responses：新协议，但不是所有工具都支持

/v1/responses 是一套较新的交互协议。它与传统 Chat Completions 的最大区别在于，不再单纯围绕“消息列表”组织请求，而是引入了更抽象的能力封装。

在一些新式工具中，这种端点可以支持更丰富的返回结构、工具调用方式以及结果类型。但这并不意味着它可以随意替换 /v1/chat/completions。

关键点在于：

• 并非所有模型或网关都实现了 /v1/responses；
• 也并非所有客户端都按相同方式实现了该协议；
• 如果工具明确要求使用该端点，才应该填写它；
• 如果工具只是“兼容 OpenAI”，通常仍然指的是旧版 Chat Completions。

因此，/v1/responses 不应被视为“高级版”或“默认升级版”。它只是另一套协议，适用于特定工具链。

---

六、/v1/messages：面向原生 SDK 的端点

/v1/messages 常见于某类原生 AI 接口体系。例如 Claude / Anthropic 风格的 SDK 中，默认使用 /v1/messages 作为消息创建端点。

它的请求格式与 Chat Completions 存在明显差异。一个典型结构如下：

{
  "model": "example-model",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What is an API endpoint?"
    }
  ]
}

虽然看起来相似，但字段约定、返回结构、错误码含义以及流式输出机制都可能不同。

常见问题包括：

• 把 /v1/messages 填到 OpenAI SDK 中；
• 把 /v1/chat/completions 的请求体原样发给 /v1/messages；
• 在需要 Base URL 的地方填了完整路径；
• 在需要完整路径的地方只填了域名。

这些错误最终都可能表现为“模型不可用”或“请求格式错误”。

---

七、如何判断当前工具应该使用哪个端点？

实际开发中，可以按照以下顺序快速判断：

1. 查看工具是否明确标注协议类型

如果工具说明里出现“OpenAI compatible”“Chat Completions”“Responses API”等关键词，直接按其要求填写即可。

2. 查看 SDK 类型

如果使用的是某类原生 SDK，通常 SDK 内部已经约定了端点路径。此时应优先以 SDK 默认配置为准，而不是手动修改端点。

3. 查看请求体格式要求

如果工具允许自定义请求体，可以观察它要求填写的字段：

• 出现 messages 数组，且每项包含 role 和 content，多为 Chat Completions 风格；
• 如果要求 input 或其他抽象字段，则可能是 Responses 风格；
• 如果字段名、分页方式、停止条件与常见格式不同，则可能属于某类原生协议。

4. 使用最小化测试请求

在不确定时，可以用最简单的请求体先测试连通性：

{
  "model": "example-model",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}

选择一个最基础的 Text Generation 场景，避免同时引入工具调用、流式输出、结构化输出等复杂参数。这样可以更快定位问题来源。

---

八、常见错误配置与排查建议

以下列举几类典型错误，以及对应的排查思路。

错误一：Base URL 中重复拼接端点

例如工具要求填写：

https://api.example.com/v1

但用户填写成：

https://api.example.com/v1/chat/completions

此时工具可能还会自动拼接 /chat/completions，最终路径变成：

https://api.example.com/v1/chat/completions/chat/completions

解决方案：Base URL 通常只填写到版本号或域名层级，不要提前补全端点路径。

错误二：工具默认端点与目标不一致

有些工具默认使用 /v1/chat/completions，但用户配置的是一个仅支持 /v1/messages 的接口地址。此时即使模型名称正确，也无法匹配处理逻辑。

解决方案：确认工具是否支持切换协议类型；如果不支持，则更换客户端或中间层。

错误三：请求体跨协议混用

将 Chat Completions 的 messages 字段原样发给 Responses 或 Messages 端点，可能不会立即报错，而是返回结构异常或空结果。

解决方案：严格按照目标端点的字段定义构造请求体，不要从旧项目直接复制。

---

九、写在最后

“模型不可用”并不总是模型的问题。

在大量实际案例中，模型本身状态正常，真正的原因是：

• 端点选择错误；
• 请求体格式不匹配；
• SDK 与协议类型不一致；
• Base URL 配置不完整或重复拼接。

对于开发者来说，排查此类问题时，可以先将注意力从“模型权限是否被限制”转移到“请求是否到达了正确的处理逻辑”。按照以下顺序检查，通常能更快定位问题：

Base URL 是否正确
模型名称是否正确
端点路径是否匹配
请求体格式是否匹配
SDK 是否与协议类型一致

在绝大多数情况下，只需要调整其中一项，原本“不可用”的模型就会恢复正常。理解 API 端点之间的差异，不仅能减少无效排查时间，也能帮助我们在不同工具链之间更稳定地迁移和集成。