使用指南

修复 HiAPI OpenAI 兼容接口的 "Model Not Found"（model_not_found）报错

2026年10月22日

问题现象

当你调用 HiAPI 的 OpenAI 兼容接口（POST /v1/chat/completions），而传入的 model id HiAPI 无法识别或无法路由时，接口返回 HTTP 400，响应体里带 model_not_found 错误码，长这样：

{
  "error": {
    "message": "The requested model does not exist or is not available. Check the exact model ID with GET /v1/models and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "code": "model_not_found",
    "request_id": "..."
  }
}

注意这和「密钥出问题」是两回事。如果你的 API key 本身无效或过期，HiAPI 返回的是 HTTP 401 + permission_denied，而不是 model_not_found：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "request_id": "..."
  }
}

看到 permission_denied 就先去修 key，不用管 model id。下面只讲 model_not_found。

常见原因

按实际命中概率从高到低排：

model id 拼写 / 大小写错，或直接复制了网页地址栏里的 slug。 model id 对大小写敏感，而且经常带点、横线、斜杠（例如 seedream-5.0-lite 不是 seedream-5-0-lite）。从浏览器地址栏把模型页的 slug 抄下来当 id 用，是这个报错最常见的来源——模型页网址里的短 slug 不一定等于真实 API id。
这个模型根本不是对话模型，它走的是别的接口。 HiAPI 上大多数图像 / 视频 / 音频模型只支持异步任务接口 POST /v1/tasks；而 gpt-5.6 / gpt-6 这一类推理模型只支持 POST /v1/responses。把它们发到 /v1/chat/completions，接口会用 invalid_request（HTTP 400）拒绝：
```
{
  "error": {
    "message": "The request is incomplete or incorrectly formatted. Please check it and try again...",
    "type": "hiapi_error",
    "param": "",
    "code": "invalid_request",
    "request_id": "..."
  }
}
```
GET /v1/models 返回的每个模型都带一个 supported_endpoint_types 字段，它才是「这个模型该用哪个接口」的唯一依据（见下文）。
模型已下线或改名。 id 拼写完全正确，但它已经不在当前 /v1/models 清单里了——老笔记、缓存里的旧 id 都可能过期。
把 key / 权限问题误判成 model 问题。 账号密钥无效时报的是 permission_denied（401），不是 model_not_found（400）。先按错误码分清是哪一类，再对症修。

修复步骤

先拿活清单和精确 id：带上你的 key 调 GET https://api.hiapi.ai/v1/models。这是实时目录，也正是报错信息让你去核对的地方——它的权威性高于你代码或笔记里任何写死的 id。
看 supported_endpoint_types 判断接口。每个模型条目长这样：
```
{ "id": "gpt-image-2/text-to-image", "object": "model", "owned_by": "custom", "supported_endpoint_types": ["task"] }
```
- task → 用异步 POST /v1/tasks，不能用 chat/completions；
- openai → 用 POST /v1/chat/completions（本文讲的就是这条线）；
- openai-response → 用 POST /v1/responses。
用清单里一字不差的 id 重发请求。多任务模型在清单里会带任务类型后缀（如 /text-to-image、/image-to-video），按清单里写的那个完整 id 用，别只用模型页网址里的裸 slug。
接口选对：是 task 型就改走 /v1/tasks，是 openai-response 型就改走 /v1/responses。换接口比在 chat/completions 上反复试 id 更能一次解决。
如果错误码其实是 permission_denied（401），问题在你的 key，不在 model id——单独去重置或更换 API key。

最小验证示例

排查这个报错，第一条命令永远是 GET /v1/models——它零成本、无副作用，一次验证两件事：key 通不通、这个 id 到底存不存在、该走哪个接口。

curl -s https://api.hiapi.ai/v1/models \
  -H "Authorization: Bearer $HIAPI_API_KEY"

返回 200 + 模型列表 → key 正常，接下来在列表里核对 id 和它的 supported_endpoint_types；
返回 401 + permission_denied → 是 key 的问题，先修 key。

确认某个模型是 task 型后，正确的调用方式是统一任务接口（model 用裸 id 即可，不带任务类型后缀也能路由）：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a red apple on a white table" }
  }'

注意 /v1/tasks 一旦收下请求就会真正创建一个计费任务并返回 taskId，所以它是「修复后正式调用」，不是用来随手试连通性的——纯连通性检查请用上面的 GET /v1/models。如果 id 不可用，/v1/tasks 的报错是另一套扁平结构（和 chat/completions 不同）：

{ "code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks" }

FAQ

Q：我是从模型页网址里直接复制的 id，为什么用不了？ A：模型页网址里往往是一个短 slug，而真实 API id（尤其是多任务模型）会带任务类型后缀，例如 gpt-image-2/text-to-image。请以 GET /v1/models 返回的 id 为准，不要以浏览器地址栏为准。

Q：GET /v1/models/{id} 对一个不存在的 id 居然返回了 HTTP 200，是 bug 吗？ A：不是。单模型查询接口即使 id 不存在也返回 200，但响应体里是一个 invalid_request_error / model_not_found 结构，而不是 404/400 状态码。对这个接口别只看 HTTP 状态码，要看 body。列表接口 GET /v1/models 和 /v1/chat/completions 的行为则如上文所述。

Q：我用 OpenAI 的 SDK 指向 HiAPI，报 model_not_found，这是 OpenAI 那边的问题吗？ A：不是。只要把 OpenAI 兼容 SDK 的 base_url 指向 HiAPI，模型解析就完全由 HiAPI 负责。model_not_found 意味着 HiAPI 没能把你传的 id 匹配到已注册的模型，按上面的步骤修即可。

Q：怎么快速判断一个模型该用哪个接口？ A：看 GET /v1/models 里该模型的 supported_endpoint_types：含 task 就走 POST /v1/tasks，含 openai 就走 POST /v1/chat/completions，含 openai-response 就走 POST /v1/responses。

Q：/v1/tasks 和 /v1/chat/completions 的错误码是一样的吗？ A：不一样。/v1/chat/completions 用小写 code（如 model_not_found、invalid_request）包在 {"error": {...}} 里；/v1/tasks 用大写 error_code（如 MODEL_UNAVAILABLE）放在扁平的 {"code","message","data","error_code"} 里。给两个接口写错误处理时，别假设一套能通用。