Fixed: "Model Not Found" Error on OpenAI-Compatible APIs (hiapi)

问题现象

When you call hiapi's OpenAI-compatible endpoint (POST /v1/chat/completions) with a model id that hiapi doesn't recognize or route, the API returns HTTP 400 with this exact body:

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

This is distinct from an auth failure. If your API key itself is invalid or expired, hiapi returns HTTP 401 with {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} instead — no mention of model_not_found. If you're seeing permission_denied, the problem is your key, not the model id; see the fix for that in a separate guide.

常见原因

Ranked by how often this actually turns out to be the cause:

1. Sending the page-URL slug instead of the real API model id. hiapi's model catalog pages live at URLs like /models/gpt-image-2, but models that support more than one task type (image generation, image editing, video, etc.) require a task-type suffix as part of the actual API model id — e.g. the real id for image generation is gpt-image-2/text-to-image, not the bare gpt-image-2 you see in the URL. Copying the slug straight out of the browser address bar is the single most common cause of this error.
2. Typos or case mismatches in the model id — model ids are case-sensitive and often contain dots, dashes, or slashes that are easy to mistype (e.g. seedream-5.0-lite vs seedream-5-0-lite).
3. Using a model id that isn't enabled/available on your account or plan. Some models are scoped to specific plans or temporarily unavailable; the id itself may be spelled correctly but still unroutable.
4. Confusing the optional route field with the mandatory task-type suffix. route (e.g. "route": "ext") is a separate, optional field for selecting a specific backend — it does not replace the task-type suffix in the model id, and sending a route-only value without the correct suffixed id still 400s.

修复步骤

1. Get the exact, current model id list — call GET https://api.hiapi.ai/v1/models with your API key. This is a live catalog; it's exactly what the error message tells you to check, and it's the source of truth over anything cached in your own code or notes.
2. Cross-check the id against the model's docs/catalog page, not just its URL slug. If the model supports multiple task types (image/video/text), confirm the exact suffixed id (/text-to-image, /image-to-video, etc.) rather than assuming the bare slug works.
3. Don't conflate route with the model id. If you're using route, keep it as a separate field alongside the full, correctly-suffixed model value — don't use route as a substitute for the suffix.
4. Re-run your request with the corrected id. If you still get model_not_found, re-fetch /v1/models again — the id may have changed or the model may be temporarily deprecated.
5. If the error code is permission_denied instead of model_not_found, the issue is your API key/auth, not the model id — regenerate or check your key separately.

最小验证示例

Use hiapi's unified task endpoint to confirm your key and connectivity are working, independent of any one specific model id. Sending a model id that isn't available returns a 400 with its own MODEL_UNAVAILABLE error code (a different envelope shape than the chat/completions example above, since /v1/tasks has its own error contract):

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" }
  }'

If the model id is wrong/unavailable, you'll get:

{
  "code": 400,
  "message": "model not available",
  "data": null,
  "error_code": "MODEL_UNAVAILABLE"
}

If instead you get an HTTP 401 with {"error":{"code":"permission_denied",...}}, your key itself is the problem — fix that first, then retry with the corrected model id.

相关内链

• Chat Completions API docs — full request/response reference for the OpenAI-compatible endpoint, including error behavior.
• Models Overview — browse the current model catalog and look up exact model ids.
• Create Task API docs — field reference for model, route, and callback on the unified task endpoint.
• Pricing — check which models are available and their current pricing.

FAQ

Q: I copied the model id straight from the hiapi website URL — why doesn't it work? A: The page URL often shows a short slug (e.g. /models/gpt-image-2), but the real API model id for multi-task models includes a task-type suffix (e.g. gpt-image-2/text-to-image). Always confirm the exact id via GET /v1/models or the model's docs page, not the browser URL.

Q: GET /v1/models/{id} returned HTTP 200 even though the model doesn't exist — is that a bug? A: No — the single-model retrieve endpoint returns 200 with an embedded invalid_request_error body rather than a 404/400 status for a nonexistent id. Don't rely on the HTTP status alone for that specific endpoint; check the response body. The list endpoint (GET /v1/models) and /v1/chat/completions behave as documented above.

Q: I'm getting model_not_found from my own OpenAI SDK code that points at hiapi — is this an OpenAI issue? A: No. Once you point an OpenAI-compatible SDK at hiapi's base URL, model resolution is entirely hiapi's responsibility. model_not_found means hiapi couldn't match the id you sent to a registered model — follow the fix steps above.

Q: Does /v1/tasks use the same error codes as /v1/chat/completions? A: No. /v1/chat/completions uses lowercase codes like model_not_found inside an {"error": {...}} wrapper. /v1/tasks uses its own uppercase error_code values (e.g. MODEL_UNAVAILABLE) inside a flat {"code","message","data","error_code"} shape. Don't assume the two are interchangeable when writing error-handling code against both.