Behebung des Fehlers "Model Not Found" (model_not_found) der OpenAI-kompatiblen HiAPI-Schnittstelle

Symptom

Wenn du die OpenAI-kompatible Schnittstelle von HiAPI (POST /v1/chat/completions) aufrufst und die übergebene model-ID von HiAPI nicht erkannt oder nicht geroutet werden kann, gibt die Schnittstelle HTTP 400 zurück, und der Antworttext enthält den Fehlercode model_not_found, etwa so:

{
  "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": "..."
  }
}

Beachte, dass dies etwas völlig anderes ist als „ein Problem mit dem Schlüssel". Wenn dein API-Key selbst ungültig oder abgelaufen ist, gibt HiAPI HTTP 401 + permission_denied zurück, nicht 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": "..."
  }
}

Wenn du permission_denied siehst, behebe zuerst den Key und kümmere dich nicht um die model-id. Im Folgenden geht es nur um model_not_found.

Häufige Ursachen

Sortiert nach tatsächlicher Trefferwahrscheinlichkeit von hoch nach niedrig:

1. Schreibweise / Groß-/Kleinschreibung der model-id falsch oder direkt der Slug aus der Adressleiste des Browsers kopiert. Die model-id ist groß-/kleinschreibungssensitiv und enthält oft Punkte, Bindestriche und Schrägstriche (zum Beispiel seedream-5.0-lite und nicht seedream-5-0-lite). Den Slug der Modellseite aus der Browser-Adressleiste zu kopieren und als id zu verwenden, ist die häufigste Quelle dieses Fehlers – der kurze Slug in der URL der Modellseite ist nicht unbedingt gleich der echten API-id.

2. Dieses Modell ist überhaupt kein Chat-Modell, sondern nutzt eine andere Schnittstelle. Die meisten Bild- / Video- / Audio-Modelle auf HiAPI unterstützen nur die asynchrone Task-Schnittstelle POST /v1/tasks; Reasoning-Modelle wie gpt-5.6 / gpt-6 unterstützen nur POST /v1/responses. Wenn du sie an /v1/chat/completions sendest, lehnt die Schnittstelle sie mit invalid_request (HTTP 400) ab:

   {
     "error": {
       "message": "The request is incomplete or incorrectly formatted. Please check it and try again...",
       "type": "hiapi_error",
       "param": "",
       "code": "invalid_request",
       "request_id": "..."
     }
   }
   

   Jedes von GET /v1/models zurückgegebene Modell enthält ein Feld supported_endpoint_types, und dieses ist die einzige Grundlage dafür, „welche Schnittstelle dieses Modell verwenden sollte" (siehe unten).

3. Das Modell wurde eingestellt oder umbenannt. Die id ist vollkommen korrekt geschrieben, aber sie steht nicht mehr in der aktuellen /v1/models-Liste – alte ids aus alten Notizen oder Caches können veraltet sein.

4. Ein Key- / Berechtigungsproblem wird fälschlich als Modellproblem gedeutet. Bei einem ungültigen Konto-Schlüssel wird permission_denied (401) gemeldet, nicht model_not_found (400). Unterscheide zuerst anhand des Fehlercodes, um welche Art es sich handelt, und behebe dann gezielt.

Behebungsschritte

1. Zuerst die aktuelle Liste und die exakte id holen: Rufe mit deinem Key GET https://api.hiapi.ai/v1/models auf. Dies ist das Live-Verzeichnis und genau die Stelle, auf die dich die Fehlermeldung zum Abgleichen verweist – ihre Autorität ist höher als jede fest kodierte id in deinem Code oder deinen Notizen.

2. Anhand von supported_endpoint_types die Schnittstelle bestimmen. Jeder Modelleintrag sieht so aus:

   { "id": "gpt-image-2/text-to-image", "object": "model", "owned_by": "custom", "supported_endpoint_types": ["task"] }
   

   • task → verwende das asynchrone POST /v1/tasks, nicht chat/completions;
   • openai → verwende POST /v1/chat/completions (darum geht es in diesem Artikel);
   • openai-response → verwende POST /v1/responses.

3. Sende die Anfrage mit der exakt buchstabengleichen id aus der Liste erneut. Multi-Task-Modelle tragen in der Liste ein Suffix für den Aufgabentyp (z. B. /text-to-image, /image-to-video); verwende die vollständige id so, wie sie in der Liste steht, und nicht nur den nackten Slug aus der URL der Modellseite.

4. Die richtige Schnittstelle wählen: Wenn es ein task-Typ ist, wechsle zu /v1/tasks; wenn es ein openai-response-Typ ist, wechsle zu /v1/responses. Die Schnittstelle zu wechseln löst das Problem eher auf Anhieb, als bei chat/completions wiederholt ids auszuprobieren.

5. Wenn der Fehlercode tatsächlich permission_denied (401) ist, liegt das Problem an deinem Key, nicht an der model-id – setze den API-Key separat zurück oder ersetze ihn.

Minimales Verifikationsbeispiel

Bei der Fehlersuche zu diesem Fehler ist der erste Befehl immer GET /v1/models – er ist kostenlos, hat keine Nebenwirkungen und verifiziert auf einmal zwei Dinge: ob der Key funktioniert und ob diese id überhaupt existiert und welche Schnittstelle zu verwenden ist.

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

• Rückgabe 200 + Modellliste → Key ist in Ordnung; gleiche als Nächstes in der Liste die id und ihre supported_endpoint_types ab;
• Rückgabe 401 + permission_denied → es ist ein Key-Problem, behebe zuerst den Key.

Wenn bestätigt ist, dass ein Modell vom task-Typ ist, ist der korrekte Aufruf die einheitliche Task-Schnittstelle (für model genügt die nackte id; das Routing funktioniert auch ohne Suffix für den Aufgabentyp):

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

Beachte, dass /v1/tasks die Anfrage annimmt und dann tatsächlich einen abgerechneten Task erstellt und eine taskId zurückgibt; es ist also der „offizielle Aufruf nach der Behebung" und nicht zum beiläufigen Testen der Konnektivität gedacht – für eine reine Konnektivitätsprüfung verwende das oben genannte GET /v1/models. Wenn die id nicht verfügbar ist, hat der Fehler von /v1/tasks eine andere, flache Struktur (anders als bei chat/completions):

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

Verwandte interne Links

• Chat-Completions-API-Dokumentation – vollständige Referenz zu Anfrage / Antwort und Fehlerverhalten der OpenAI-kompatiblen Schnittstelle.
• Modellübersicht-Dokumentation – Informationen zum Modellkatalog und zum Auffinden der exakten id.
• Dokumentation zur API zum Erstellen von Tasks – Referenz zu den Feldern model, input und callback von /v1/tasks.
• Modellmarktplatz – alle verfügbaren Modelle durchsuchen.
• Preisseite – prüfen, welche Modelle verfügbar sind und die aktuellen Preise.

FAQ

F: Ich habe die id direkt aus der URL der Modellseite kopiert, warum funktioniert sie nicht? A: In der URL der Modellseite steht oft ein kurzer Slug, während die echte API-id (insbesondere bei Multi-Task-Modellen) ein Suffix für den Aufgabentyp enthält, zum Beispiel gpt-image-2/text-to-image. Richte dich nach der von GET /v1/models zurückgegebenen id, nicht nach der Browser-Adressleiste.

F: GET /v1/models/{id} gibt für eine nicht existierende id tatsächlich HTTP 200 zurück – ist das ein Bug? A: Nein. Die Einzelmodell-Abfrageschnittstelle gibt selbst bei nicht existierender id 200 zurück, aber im Antwortkörper steht eine invalid_request_error / model_not_found-Struktur statt eines Statuscodes 404/400. Bei dieser Schnittstelle darfst du nicht nur auf den HTTP-Statuscode achten, sondern musst den Body ansehen. Die Listenschnittstelle GET /v1/models und /v1/chat/completions verhalten sich dagegen wie oben beschrieben.

F: Ich zeige mit dem OpenAI-SDK auf HiAPI, bekomme model_not_found – ist das ein Problem auf OpenAI-Seite? A: Nein. Sobald du die base_url des OpenAI-kompatiblen SDK auf HiAPI zeigst, liegt die Modellauflösung vollständig bei HiAPI. model_not_found bedeutet, dass HiAPI die von dir übergebene id keinem registrierten Modell zuordnen konnte; behebe es nach den obigen Schritten.

F: Wie erkenne ich schnell, welche Schnittstelle ein Modell verwenden soll? A: Sieh dir die supported_endpoint_types des Modells in GET /v1/models an: enthält task → verwende POST /v1/tasks; enthält openai → verwende POST /v1/chat/completions; enthält openai-response → verwende POST /v1/responses.

F: Sind die Fehlercodes von /v1/tasks und /v1/chat/completions gleich? A: Nein. /v1/chat/completions verwendet kleingeschriebene Codes (wie model_not_found, invalid_request), eingebettet in {"error": {...}}; /v1/tasks verwendet einen großgeschriebenen error_code (wie MODEL_UNAVAILABLE) in einem flachen {"code","message","data","error_code"}. Wenn du Fehlerbehandlung für beide Schnittstellen schreibst, gehe nicht davon aus, dass ein Satz für beide passt.