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

更新于 2026-10-23 · code0.cyou

简答：API 返回 404 model not found 时，先不要急着更换 Key 或重试：先读取响应体和最终请求 URL，再核对当前 Key 可访问的模型 ID、Base URL 是否重复拼接 /v1，以及你使用的协议是否支持该模型。若是 Azure 或其他部署型平台，model 字段通常要填部署名；若模型列表存在但仍报错，还要检查项目、分组、区域、权限和接口能力。

定义：404 model not found 是服务端无法根据当前请求找到可用模型、部署或模型路由的错误提示，但它也可能与请求路径错误或协议不匹配有关，不能仅凭 404 状态码断定模型已下线。

先做这一步：用错误响应和最终 URL 分类

本站为第三方指南，非某服务官方，以其官网为准。排查应从一次非流式、最小化请求开始，并同时记录 HTTP 状态码、响应体、请求路径、实际发送的 model 值和请求 ID；不要把完整 API Key 放进日志。OpenAI 官方文档说明，API Key 应通过 Bearer 认证并安全保管，支持的请求还可以使用客户端请求 ID辅助定位。

截至2026年10月23日，模型目录和模型生命周期会持续变化，本文不固定推荐某个具体模型名；最终应以对应平台控制台、模型列表接口和官方文档为准。

OpenAI 的 REST API 文档以 /v1 为 API 路径示例；Gemini 原生接口则使用 models/{model}:generateContent 这类路径。因此，不同平台的 Base URL 不能机械套用。

查看 OpenAI API 参考；查看 Gemini generateContent 参考。

模型参数到底填什么：模型 ID、展示名还是部署名

最常见的错误是把控制台里的展示名复制到了 model 字段。展示名适合给人看，API 通常需要精确的模型 ID；大小写、日期后缀、连字符、前后空格和隐藏换行都可能导致匹配失败。不要手打，优先从官方模型列表或部署列表复制。

Azure 官方明确区分底层模型名和部署名：调用 Azure OpenAI 时，model 应填写创建部署时选择的部署名，而不是直接填写底层模型名。部署名写错时，就可能出现 model not found 或 deployment not found。

查看 Azure 与 OpenAI 端点及部署名差异；查看 Azure 部署模型说明。

按顺序排查 Base URL、/v1 和请求协议

1. 打印最终请求地址：不要只看配置文件中的 Base URL，要查看 SDK 拼接后的完整地址。例如配置已经是 https://example.com/v1，客户端又自动追加 /v1/chat/completions 时，可能形成 /v1/v1/chat/completions。
2. 区分原生接口与兼容接口：OpenAI Chat Completions 通常使用 /chat/completions，Responses 使用对应的 Responses 路径；Anthropic 使用 Messages API；Gemini 原生接口使用 models/{model}:generateContent。不要只替换域名，却保留另一家平台的路径和字段。
3. 检查 model 的实际值：记录长度、首尾字符和 JSON 转义，重点查前后空格、换行、日期后缀、大小写、旧模型别名和客户端自动重写。
4. 关闭流式和复杂参数：先删除工具调用、图片、结构化输出、推理参数和自定义 Header，只保留认证、model 和一条文本输入。
5. 再检查权限上下文：确认 Key、项目、组织、区域、分组和部署属于同一套配置。模型列表能证明“某个上下文看到了它”，不一定证明当前请求使用的项目或接口可以调用它。

Gemini 官方模型接口支持列出可用模型，并返回模型名称、支持的操作和限制信息；其文档还展示了通过 OpenAI 兼容端点列出模型的方式。对于其他兼容服务，只有在其官方文档明确支持时，才可以照搬 /v1/models。

查看 Gemini 模型列表接口；查看 Gemini OpenAI 兼容方式。

可直接复制的最小请求：先验证模型和路径

下面的命令以 OpenAI 兼容接口为例。将 BASE_URL 改成服务商文档要求的根地址，将 MODEL_ID 改成当前 Key 可访问的真实模型 ID。不要把真实 Key 写进脚本、仓库或截图。

Bash：先列模型，再发非流式请求

export API_KEY='your-key' export BASE_URL='https://api.example.com/v1' export MODEL_ID='your-model-id' curl -i --fail-with-body "$BASE_URL/models" -H "Authorization: Bearer $API_KEY" curl -i --fail-with-body "$BASE_URL/chat/completions" -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK\"}],\"stream\":false,\"max_completion_tokens\":16}"

--fail-with-body 需要较新的 curl 版本；如果本机不支持，可先去掉该选项，但保留 -i 查看状态码。export 只对当前 Bash 会话生效。若服务商没有公开 /models，不要把列模型返回的 404 当作模型不存在，应直接查看官方控制台或文档。

PowerShell：使用 Invoke-RestMethod

$env:API_KEY = 'your-key' $env:BASE_URL = 'https://api.example.com/v1' $env:MODEL_ID = 'your-model-id' $headers = @{ Authorization = "Bearer $env:API_KEY" } Invoke-RestMethod -Uri "$env:BASE_URL/models" -Headers $headers -Method Get $body = @{ model = $env:MODEL_ID; messages = @(@{ role = 'user'; content = 'Reply with OK' }); stream = $false; max_completion_tokens = 16 } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri "$env:BASE_URL/chat/completions" -Headers ($headers + @{ 'Content-Type' = 'application/json' }) -Method Post -Body $body

PowerShell 中的 $env: 环境变量同样只对当前会话生效。若要看到完整响应头和状态码，可改用 curl.exe -i，不要混淆 PowerShell 的 curl 别名和真正的 curl。

Python：打印最终配置但不泄露 Key

import os from openai import OpenAI base_url = os.environ['BASE_URL'].rstrip('/') model = os.environ['MODEL_ID'] print({'base_url': base_url, 'model': model, 'has_key': bool(os.environ.get('API_KEY'))}) client = OpenAI(api_key=os.environ['API_KEY'], base_url=base_url) response = client.chat.completions.create(model=model, messages=[{'role': 'user', 'content': 'Reply with OK'}], stream=False, max_completion_tokens=16) print(response.choices[0].message.content)

模型列表里存在，为什么调用仍然返回 404

这类情况通常不是“模型名一定正确”，而是列表和调用使用的上下文不一致。按以下顺序核对：

• Key 或项目不同：列模型和实际调用可能用了不同环境变量、不同项目 Header 或不同账号。
• 模型存在但接口不支持：某些模型只支持文本生成、嵌入、图像或其他特定接口。若接口能力不匹配，服务端可能返回 400、404 或平台自定义错误。
• 区域或资源不同：部署型平台常按资源、区域和部署提供模型，控制台看到的模型不代表另一个区域资源也有同名部署。
• 客户端改写了模型名：检查 SDK、插件、路由层和环境变量是否将 MODEL_ID 替换成别名、默认模型或旧版本名称。
• 模型已退役或别名变化：模型目录会更新，生产环境应使用官方当前支持的模型标识，并关注弃用通知。Anthropic 官方文档将模型区分为 active、deprecated 和 retired，已 retired 的请求会失败。

如果平台返回的是 HTML 404，优先修 Base URL 和路径；如果是结构化 JSON 且明确包含模型或部署字段，再查 ID、权限和能力。不要仅凭“余额正常”判断模型一定可用，余额与模型路由是不同问题。

查看 Anthropic 模型生命周期说明。

排错后仍失败：收集这些信息再联系平台

提交工单或向内部同事求助时，建议提供：请求时间、HTTP 状态码、响应体中的错误类型和 code、最终请求路径、使用的接口类型、脱敏后的 model 值、项目或区域标识、客户端和 SDK 版本、请求 ID，以及是否能通过最小非流式请求复现。

必须删除或遮盖 API Key、Authorization Header、完整提示词中的隐私数据和返回内容中的敏感信息。若要比较两次请求，只保留配置差异，例如 Base URL、model、项目 Header 和接口路径。

常见问题

API 返回 404 model not found，是不是模型已经下线？

不一定。404 也可能来自错误的 Base URL、重复的 /v1、模型 ID 拼写错误、Azure 部署名错误、项目权限或协议不匹配。先看响应体是 HTML 还是结构化 JSON，再核对同一 Key 可访问的模型或部署列表。

为什么 /v1/models 能看到模型，实际调用还是 404？

模型列表和实际调用可能使用了不同的 Key、项目、区域或资源；也可能模型支持的接口与当前调用方式不一致，还可能被客户端改写了 model 字段。请打印最终 URL、实际 model 值和请求头中的项目上下文，逐项对比。

Base URL 应该写到 /v1 还是域名根目录？

没有统一答案，要看 SDK 和服务商文档。如果 SDK 会自动追加 /v1，Base URL 通常不应再次包含 /v1；如果文档要求兼容端点包含 /v1，则按文档配置。最终以实际请求 URL 是否出现 /v1/v1 或缺少接口路径为准。

Azure OpenAI 的 model 参数应该填模型 ID还是部署名？

通常填写部署名。Azure 官方文档明确说明，Azure OpenAI 调用使用创建部署时设置的 deployment name，而不是直接使用底层模型名称。部署名可以与模型名相同，也可以是自定义名称。

Anthropic、Gemini 和 OpenAI 的模型名可以直接互换吗？

不能直接互换。不同平台有不同的模型标识、请求路径、认证方式和接口能力。Anthropic 使用 Messages API；Gemini 原生接口使用模型资源路径；OpenAI 兼容接口也只能在服务商明确支持时使用兼容格式。

相关阅读

• 返回 Code0 首页查看其他 AI API 接入与排错指南

参考资料

1. OpenAI API Reference：认证、REST API 与请求说明
2. Google Gemini API：generateContent 接口参考
3. Google Gemini API：模型列表接口参考
4. Google Gemini API：OpenAI 兼容方式
5. Microsoft Learn：OpenAI 与 Azure OpenAI 端点及部署名差异
6. Anthropic 官方文档：Claude 模型生命周期与退役说明