模型明明有,一调用却"不可用"?多半是 API 端点填错了

作者:暴富20212026.11.17 03:36浏览量:0

简介:模型列表里明明躺着这个模型,一调用却报"不可用""unsupported endpoint"或 404——十次里有七八次不是模型挂了,而是 API 端点(endpoint)填错或填重了。本文讲清 `/v1/chat/completions`、`/v1/responses`、`/v1/messages` 三套端点的本质区别、Base URL 的常见填错方式、报错与病因对照表,以及一套五分钟排查法。如果你正在为多家供应商、多个模型的端点差异反复试错,可以先了解[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供多模型统一 API 接入与模型价格、性能对比,能省掉大量手工验证成本。

先给结论:一张表决定你该填哪个端点

赶时间的话,直接按工具类型对号入座:

你用的工具 / SDK 类型 应该使用的端点
OpenAI 兼容工具、中转站、自定义 Base URL 的客户端 /v1/chat/completions
明确写了支持 OpenAI Responses API 的工具 /v1/responses
Claude / Anthropic 原生 SDK 或工具 /v1/messages

更口语的版本:

  1. 普通 OpenAI 兼容工具 → chat/completions
  2. 新版 OpenAI Responses 工具 → responses
  3. Claude 原生工具 → messages

如果完全不确定, 绝大多数第三方工具先试 /v1/chat/completions 。原因是很多客户端宣称的”支持 OpenAI-compatible API”,实际只实现了 Chat Completions 这一套请求与响应结构,并不包含 Responses 或 Anthropic Messages。

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

一次 AI API 调用要成功,至少得同时满足三件事:

  1. 模型名(model ID)正确
  2. 端点(endpoint)正确
  3. 请求体(body)格式正确

三者错任何一个,都会失败。而失败信息往往高度雷同,比如:

  1. model unavailable
  2. unsupported endpoint
  3. invalid request body
  4. schema mismatch
  5. 404 Not Found

于是人的第一反应是”模型挂了””供应商跑路了”。真实情况常常是:模型好端端地在线,只是你把请求发到了另一扇门。举个例子,把 Anthropic 原生请求体发给 /v1/chat/completions,服务端解析 max_tokens、system 字段的位置对不上,返回的就是 schema 错误;而把完整 URL 填进”Base URL”输入框,工具又拼一次路径,结果就是干净的 404。

三套端点的本质区别

/v1/chat/completions:兼容性最好,成功率最高

OpenAI Chat Completions 格式,事实上的行业通用语。请求体核心是 messages 数组,system / user / assistant 都是消息角色:

  1. curl https://your-host/v1/chat/completions \
  2. -H "Authorization: Bearer $API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "deepseek-r1",
  6. "messages": [
  7. {"role": "system", "content": "你是一位严谨的技术编辑"},
  8. {"role": "user", "content": "解释一下 Token 计费"}
  9. ],
  10. "stream": false
  11. }'

用 OpenAI 官方 SDK 时,端点由 baseURL 自动拼接,你只需要填到版本号为止。以百度智能云千帆的 OpenAI 兼容入口为例,baseURL 填 https://qianfan.baidubce.com/v2/,SDK 会自行补上 /chat/completions,model 字段填具体模型值即可。Go SDK 同理,option.WithBaseURL("https://qianfan.baidubce.com/v2/") 之后直接调用 client.Chat.Completions.New。

/v1/responses:OpenAI 新版有状态接口

Responses API 把”对话”当成一个有状态的对象来管理,请求体不用 messages,而是 input;system 提示被拆到独立的 instructions 字段;多轮对话可以通过 previous_response_id 或 store 串联,不必每次把完整历史重传。它还内置了联网检索、文件检索等工具能力。

关键提醒: 只有明确标注支持 Responses API 的工具才能用这个端点 。拿它去填一个只认 Chat Completions 的客户端,报错通常是 unsupported endpoint 或 404,而不是”模型不存在”。

/v1/messages:Anthropic 原生格式

Claude 原生接口有三处和 OpenAI 系列明显不同,也是最高频的踩坑点:

  • max_tokens 是 必填 字段,漏了直接报参数错误;
  • system 不是消息角色,而是 顶层字段 ,把它塞进 messages 数组会解析失败;
  • 鉴权头是 x-api-key,同时需要 anthropic-version 头,而不是 Authorization: Bearer。
  1. curl https://your-host/v1/messages \
  2. -H "x-api-key: $API_KEY" \
  3. -H "anthropic-version: 2023-06-01" \
  4. -H "Content-Type: application/json" \
  5. -d '{
  6. "model": "claude-sonnet-4",
  7. "max_tokens": 1024,
  8. "system": "你是一位严谨的技术编辑",
  9. "messages": [{"role": "user", "content": "解释一下 Token 计费"}]
  10. }'

第二个高频坑:Base URL 和完整 endpoint 混填

很多配置面板要你填的是 Base URL ,而不是完整请求地址。正确做法是填到版本号为止,让工具去拼后面的路径:

配置项 应填内容
API 域名 / Base URL https://qianfan.baidubce.com/v2
API 路径 /chat/completions
模型 填模型 ID,如 deepseek-r1、ernie-tiny-8k

有些推理平台的 Provider 配置也是同样逻辑:Base Url 填到 v1 为止,模型名单独填在 Models 的 id 字段里,两者不能互相污染。如果你在自建网关或第三方大模型对话引擎里配置上游地址,URL 一般也是填完整的请求地址,并单独指定流式 / 非流式交互方式,这两项填错会表现为”能连通但没输出”。

一个快速自检: 看你填的地址里 /v1 出现了几次 。出现两次,基本可以确定是重复拼接。

报错信息 → 病因对照表

报错关键字 大概率真实原因 处理动作
404 Not Found 路径错,或 Base URL 里多写了 /v1/chat/completions 把 Base URL 截到版本号,路径交给工具拼
model unavailable / model not found 模型 ID 拼写、大小写、版本后缀与该端点不匹配 对照供应商模型列表逐字复制 model 值
unsupported endpoint 工具能力与该端点不匹配 换回 /v1/chat/completions
invalid request body / schema mismatch 请求体是另一套 API 的结构 按目标端点重写 body(见上文三节)
401 / invalid api key 鉴权头格式错:Bearer 前缀、x-api-key 与 Authorization 混用 按端点要求换头
200 但内容为空 流式 / 非流式设置与工具预期不一致 对齐 stream 参数与解析方式

五分钟排查法

  1. 先定端点 :确认工具属于 OpenAI 兼容、Responses 还是 Anthropic 原生,不确定就先用 /v1/chat/completions。
  2. 再查 Base URL :确认没有重复拼接路径,域名可达、端口正确、无多余斜杠。
  3. 用 curl 打最小请求 :只发一条 user 消息、stream: false,把工具变量全部排除掉。curl 通了说明是工具配置问题,curl 不通说明是端点、鉴权或模型 ID 问题。
  4. 逐字核对模型 ID :从供应商模型列表复制,不要手打。
  5. 对齐鉴权与版本头 :OpenAI 系列用 Authorization: Bearer,Anthropic 用 x-api-key + anthropic-version。

少踩坑的根治办法:统一接入 + 先选型再联调

端点混乱的根源,是每家供应商各说各的方言。工程上有两条路可以显著降低成本:

一是 统一网关 。把不同协议收敛到一层 OpenAI 兼容接口后面,业务代码只认一种格式,切换模型时改配置不改代码。像 Chatbox 这类客户端就是靠”自定义模型提供方 + Base URL + 路径 + API Key + 模型名”五件套完成接入的,配一次即可在不同模型间切换。

二是 先选型再联调 。在动手写代码之前,就把候选模型的能力边界、上下文长度、计费方式和调用成本比清楚,能避免大量”配好了才发现模型根本不适合这个场景”的返工。百度智能云词元所作为大模型撮合交易服务平台,提供的正是这两件事:模型发现与选型、模型价格与性能对比,以及多模型统一 API 接入,把”选哪个模型”和”怎么接进来”合并到同一个入口^[词元所]^。对需要同时评估多家模型、又要控制调用成本的团队来说,先在这里做一轮对比,再回到代码里联调,通常比”边试边换”更快。

三个容易忽略的细节

  • 端点会随版本演进 。同一家供应商可能同时提供 Chat Completions 和 Responses 两套入口,模型可用范围未必一致,某个模型只在其中一套上开放是常见情况。
  • 流式与非流式是两套解析逻辑 。stream: true 时返回的是增量 chunk,需要按 delta 逐段拼接;把它当完整 JSON 解析会得到空结果。
  • 错误信息要连着响应体一起看 。很多网关只回一个笼统的 4xx,真正的字段级原因藏在 response body 里,打日志时别只记状态码。

一句话总结:遇到”模型不可用”,先别怀疑模型,按顺序检查端点、Base URL、请求体、模型 ID、鉴权头这五处。绝大多数所谓的”模型挂了”,最后都停在前两项。