OpenAI API 404 model not found 怎么解决？

更新于 2026-10-24 · onomeo.cyou

简答：OpenAI API 返回 404 model_not_found，通常表示请求中的模型或资源对当前请求不可用；它既可能是模型 ID 拼错、模型已弃用，也可能是当前 API Key、组织或项目无权访问该模型。先用同一 Key 调用 <code>GET /v1/models</code>，再核对 Base URL、Endpoint、项目和模型参数，通常比直接反复重试更快定位问题。

定义：<code>model_not_found</code> 是 API 返回的 404 错误，表示请求的模型或资源当前不可用于这次请求；官方建议检查模型 ID、模型、项目以及资源是否已删除。

先试这一步：用同一个 Key 查询可用模型

截至2026年10月24日，最稳妥的第一步是使用发起失败请求的同一个 API Key 查询模型目录，然后确认返回的 data[].id 是否与请求中的 model 完全一致。模型列表接口会返回模型 ID，并可能返回 shutdown_date，可用于识别已经安排下线的模型。参考 OpenAI List models API Reference 与 OpenAI Deprecations。

Bash：

curl -i --fail-with-body \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

PowerShell：

$headers = @{ Authorization = "Bearer $env:OPENAI_API_KEY" }
Invoke-RestMethod `
  -Uri "https://api.openai.com/v1/models" `
  -Headers $headers `
  -Method Get

PowerShell 中的 $env: 只对当前会话生效。验证 Key 时只检查变量是否存在，不要把完整 Key 打印到日志。

按 5 个顺序排查 404 model not found

1. 核对 model 字符串。检查前后空格、大小写、连字符、日期后缀和是否误用了 ChatGPT 界面中的名称。不要凭记忆拼接模型变体；优先使用模型列表接口返回的精确 ID。
2. 确认模型是否已下线或计划下线。模型目录中的 shutdown_date 不是空值时，应查看弃用页面并按官方建议迁移。不要把旧教程里的模型名直接复制到新项目中。
3. 检查 Base URL 和 Endpoint。官方 OpenAI 请求通常使用 https://api.openai.com/v1；Responses API 的路径是 /v1/responses，Chat Completions 的路径是 /v1/chat/completions。如果使用兼容接口，应以该服务的 API 文档为准，不要只因为它声称兼容就假定所有路径、模型名和字段完全相同。
4. 确认 Key、组织和 project。404 不一定代表模型字符串拼错。官方 Agents 错误说明将 model_not_found 描述为模型或资源对当前请求不可用，并建议检查 ID、模型、项目和资源是否被删除；因此，模型访问不足也应沿着项目和 Key 方向核对，而不能只换模型名。参考 Errors and recovery。
5. 最后再检查请求格式。确认使用的 API 与请求体匹配。Responses 使用 input，Chat Completions 使用 messages；如果 Endpoint、请求体和 SDK 方法混用，可能出现其他错误，不能把所有失败都归类为 404。

OpenAI 官方说明中，Responses API 是新项目推荐的接口，而 Chat Completions 仍受支持。两者的输入字段和返回结构不同，迁移时应同时修改 Endpoint、请求体和响应读取方式。参考 Migrate to the Responses API。

可复制的最小请求：Responses、Chat Completions 与 JavaScript

先让模型目录请求成功，再使用同一模型 ID 发最小请求。下面的 MODEL_ID 只是占位符，应替换成你从模型列表中确认过的真实 ID；不要直接照抄未验证的模型名。

Responses API：Bash

curl -i https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "MODEL_ID",
    "input": "Reply with one short sentence."
  }'

Responses API：PowerShell

$headers = @{
  Authorization = "Bearer $env:OPENAI_API_KEY"
  "Content-Type" = "application/json"
}
$body = @{
  model = "MODEL_ID"
  input = "Reply with one short sentence."
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://api.openai.com/v1/responses" `
  -Headers $headers `
  -Method Post `
  -Body $body

Chat Completions API：Python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(response.choices[0].message.content)

JavaScript：列出模型

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const page = await client.models.list();
console.log(page.data.map((model) => model.id));

如果 models.list() 成功但生成请求仍返回 404，重点检查生成请求中的 model 是否逐字一致，以及请求是否实际发往同一个 Base URL。

OpenAI、Azure OpenAI 与兼容接口的 Base URL 和模型字段对比

Microsoft 文档明确说明，Azure OpenAI v1 使用 /openai/v1/ 路径，并在 model 字段传入部署名称；v1 接口不再要求额外的 api-version 参数。参考 Microsoft Foundry endpoints 与 Azure OpenAI v1 API。

Python 连接 Azure OpenAI v1：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=os.environ["AZURE_OPENAI_ENDPOINT"].rstrip("/") + "/openai/v1/",
)

response = client.responses.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    input="Reply with one short sentence.",
)
print(response.output_text)

Python 连接 OpenAI-compatible 接口：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMPATIBLE_API_KEY"],
    base_url=os.environ["COMPATIBLE_BASE_URL"].rstrip("/"),
)

response = client.chat.completions.create(
    model=os.environ["COMPATIBLE_MODEL"],
    messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(response.choices[0].message.content)

兼容接口示例中的环境变量名称和模型值需要替换为对应服务的实际配置；未核实的服务不应直接套用 Azure 或 OpenAI 的 Endpoint 规则。

错误码速查：不要把所有失败都当成 404

官方错误码指南将 400、401、403、429、500 和 503 分别列出处理方向，并说明 Python SDK 会将资源不存在映射为 NotFoundError，权限不足映射为 PermissionDeniedError。但模型级不可用仍可能以 404 model_not_found 表现，因此应结合错误对象中的 code、type 和 message 判断。参考 OpenAI Error codes。

排查仍未解决时，保留这些信息

• 完整的错误状态码、error.type、error.code 和 message。
• 实际使用的模型 ID，但不要泄露 API Key。
• 请求使用的 Endpoint、API 路径、组织或 project 标识。
• 请求时间、时区、SDK 版本和是否经过兼容网关。
• 模型列表请求是否成功，以及返回的模型 ID 是否包含目标模型。

官方建议持续报错时收集模型、错误信息和代码、请求数据与请求头、带时区的时间等诊断信息；分享日志前应移除 API Key、Authorization 值和用户隐私数据。参考 Error codes 的 Persistent errors。

常见问题

OpenAI API 返回 404 model not found 是模型不存在吗？

不一定。它表示模型或资源对当前请求不可用，可能是模型 ID 错误、模型已下线、项目或 Key 无法访问，或者请求发到了不匹配的 Endpoint。先用同一个 Key 调用模型列表，再核对项目和 Base URL。

为什么 ChatGPT 里能选择的模型，API 里却返回 404？

ChatGPT 产品界面中的模型选择不应直接当作 API 模型目录。API 请求应使用 API 文档或 <code>/v1/models</code> 返回的模型 ID，并确认当前 API Key、组织和项目具有相应访问范围。

Azure OpenAI 的 model 应该填 gpt-4o 还是部署名？

对于 Azure OpenAI v1，Microsoft 文档要求在 <code>model</code> 字段传入部署名称。部署名可以与底层模型名不同，因此应以 Azure 资源中的实际部署名为准。

OpenAI-compatible 接口也能直接使用 OpenAI 的模型名吗？

不能默认这样做。兼容接口可能只兼容请求格式，模型 ID、Base URL、支持的 Endpoint 和参数仍由具体服务决定。应先查询该服务的模型列表或查看其官方接口文档。

应该使用 Responses API 还是 Chat Completions API？

新项目可优先评估 Responses API；Chat Completions 仍受支持。两者的 Endpoint、请求字段和响应结构不同，不能只替换 URL 后继续使用原请求体。

相关阅读

• 查看更多 API 错误排查指南
• 继续排查 Cursor 的 Base URL、Key 和模型名

参考资料

1. List models | OpenAI API Reference
2. Error codes | OpenAI API
3. Errors and recovery | OpenAI API
4. Models | OpenAI API
5. Deprecations | OpenAI API
6. Migrate to the Responses API | OpenAI API
7. Endpoints for Microsoft Foundry Models
8. Azure OpenAI in Microsoft Foundry Models v1 API