OpenOx

OpenAI API 404 model not found 怎么办？

更新于 2026-11-01 · openox.cyou

简答：OpenAI API 返回 404 model not found，最常见原因不是网络，而是 model 字段填错、模型对当前项目不可用、Base URL 或接口路径拼接错误。最快的处理顺序是：记录最终 URL → 用同一个 Key 请求 /v1/models → 从返回结果复制精确 id → 再用最小请求验证。若使用 Azure OpenAI，model 通常应填写部署名称，而不是模型展示名称。

定义：404 model not found 是服务端找不到当前请求所引用的模型或模型资源，实际还需要结合响应 JSON、请求地址、项目权限和供应商类型判断具体原因。

先做这一步：确认 404 到底是哪一种

先不要立即更换模型或反复重试。把客户端最终发出的请求地址、HTTP 方法、响应状态码和响应正文保存下来，并确认请求是否真的发往预期的服务商。OpenAI 官方对 404 的通用解释是请求的资源不存在；如果错误类型包含 model_not_found，还应检查模型、项目以及资源是否已被删除或当前请求不可用。可参考OpenAI 官方错误与恢复说明。

根据响应特征快速分流
现象优先怀疑先做什么
JSON 中出现 model_not_found模型 ID、项目或模型可用性用同一个 Key 查询 GET /v1/models
返回 404，但正文是 HTMLBase URL、路由或反向代理检查是否缺少或重复拼接 /v1
访问 /v1/models 也返回 404服务商地址或兼容网关路径错误核对该服务商的 API 文档和最终 URL
模型列表能看到，但调用仍失败项目权限、接口类型或模型能力不匹配确认 Key、Organization、Project 与调用接口一致
使用 Azure OpenAI把模型名误当成部署名改用实际创建的 deployment name

三步修复流程：URL、模型列表、最小请求

  1. 记录最终请求地址。约定 BASE_URL 要么写成 https://api.openai.com，要么写成 https://api.openai.com/v1，不要在代码中无条件再次追加 /v1。直连 OpenAI 的模型列表地址通常是 https://api.openai.com/v1/models；官方模型列表接口会返回当前可用模型及其 id，不要只根据控制台展示名称或旧教程填写模型。详见OpenAI 官方 List models 接口。
  2. 使用完全相同的 API Key 查询模型。如果客户端使用了项目级 Key，就不要用另一个账户或另一个项目的 Key 查询。模型列表中复制完整的 id，注意大小写、连字符、版本后缀、前后空格和换行。
  3. 使用同一模型发最小请求。先去掉工具调用、图片、流式输出、长上下文和自定义参数，只保留认证、model 与一段文本。成功判定应是 HTTP 200，并且响应中出现正常的输出字段，而不是只看客户端没有抛出异常。

如果你使用的是 OpenAI Responses API，请请求 /v1/responses 并发送 input；如果使用 Chat Completions，请请求 /v1/chat/completions 并发送 messages。两个接口的路径和请求体不能混用。官方文档分别列出了Responses API与Chat Completions API的请求格式。

可复制的最小测试：Bash、PowerShell、CMD、Python 与 JavaScript

Bash 或 macOS/Linux

以下示例假设 BASE_URL 不包含末尾的 /v1，因此路径由命令统一补上。先替换为你通过模型列表接口确认过的精确 ID。

export OPENAI_API_KEY='替换为你的Key' export BASE_URL='https://api.openai.com' export MODEL_ID='从/v1/models复制的id' curl --fail-with-body "$BASE_URL/v1/responses" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"model\":\"$MODEL_ID\",\"input\":\"Reply with OK\"}"

PowerShell

$env:OPENAI_API_KEY = "替换为你的Key" $env:BASE_URL = "https://api.openai.com" $env:MODEL_ID = "从/v1/models复制的id" $headers = @{ Authorization = "Bearer $env:OPENAI_API_KEY" } $body = @{ model = $env:MODEL_ID; input = "Reply with OK" } | ConvertTo-Json Invoke-RestMethod -Method Post -Uri "$env:BASE_URL/v1/responses" -Headers $headers -ContentType "application/json" -Body $body

Windows CMD

set OPENAI_API_KEY=替换为你的Key set BASE_URL=https://api.openai.com set MODEL_ID=从/v1/models复制的id curl --fail-with-body "%BASE_URL%/v1/responses" -H "Authorization: Bearer %OPENAI_API_KEY%" -H "Content-Type: application/json" -d "{\"model\":\"%MODEL_ID%\",\"input\":\"Reply with OK\"}"

Python

import os from openai import OpenAI client = OpenAI( api_key=os.environ["OPENAI_API_KEY"], base_url=os.environ.get("BASE_URL", "https://api.openai.com/v1"), ) response = client.responses.create( model=os.environ["MODEL_ID"], input="Reply with OK", ) print(response.output_text)

JavaScript

import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.BASE_URL || "https://api.openai.com/v1", }); const response = await client.responses.create({ model: process.env.MODEL_ID, input: "Reply with OK", }); console.log(response.output_text);

执行前请确认 SDK 版本支持你使用的接口，并且不要把真实 Key 写入代码、提交到 Git 仓库或粘贴到公开工单中。若你把 BASE_URL 设置为已经包含 /v1 的地址，就必须把代码中的路径改为 SDK 所需的相对路径，避免产生 /v1/v1。不同 SDK 对 base_url 的拼接方式可能不同，最终仍应以网络日志中的实际请求 URL 为准。

模型列表能看到，为什么调用仍然 404？

OpenAI 官方模型接口说明，模型的 id 是可以在 API 端点中引用的模型标识；因此排查时应优先采用服务端实际返回的 ID，而不是依据旧文章中的固定模型名。参考OpenAI 官方模型文档。

Azure OpenAI 与兼容接口要单独判断

Azure OpenAI 的调用逻辑不能简单等同于 OpenAI 直连。Microsoft 官方说明：Azure OpenAI 使用部署概念，调用时 model 应填写你创建的 deployment name；即使底层部署的是某个模型，部署名称也可能是自定义字符串。可核对Microsoft 官方端点切换说明。

如果使用 Azure 的 OpenAI v1 路径，官方文档给出的形式是资源地址加上 /openai/v1/，并在 model 字段中传部署名称；如果使用旧式部署路径，则还需要按照 Azure 当前文档处理部署路径和 API 版本，不能把两种写法混拼。若 Responses API 返回模型不支持，应先确认该部署是否支持该接口，再考虑改用 Chat Completions；相关限制可见Microsoft Foundry 官方端点说明。

第三方 OpenAI 兼容服务的情况则取决于其路由和模型映射：先向该服务商的 Base URL 请求模型列表，确认返回格式和模型 ID，再按其文档选择 /v1/responses、/v1/chat/completions 或其他路径。查不到明确文档时，不要把“兼容 OpenAI”理解为所有端点、字段和模型都完全相同。

排查完成后的自查清单

  1. 是否保存了原始 HTTP 状态码、响应 JSON 或 HTML 正文？
  2. 最终请求域名是否是预期服务商，而不是旧环境变量、代理或默认 SDK 地址？
  3. BASE_URL 与 /v1 是否只拼接了一次？
  4. 是否用同一个 API Key 请求了模型列表？
  5. model 是否直接复制自当前返回的精确 id？
  6. Organization、Project、Key 和运行环境是否属于同一套配置？
  7. Responses 的 input 与 Chat Completions 的 messages 是否没有混用？
  8. 使用 Azure 时，填写的是 deployment name，而不是仅凭模型名称猜出的字符串？
  9. 最小请求是否成功后，才逐项恢复工具、图片、流式和其他参数？

如果仍然失败，向服务商提交脱敏后的模型名、错误类型、请求时间和最终 URL；不要提交完整 API Key、Authorization 请求头或包含敏感数据的请求体。OpenAI 官方错误文档也建议持久性错误提供模型、错误信息、请求数据和时间等诊断信息，但敏感凭据应先移除。

常见问题

OpenAI API 404 model not found 是模型下线了吗？

不一定。它也可能由模型 ID 拼写错误、当前 Project 不可用、Key 不一致、Base URL 错误或接口类型不匹配造成。先用同一个 Key 请求模型列表，再根据响应中的精确 id 做最小请求。模型是否仍可用应以当前 API 返回和官方文档为准。

为什么 /v1/models 能返回模型，但调用还是 404？

模型列表和推理请求可能使用了不同的 Key、Project、Organization 或 Base URL；也可能是模型支持的接口与当前请求不匹配。请检查最终请求地址，确认 Responses 与 Chat Completions 的路径和请求体没有混用，并逐项核对项目权限。

Base URL 应该写到 /v1 还是不要写？

没有一个适用于所有 SDK 的统一写法。本文 curl 示例把 Base URL 写成不含 /v1 的根地址，再在命令中拼接完整路径；Python 和 JavaScript 示例使用 SDK 常见的含 /v1 的 Base URL。关键是确认 SDK 会如何拼接，并在日志中检查最终 URL，避免 /v1/v1 或缺少 /v1。

Azure OpenAI 的 model 为什么不是公开模型名？

Azure 使用部署名称路由请求。Microsoft 官方说明，Azure OpenAI 调用中的 model 应填写你创建的 deployment name；部署名称可以与底层模型名相同，也可以是自定义名称。因此应到 Azure 的部署列表复制实际名称。

能不能直接换一个网上看到的模型名？

不建议。模型 ID、接口支持、项目权限和可用性可能变化，旧文章中的名称未必适用于当前 Key。更稳妥的做法是先请求模型列表，从当前响应复制精确 id，再用最小请求验证。

相关阅读

参考资料

  1. OpenAI 官方错误与恢复说明
  2. OpenAI 官方 List models 接口
  3. OpenAI 官方 Responses API
  4. OpenAI 官方 Chat Completions API
  5. OpenAI 官方模型文档
  6. Microsoft 官方 OpenAI 与 Azure OpenAI 端点切换说明