HiAPI 400 Bad Request: So beheben Sie Parameterfehler bei der Task-API

Die einheitliche asynchrone Task-Schnittstelle gibt 400 Bad Request zurück. Das bedeutet, dass Ihre Anfrage HiAPI erreicht hat, aber noch bevor irgendein Modell ausgeführt wurde abgelehnt wurde – weil das JSON selbst oder das input-Objekt nicht dem Schema dieses Modells entspricht. Die Antwort sieht so aus:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'"
}

Das nützlichste Feld ist message: Es gibt an, welcher Parameter genau betroffen ist und worin der Fehler liegt. 400 ist ein Problem der Anfrage selbst, kein Authentifizierungs- oder Guthabenproblem – und da überhaupt kein Task erstellt wurde, wird ein abgelehnter 400 nie berechnet.

Wann 400 ausgelöst wird (nach Trefferwahrscheinlichkeit von hoch nach niedrig)

Jeder der folgenden Fälle gibt HTTP 400 zurück. Bei Schema-Problemen ist error_code gleich INVALID_REQUEST, bei nicht existierender Modell-ID gleich MODEL_UNAVAILABLE. Die folgenden Fehlertexte sind alle echte Rückgaben von HiAPI:

Auslöser	Die echte message, die Sie sehen werden	error_code
Ungültiger Enum-Wert	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
Falscher Werttyp	invalid input: prompt: got number, want string	INVALID_REQUEST
Pflichtfeld fehlt / Feldname falsch geschrieben	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
JSON-Formatfehler	invalid json body: unexpected end of JSON input	INVALID_REQUEST
Modell-ID existiert nicht / falsch geschrieben	model not available via /v1/tasks	MODEL_UNAVAILABLE

Achten Sie darauf, was der Schema-Validator tatsächlich prüft: Enum-Werte (aspect_ratio, resolution usw. liegen außerhalb der für dieses Modell erlaubten Menge), Typen (wo ein String erwartet wird, wurde eine Zahl übergeben, oder wo ein Array erwartet wird, ein nackter String), Feldnamen (Tippfehler wie promptt oder umbenannte, entfernte Felder – der Validator meldet dann gleichzeitig „fehlendes Pflichtfeld" und „zusätzliches unbekanntes Feld") sowie die Modell-ID selbst (der Wert ist kein auf der Task-Schnittstelle verfügbares Online-Modell).

So diagnostizieren Sie anhand des Antwortkörpers

1. Schauen Sie zuerst auf den HTTP-Statuscode. 400 = Ihre Anfrage hat ein Problem. Wenn Sie 401, 402, 403, 429 oder 504 sehen, ist das eine andere Art von Problem – siehe „Weiterführende Lektüre" am Ende. Wenn der Statuscode tatsächlich 401 ist, ändern Sie nicht die Parameter, um es wie einen 400 zu beheben.
2. Dann schauen Sie auf error_code. INVALID_REQUEST bedeutet, dass der Request-Body / das input die Schema-Validierung nicht bestanden hat; MODEL_UNAVAILABLE bedeutet, dass der Wert von model auf /v1/tasks nicht aufgelöst werden kann.
3. Lesen Sie message wörtlich. Sie ist feldbezogen: invalid input: <Feld>: <Grund>. Das Wort nach invalid input: ist der zu korrigierende Parameter. Steht dort value must be one of ..., sind die erlaubten Werte direkt dort abgedruckt – kopieren Sie einen davon unverändert.
4. Bei additional properties '<x>' not allowed haben Sie ein Feld übergeben, das im Schema dieses Modells nicht definiert ist – meist ein Tippfehler oder ein von einem anderen Modell kopierter Parameter. Löschen Sie es, oder ändern Sie es in den korrekten Feldnamen.

Diese feldbezogenen Fehlermeldungen verdienen eine eigene Erwähnung: Viele Bild- und Video-APIs antworten auf eine fehlerhafte Anfrage nur mit einem nackten 400 Bad Request ohne jede Details. HiAPI validiert Ihr input gegen das jeweilige Schema jedes Modells und teilt Ihnen mit, welches Feld betroffen ist und was erwartet wird – so können Sie ein Feld nach dem anderen korrekt beheben, statt zu raten.

Schritte zur Behebung (Checkliste)

1. Korrigieren Sie zuerst das JSON-Format. Wenn message mit invalid json body beginnt, ist der Payload selbst kein gültiges JSON – prüfen Sie auf nicht geschlossene geschweifte oder eckige Klammern, überflüssige Kommas oder nicht escapte Anführungszeichen. Validieren Sie den String vor dem Senden mit jq oder python -m json.tool.
2. Stellen Sie sicher, dass model eine nackte Online-ID ist. Verwenden Sie reine IDs wie z-image, gpt-image-2 – erfinden Sie keine Routing-Suffixe. Prüfen Sie gegen die Modellliste oder die Modellseite. Eine nicht existierende ID liefert MODEL_UNAVAILABLE.
3. Richten Sie sich nach dem Schema des Modells. Jedes Modell deklariert seine eigenen input-Felder. Legen Sie die Generierungsparameter in input ab, nicht auf der obersten Ebene. Löschen Sie Felder, die im Schema nicht aufgeführt sind (genau daraus entsteht additional properties ... not allowed).
4. Übernehmen Sie Enum-Werte unverändert. Wenn message value must be one of ... ausgibt, kopieren Sie einen der Werte zeichengenau (z. B. "aspect_ratio": "1:1").
5. Übergeben Sie den richtigen Typ. prompt ist ein String; Referenzbilder gehören in ein Array-Feld (z. B. image_urls); numerische Felder müssen Zahlen sein, keine Strings in Anführungszeichen. Feldnamen können sich je nach Modell unterscheiden (etwa Referenzbilder als input_urls / image_urls / image_input, Seitenverhältnis als aspect_ratio / ratio / size, Dauer kann String oder Integer sein) – maßgeblich ist stets das Schema des Modells.
6. Erneut senden und erneut lesen. Falls es weiterhin 400 ist, verweist message diesmal auf das nächste Feld. Beheben Sie eins nach dem anderen, bis der Aufruf eine 200 mit taskId zurückgibt.

Minimal funktionierender Request

Dies ist der kleinste korrekt formatierte Text-zu-Bild-Aufruf. Wenn er eine 200 mit data.taskId zurückgibt, sind Ihr Key, Ihre Endpunkt-URL und Ihre Request-Struktur in Ordnung – der zuvor aufgetretene 400 war ein Parameterproblem, kein Verbindungsproblem:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "a red ceramic mug on a wooden table, soft daylight",
      "aspect_ratio": "1:1"
    }
  }'

Nach erfolgreicher Übermittlung enthält data eine taskId. Fragen Sie anschließend wiederholt GET https://api.hiapi.ai/v1/tasks/<taskId> ab, bis data.status zu success (oder fail) wird, und lesen Sie dann das Ergebnis aus data.output. Halten Sie den Request während der Fehlersuche minimal: Fügen Sie optionale Felder einzeln wieder hinzu, damit ein neu auftretender 400 genau auf das gerade hinzugefügte Feld zeigt. Die vollständige Feldliste finden Sie auf der Modellseite, den Task-Lebenszyklus in der API-Dokumentation.

Weiterführende Lektüre

• API Key ungültig: Ursachen, Behebung und Integrations-Checkliste – lesen Sie diesen Artikel, wenn der Statuscode 401 statt 400 ist.
• „Model Not Found" bei HiAPI beheben – zu MODEL_UNAVAILABLE und Modell-ID-Problemen.
• So beheben Sie HiAPI-Rate-Limit-Fehler (429) – zu Drosselung, nicht zur Request-Validierung.
• Werden fehlgeschlagene HiAPI-Requests berechnet? – zum Unterschied bei der Abrechnung zwischen 400 und „fehlgeschlagen, nachdem der Task gestartet ist".
• Preisseite und Dashboard: Credits prüfen, Key abrufen.

FAQ

Was bedeutet error_code: INVALID_REQUEST? Ihr Request-Body oder das input-Objekt hat die Schema-Validierung nicht bestanden. Das Feld message benennt den betroffenen Parameter. Es ist kein Authentifizierungsproblem (das wäre 401) und kein Guthabenproblem (das wäre 402).

Warum erscheint additional properties '<Feld>' not allowed? Sie haben ein Feld übergeben, das im Schema dieses Modells nicht definiert ist – meist ein Tippfehler (prompt als promptt geschrieben), ein Feld eines anderen Modells, oder Sie haben einen Parameter auf der obersten Ebene statt in input abgelegt. Löschen oder benennen Sie ihn um.

Werden bei 400 Bad Request Credits abgezogen? Nein. 400 wird in der Validierungsphase abgelehnt, es wurde überhaupt kein Task erstellt, also gibt es auch nichts zu berechnen. Nur tatsächlich akzeptierte und ausgeführte Tasks werden berechnet.

Ich bin sicher, dass das JSON korrekt ist, bekomme aber trotzdem 400 – was tun? Lesen Sie message wörtlich. Sie ist feldbezogen und nennt Ihnen den exakten Parameter und den erwarteten Wert oder Typ. Steht dort value must be one of ..., liegt Ihr Wert nicht im erlaubten Enum – kopieren Sie einen erlaubten Wert unverändert. Wenn der Typ bemängelt wird (got number, want string), korrigieren Sie den Typ.

Ist es derselbe Fehler, wenn die Modell-ID falsch geschrieben ist? Es bleibt HTTP 400, aber error_code ist MODEL_UNAVAILABLE mit dem Text model not available via /v1/tasks. Verwenden Sie eine nackte, aktuell online verfügbare Modell-ID, ohne selbst erfundene Routing-Suffixe.

Wie finde ich heraus, welche Felder ein Modell tatsächlich akzeptiert? Die Seite jedes Modells listet sein input-Schema und einen Beispiel-Request auf. Beginnen Sie mit dem oben genannten minimal funktionierenden Request und fügen Sie dann gemäß der Modellseiten-Dokumentation die Felder einzeln hinzu.