OpenAI API 返回 404 model not found 怎么解决？

更新于 2026-10-30 · yunwu.cyou

简答：先不要重复生成 API Key：用同一个 Base URL 和 Key 请求模型列表，确认实际可见的 model ID；再用该 ID 发一次最小请求。若模型列表本身返回 404，优先查 Base URL、/v1 是否重复或请求发错主机；若列表成功但模型调用返回 model_not_found，再查模型 ID、接口类型、项目权限和模型状态。对于兼容接口，本文不能核实固定地址或固定模型目录，必须以当前控制台和实际响应为准。

定义：404 model not found 表示当前请求找不到或无法访问指定的模型资源，不等同于普通网页不存在，也不一定只代表模型名称拼写错误。

先做这一步：用同一个地址和 Key 查询可见模型

404 排查最容易走偏的地方，是只盯着错误信息，却没有确认客户端最终发出的完整 URL 和 model 值。先把配置页面中的地址、Key 和模型名复制到终端，分别验证模型列表与最小对话请求。

OpenAI 官方的模型列表接口会返回可用于 API 请求的模型标识符；模型对象还可能包含可选的关闭日期字段。可参考 List models 官方参考。官方错误说明也把 404 归为请求资源不存在，把权限问题单独归为 PermissionDeniedError，因此应按响应码和错误字段分流，而不是把所有 404 都当作 Key 失效。

重要边界：截至 2026-10-30，本文没有核实某个兼容平台的固定 Base URL、固定 /v1 规则或可用模型目录。使用兼容接口时，请从当前控制台复制地址和模型 ID；不要把下方的官方地址或示例模型名直接替换到其他平台。

最小 curl 验证：先查模型，再发一次请求

下面的命令是字段填写模板，不是某个兼容平台的固定配置。把 BASE_URL、API_KEY 和 MODEL_ID 替换为你实际核验过的值。密钥不要写进代码仓库、截图、Shell 历史或前端页面。

BASE_URL="https://api.openai.com/v1"   # 官方 API 示例；兼容接口请替换为控制台给出的地址
API_KEY="替换为你的 API Key"
MODEL_ID="替换为 /models 返回的精确 id"

curl -sS "$BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

curl -sS "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复 OK\"}]}"

1. 模型列表请求应返回 JSON，检查 data[].id，不要使用模型展示名、宣传名称或带多余空格的文本。
2. 如果官方接口返回列表但兼容接口返回 HTML 404，说明请求可能没有到达兼容 API 的正确路径，优先检查 Base URL 和路径拼接。
3. 如果列表成功但第二个请求返回 model_not_found，把 MODEL_ID 重新从同一服务的列表结果复制，不要混用其他平台的模型名。
4. 如果服务只支持 Responses API，Chat Completions 请求可能不适用；反之也不能仅凭模型名称推断端点兼容性。应查看当前服务文档或控制台说明。

OpenAI 的 Chat Completions 参考要求请求体包含 model 和消息内容，并明确提示不同模型的参数支持可能不同，可查看 Create chat completion 官方参考。新项目还可以对照 Text generation 官方指南确认是否应使用 Responses API。

Python 与 Node.js：避免 SDK 把地址或模型改错

如果 curl 能成功而 SDK 失败，重点查看 SDK 初始化时的 base_url、自动补全路径和实际发送的模型字段。不同 SDK 版本的默认行为可能变化，不能假设它一定会自动处理或删除 /v1。

Python 最小请求

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url=os.environ["BASE_URL"]
)

model_id = os.environ["MODEL_ID"]
response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "只回复 OK"}],
)
print(response.choices[0].message.content)

Node.js 最小请求

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: process.env.BASE_URL,
});

const response = await client.chat.completions.create({
  model: process.env.MODEL_ID,
  messages: [{ role: "user", content: "只回复 OK" }],
});

console.log(response.choices[0].message.content);

这里的环境变量必须由你在本地或服务端设置，示例中的三个值均为占位字段。OpenAI 官方文档建议使用 Bearer 认证，并将 API Key 从环境变量或密钥管理服务加载，而不是放在浏览器或客户端代码中；可查看 API Reference Overview 的认证说明。

排查 SDK 时记录以下非敏感信息：请求时间和时区、最终主机与路径、HTTP 状态码、错误类型、错误码、请求 ID（如响应提供）以及脱敏后的模型 ID。不要提交完整 Authorization 头或完整请求体中的隐私数据。

按 404 原因逐项处理：模型名、路径、权限与下线

OpenAI 官方弃用页面说明，模型退役会影响依赖旧模型的软件，并建议通过 GET /v1/models 检查模型对象中的可选 shutdown_date。因此，旧教程里的模型名不能作为当前可用性的证明，应以当前模型目录和服务控制台为准，参考 Deprecations 官方页面。

如果你使用的是兼容网关，平台可能只暴露部分模型，也可能使用自己的模型 ID、分组或路由名。本文没有核实这些平台内部规则，不能据此推断某个具体模型一定可用；最可靠的顺序仍是“同一地址和 Key 查询模型列表—复制精确 ID—发送最小请求—再回到客户端配置”。

仍然失败时：用错误码和请求记录继续分流

返回普通网页 404：通常先查主机、路径、反向代理和重复的 /v1，因为请求可能没有进入 API 路由。

返回 JSON 且含 model_not_found：重点查模型 ID、Key 所属项目、模型可见范围和模型状态。不要通过盲目重试解决模型不存在问题。

变成 401：检查 Bearer 头、Key 是否过期或被撤销，以及环境变量是否为空。官方错误文档将认证失败归因于无效、过期或撤销的凭证。

变成 403：检查账户、项目、分组或资源权限；不要继续改模型名来掩盖权限问题。

变成 429：这是限速或用量相关方向，应先查看响应中的错误字段和 Retry-After，不要把限流当成模型不存在。只有临时限流才考虑遵守服务端等待时间后重试；余额、权限和未知错误不应自动重试。

提交支持请求时，保留模型 ID、错误原文、状态码、时间及时区、最终请求路径和脱敏后的请求信息。官方错误指南也建议提供模型、错误消息、请求数据与请求时间，同时删除密钥等敏感内容，可参考 Error codes 官方指南。

常见问题

404 model not found 是不是 API Key 错了？

不一定。OpenAI 官方将 404 的 NotFoundError 解释为请求资源不存在，将权限问题单独列为 PermissionDeniedError。先查询同一地址的模型列表：如果列表也失败，查地址和认证；如果列表成功但调用失败，再查模型 ID、权限和端点支持。

Base URL 要不要写 /v1？

不能一概而论。官方 OpenAI API 的模型列表路径示例是 /v1/models，Chat Completions 路径是 /v1/chat/completions；兼容平台可能要求填写带 /v1 或不带 /v1 的地址。请以当前服务文档、控制台字段说明和最终请求 URL 为准，重点防止 /v1/v1 重复拼接。

模型名称看起来一样，为什么仍然返回 404？

展示名不一定等于 API 的模型 ID。大小写、空格、连字符、版本后缀、分组前缀都可能导致不匹配。应从同一个 Base URL 和同一个 Key 返回的模型列表中复制 data[].id，不要从搜索结果、旧教程或其他平台配置中手动拼写。

模型列表能查到，但 Chat Completions 还是 404，怎么办？

检查该模型是否支持当前接口，以及客户端是否把请求发到了正确路径。官方文档提示不同模型的参数支持可能不同；如果服务要求 Responses API，就不能仅凭模型列表存在来证明 Chat Completions 一定可用。

如何判断是模型下线而不是路径错误？

先看返回是否为 JSON 以及错误字段，再查询当前模型目录和弃用页面。官方模型对象可能提供 shutdown_date；若模型已关闭，应按照官方替代模型和迁移说明更新配置。

相关阅读

• 继续排查 401 认证失败
• 继续排查 403 权限问题
• 查看 Chatbox 的 Base URL 与 Key 配置
• 查看兼容接口中的模型 ID 与 /v1 设置
• 调用成功后再排查流式中断

参考资料

1. OpenAI API Error codes 官方指南
2. OpenAI API List models 官方参考
3. OpenAI API Create chat completion 官方参考
4. OpenAI API Reference Overview 与认证说明
5. OpenAI API Deprecations 官方页面
6. developers.openai.com