API 报 model not found / 模型不存在?六个原因和对应查法(2026)
报「模型不存在」时,常见原因是名字、端点、权限三者之一对不上,不一定是模型下架了。按顺序排查,两分钟能定位。附一个能直接抄的最小验证命令和一张「症状 → 根因 → 解法」对照表。
1. 第一步永远是拉一次模型列表
多数兼容 OpenAI 协议的端点都提供 `GET /v1/models`。用你正在用的那个 key 和那个 base_url 调一次,把返回的清单和你填的名字逐字对比。这一步花不到一分钟,却能一次性分出两大类:名字在清单里,说明端点列出了模型,再用同一个 key 发一条最短的实际调用验证权限;名字不在清单里,继续查名字、端点或权限。下面的命令可以直接抄,把 key 和地址换成你自己的。
curl -s https://YOUR_BASE_URL/v1/models \
-H "Authorization: Bearer $YOUR_KEY" | grep -o '"id":"[^"]*"'2. 名字:拼写、大小写、版本后缀、前缀
常见原因之一是名字差一点。典型的几种:少了或多了一个连字符;版本号写成了别的格式;漏了或多了日期后缀;从聚合平台复制来的名字带着「厂商名/」前缀,而当前端点不认这个前缀。有的服务商对大小写敏感,有的不敏感,别赌。最稳的做法是从模型清单里复制,不要凭记忆手打,也不要从半年前的教程里抄——模型名会随版本更新变化。
3. base_url 的坑:结尾那个 /v1
这一点经常被问到。有的客户端要求 base_url 以 `/v1` 结尾,有的会自己补,补两次或一次都没补,请求就打到了错误的路径。填错的表现很有迷惑性:不一定报 404,也可能报「模型不存在」——因为请求打到了一个存在但不认识这个模型的地方。以 cocodot 为例:OpenAI SDK / 客户端的 base_url 填 `https://cocodot.co/api/ai/v1`,Anthropic SDK / Claude Code 填 `https://cocodot.co/api/ai`,两者只差结尾的 /v1。排查方法:把实际发出的完整 URL 打印出来看一眼,不要相信配置文件里写的是什么。
没有海外卡也能调大模型:cocodot 的 OpenAI 兼容 API,改 base_url 就能调在售型号。
支付宝 / 微信支付(人民币)、USDT / USDC 充值 · 按 token 计费 · 改 base_url 即可接入
4. 「所有模型都说不存在」:先查端点和 key
如果你换了好几个模型名都报不存在,那问题不在名字上。这时更可能是 base_url、鉴权头、或者请求路径的问题——请求根本没到该到的地方。还有一种容易忽略的情况:环境变量覆盖了配置文件,你以为在用 A 的 key 和地址,实际进程读到的是 B。先用一个确定支持的模型和最短的请求体验证连通性,通了再回来调模型名。先解决连通,再解决具体模型,顺序反了会浪费很多时间。鉴权本身报错(401 一类)的排查是另一回事,别和本篇混在一起查。
5. 权限:key 属于谁、模型开没开
「名字没错、端点没错,还是不存在」时,看权限。同一家服务商下,不同账号、不同项目、不同分组能用的模型可能不一样,你的 key 可能恰好属于一个没开这个模型的项目。有的模型需要单独申请或满足一定条件才开放。先拉模型清单核对名字,再到控制台确认权限。清单没有该名字也可能是端点或命名不同,不能直接认定没权限。网页聊天能用某个模型,不代表 API 权限也开了,这是两套体系。
6. 官方名和服务商代号可能都对,也可能只有一个对
通过中转或聚合服务调用时,同一个模型可能有两种可用名字:厂商官方名(如 `claude-sonnet-5`)和服务商自己的代号。有的服务商两种都认,有的只认一种,有的要求加前缀。别假设,查一次文档或模型列表就知道。 cocodot 这边两种都可以:官方名和代号(如 `mcs-6`)都能用,写法以模型清单里的原样为准;模型下拉清单在 `GET https://cocodot.co/api/ai/v1/models`(公开,无需鉴权),带实时价格的全量清单在 `GET https://cocodot.co/api/ai/models`,网页版在 cocodot.co/pricing#models。
7. 确实下架了怎么办
模型下架是会发生的,尤其是预览版和带日期后缀的快照版本;另一种情况是通用别名改指向了新版本,行为变了但名字没报错。判断方法是查厂商的发布记录和弃用公告,以官方页面当前说明为准。真下架了只能换一个——这时候用 OpenAI 兼容接口的好处体现出来:换模型名是改一个字符串,不用动 SDK、不用重新对接。生产代码里建议把模型名放进配置而不是写死在代码里,并在启动时用模型清单校验一次,下架时能第一时间发现。
8. 一份两分钟排查清单
1. 打印实际请求的完整 URL,确认 base_url 和路径。2. 打印进程实际读到的 key 前几位,确认没被环境变量覆盖。3. 用同一个 key 和地址拉 `/v1/models`。4. 从清单里复制模型名替换你填的名字。5. 名字不在清单里:查控制台开通状态或换 key。6. 名字在清单里还报错:检查请求体里 model 字段的拼写和位置。7. 都没问题:查厂商发布记录确认是否下架。其它常见报错:上下文超限见 /hub/context-length-exceeded-fix,限流见 /hub/api-429-rate-limit-concurrency-china,过载见 /hub/claude-api-529-overloaded。
症状 → 根因 → 解法
| 症状 | 根因 | 解法 |
|---|---|---|
| 换个模型名就好了 | 名字拼错、大小写或版本后缀不对 | 从 /v1/models 返回里复制名字,别手打 |
| 所有模型都说不存在 | base_url 指错或路径多 / 少了 /v1 | 打印实际请求的完整 URL |
| 同事的 key 能用,你的不行 | key 属于另一个账号 / 项目 / 分组 | 用同一个 key 拉模型清单对比 |
| 别的模型正常,只有这个不行 | 该模型未开通或有门槛 | 查服务商控制台的开通状态 |
| 官方名可以、代号不行(或反过来) | 用了对方没有的别名或别家前缀 | 看服务商文档的命名规则 |
| 昨天还能用,今天突然不行 | 模型下架或别名改指向 | 查厂商发布记录,换成清单里的名字 |