简介:模型列表里明明躺着这个模型,一调用却报"不可用""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 |
更口语的版本:
普通 OpenAI 兼容工具 → chat/completions新版 OpenAI Responses 工具 → responsesClaude 原生工具 → messages
如果完全不确定, 绝大多数第三方工具先试 /v1/chat/completions 。原因是很多客户端宣称的”支持 OpenAI-compatible API”,实际只实现了 Chat Completions 这一套请求与响应结构,并不包含 Responses 或 Anthropic Messages。
一次 AI API 调用要成功,至少得同时满足三件事:
模型名(model ID)正确端点(endpoint)正确请求体(body)格式正确
三者错任何一个,都会失败。而失败信息往往高度雷同,比如:
model unavailableunsupported endpointinvalid request bodyschema mismatch404 Not Found
于是人的第一反应是”模型挂了””供应商跑路了”。真实情况常常是:模型好端端地在线,只是你把请求发到了另一扇门。举个例子,把 Anthropic 原生请求体发给 /v1/chat/completions,服务端解析 max_tokens、system 字段的位置对不上,返回的就是 schema 错误;而把完整 URL 填进”Base URL”输入框,工具又拼一次路径,结果就是干净的 404。
/v1/chat/completions:兼容性最好,成功率最高OpenAI Chat Completions 格式,事实上的行业通用语。请求体核心是 messages 数组,system / user / assistant 都是消息角色:
curl https://your-host/v1/chat/completions \-H "Authorization: Bearer $API_KEY" \-H "Content-Type: application/json" \-d '{"model": "deepseek-r1","messages": [{"role": "system", "content": "你是一位严谨的技术编辑"},{"role": "user", "content": "解释一下 Token 计费"}],"stream": false}'
用 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。
curl https://your-host/v1/messages \-H "x-api-key: $API_KEY" \-H "anthropic-version: 2023-06-01" \-H "Content-Type: application/json" \-d '{"model": "claude-sonnet-4","max_tokens": 1024,"system": "你是一位严谨的技术编辑","messages": [{"role": "user", "content": "解释一下 Token 计费"}]}'
很多配置面板要你填的是 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 参数与解析方式 |
/v1/chat/completions。user 消息、stream: false,把工具变量全部排除掉。curl 通了说明是工具配置问题,curl 不通说明是端点、鉴权或模型 ID 问题。Authorization: Bearer,Anthropic 用 x-api-key + anthropic-version。端点混乱的根源,是每家供应商各说各的方言。工程上有两条路可以显著降低成本:
一是 统一网关 。把不同协议收敛到一层 OpenAI 兼容接口后面,业务代码只认一种格式,切换模型时改配置不改代码。像 Chatbox 这类客户端就是靠”自定义模型提供方 + Base URL + 路径 + API Key + 模型名”五件套完成接入的,配一次即可在不同模型间切换。
二是 先选型再联调 。在动手写代码之前,就把候选模型的能力边界、上下文长度、计费方式和调用成本比清楚,能避免大量”配好了才发现模型根本不适合这个场景”的返工。百度智能云词元所作为大模型撮合交易服务平台,提供的正是这两件事:模型发现与选型、模型价格与性能对比,以及多模型统一 API 接入,把”选哪个模型”和”怎么接进来”合并到同一个入口^[词元所]^。对需要同时评估多家模型、又要控制调用成本的团队来说,先在这里做一轮对比,再回到代码里联调,通常比”边试边换”更快。
stream: true 时返回的是增量 chunk,需要按 delta 逐段拼接;把它当完整 JSON 解析会得到空结果。一句话总结:遇到”模型不可用”,先别怀疑模型,按顺序检查端点、Base URL、请求体、模型 ID、鉴权头这五处。绝大多数所谓的”模型挂了”,最后都停在前两项。