HiAPI-Aufgabe gibt TASK_FAILED zurück: Ursachen und Behebung

Beim Einreichen einer asynchronen Aufgabe an die HiAPI-Aufgabenschnittstelle wird bei erfolgreicher Einreichung HTTP 200 und eine taskId zurückgegeben. Die Aufgabe wird anschließend im Hintergrund ausgeführt. Wenn du sie abfragst, kann sie im Endzustand fail enden. Die Abfrage liefert dann etwa Folgendes – beachte, dass der HTTP-Aufruf selbst weiterhin 200 ist:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M4RK...",
    "model": "seedream-5.0-lite/image-to-image",
    "status": "fail",
    "error": { "code": "TASK_FAILED", "message": "task failed" },
    "created": 1791827316,
    "completed": 1791827352,
    "storage": "temp"
  },
  "message": "success"
}

Das ist der oft als „TASK_FAILED-Fehler“ bezeichnete Fall: Die Anfrage wurde angenommen, die Aufgabe lief und war am Ende nicht erfolgreich. Es ist kein HTTP-4xx-Fehler und auch kein Timeout. Dieser Artikel zeigt dir, wie du diese Rückgabe liest und die einzelnen Ursachen behebst.

Zuerst klarstellen: TASK_FAILED ist kein HTTP-Statuscode

Der wichtigste Punkt:

• Der HTTP-Statuscode des Abfrageaufrufs ist 200, im Antwortkörper steht sogar "message": "success" – das bedeutet nur, dass der API-Aufruf erfolgreich war, nicht dass deine Aufgabe erfolgreich war.
• "status": "fail" (in data) ist die Grundlage für die Feststellung, dass die Aufgabe fehlgeschlagen ist. Bei einer abgeschlossenen Aufgabe ist data.status immer "success" oder "fail".
• "TASK_FAILED" ist der Wert von data.error.code, nicht der status. Manche Fehlschläge tragen einen spezifischeren code und eine hilfreichere message (siehe unten).

Frage also immer GET /v1/tasks/{taskId} ab und entscheide anhand von data.status – verlasse dich niemals nur auf den HTTP-Statuscode, um Erfolg oder Misserfolg zu beurteilen.

Ursache aus den Aufgabendetails ermitteln

Nach Erhalt der Rückgabe im Endzustand lies die data-Felder in dieser Reihenfolge:

1. Sieh zuerst data.status an – nur bei "fail" ist die Aufgabe fehlgeschlagen.
2. Lies dann data.error.code – das ist die maschinell auswertbare Fehlerkategorie (z. B. TASK_FAILED, INVALID_REQUEST, CONTENT_POLICY_VIOLATION).
3. Lies zuletzt data.error.message – das ist die für Menschen gedachte Erläuterung, die meist direkt die Ursache benennt (etwa dass eine bestimmte Eingabe-URL nicht abrufbar ist).

error.code bestimmt im Wesentlichen, ob dieser Fehlschlag „durch Wiederholen behoben werden kann“: Das generische TASK_FAILED (message meist "task failed") ist oft ein vorübergehendes Problem und kann wiederholt werden; ein eindeutiger code (wie INVALID_REQUEST, CONTENT_POLICY_VIOLATION) ist ein deterministischer Fehlschlag – ohne Änderung der Eingabe führt jede Wiederholung zum selben Ergebnis.

Häufige Ursachen für den Endzustand fail

Ungefähr nach Häufigkeit absteigend sortiert.

1. Eingabe-Bild-/Video-URL nicht erreichbar oder nicht öffentlich

Dies ist die häufigste Ursache bei Image-to-Image- sowie Image-/Video-to-Video-Aufgaben. Wenn deine input-URL auf eine URL verweist, die die Plattform nicht abrufen kann, wird die Aufgabe angenommen, schlägt aber bei der Ausführung fehl. Eine echte Rückgabe im Endzustand:

"error": {
  "code": "INVALID_REQUEST",
  "message": "The image URL could not be downloaded. Please provide a reachable public HTTP(S) URL and try again."
}

Die message sagt hier bereits alles. Andere Modelle legen dieselbe Grundursache als generisches TASK_FAILED / "task failed" offen.

Behebung: Hoste die Eingabe unter einer öffentlich erreichbaren HTTPS-URL und prüfe sie vor dem Einreichen:

curl -I "https://your-host.example.com/input.png"
# Muss 200 zurückgeben und ein direkter Medien-content-type sein (image/* oder video/*)
# Darf nicht 401/403/404 sein und auch keine HTML-Seite

Abgelaufene Presigned-URLs, localhost / interne Adressen und Links, die erst nach Anmeldung geöffnet werden können, sind die häufigsten Fallstricke. Das ist ein deterministischer Fehlschlag – ohne Reparatur der URL läuft jede Wiederholung nur erneut ins Leere.

2. Vorübergehender oder Upstream-Generierungsfehler

Manchmal scheitert eine formal völlig korrekte Aufgabe mit generischem error.code: "TASK_FAILED", message: "task failed" und ohne weitere Details. Dies ist meist ein vorübergehendes Problem.

Behebung: Wiederhole ein- bis zweimal. Schlägt es mit derselben Eingabe wiederholt fehl, vereinfache die Eingabe (kürze den Prompt, entferne optionale Felder) und führe erneut aus, um den Auslöser einzugrenzen.

3. Inhalt durch Sicherheitsrichtlinie blockiert

Wenn der Prompt oder das Eingabebild gegen die Inhaltssicherheitsrichtlinie der Plattform verstößt, endet die Aufgabe mit einem deterministischen richtlinienbezogenen Fehler, wobei data.error.code gleich CONTENT_POLICY_VIOLATION ist.

Behebung: Dies ist ein dauerhafter Fehlschlag; Wiederholen hilft nicht. Passe den Prompt und die Eingabematerialien an, entferne die regelwidrigen Inhalte und reiche dann erneut ein.

4. Ein Parameter, den das Modell erst zur Laufzeit ablehnt

Die allermeisten ungültigen Parameter werden bereits beim Einreichen mit HTTP 400 abgefangen (du erhältst dann gar keine taskId) – siehe den nächsten Abschnitt. Gelegentlich wird eine Option, die für sich genommen gültig ist, in der Kombination aber vom Modell nicht unterstützt, erst bei der Ausführung abgelehnt und endet in data.status: "fail". Die error.message nennt dann die betroffene Option.

Behebung: Lies data.error.message und prüfe auf der Modellseite die unterstützten Eingaben dieses Modells (z. B. die Modellseite von GPT Image 2); entferne oder korrigiere das genannte Feld.

Wie man TASK_FAILED, 4xx und Timeout unterscheidet

Drei völlig verschiedene Situationen werden umgangssprachlich oft pauschal als „fehlgeschlagen“ bezeichnet, doch die Behebung unterscheidet sich:

Was du siehst	Bedeutung	Wo zu beheben
POST gibt kein 2xx zurück (400/401/402/429) und keine taskId	Anfrage abgelehnt, es lief überhaupt keine Aufgabe	Anfrage / Key / Guthaben korrigieren (siehe Links unten)
POST gibt 200 + taskId zurück, Abfrage zeigt data.status: "fail"	TASK_FAILED – Aufgabe lief und schlug fehl	data.error.message lesen (dieser Artikel)
POST gibt 200 + taskId zurück, die Abfrage bleibt über deine Frist hinaus in einem Nicht-Endzustand (z. B. handling)	Timeout, kein Fehlschlag	Weiter abfragen / Timeout erhöhen / wiederholen

Wenn du gar keine taskId erhalten hast, ist es kein TASK_FAILED, sondern ein Anfragefehler:

• HTTP 400 Parameter ungültig, fehlend oder nicht unterstützt → HiAPI-400-Parameterfehler beheben
• HTTP 401 API-Key ungültig → Fehler „API-Key ungültig“
• Guthaben unzureichend (wird bereits bei der Erstellung abgelehnt, es gibt also keine Aufgabe, die fehlschlagen könnte) → HiAPI-402-Guthaben unzureichend beheben
• Unbekannte oder nicht gelistete Modell-ID (MODEL_UNAVAILABLE) → „Modell existiert nicht / nicht verfügbar“
• Aufgabe erreicht nie den Endzustand → HiAPI-Aufgaben-Timeout und 504-Fehler

Ein Authentifizierungsfehler wird bereits auf Anfrageebene abgelehnt; die Rückgabe ist HTTP 401 + {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}. Es entsteht keine Aufgabe, also kann auch von TASK_FAILED keine Rede sein.

Behebungs-Checkliste

1. Frage die Aufgabe ab, verlasse dich nicht nur auf POST. Das Einreichen sagt dir nur, dass die Aufgabe in die Warteschlange gestellt wurde. Rufe GET /v1/tasks/{taskId} auf und sieh dir data.status an.
2. Bestätige, dass es ein echter Fehlschlag ist: data.status == "fail" (der HTTP-Code ist weiterhin 200).
3. Lies data.error.code und data.error.message. Die message ist dein wichtigstes Signal.
4. Wird eine Eingabe-URL genannt: Ändere die URL auf öffentlich erreichbar und prüfe mit curl -I (200 + direkter Medien-content-type).
5. Ist die message generisch ("task failed"): Behandle es als vorübergehendes Problem und wiederhole; bei wiederholtem Fehlschlag vereinfache die Eingabe.
6. Bei deterministischen Fehlern wie CONTENT_POLICY_VIOLATION: Das ist ein dauerhafter Fehlschlag; nicht automatisch wiederholen – nur eine Änderung der Eingabe hilft.
7. Prüfe die Modell-ID: Ist sie aktuell in GET /v1/models enthalten und stimmt sie exakt mit der gesendeten überein? Eine unbekannte ID schlägt beim Einreichen mit 400 MODEL_UNAVAILABLE fehl, nicht im Endzustand fail.
8. Gar keine taskId? Dann ist es kein TASK_FAILED – springe zum entsprechenden Leitfaden für Anfragefehler oben.

Minimales Verifizierungsbeispiel

Bevor du eine konkrete Aufgabe untersuchst, bestätige mit einer sauberen Anfrage deinen Key und die Konnektivität. Rufe die einheitliche Aufgabenschnittstelle POST https://api.hiapi.ai/v1/tasks auf, mit der Modell-ID als nackter ID (ohne endpoint-Suffix):

# 1) Einreichen – erwartet HTTP 200 + eine taskId
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"a red bicycle on a white background","aspect_ratio":"1:1"}}'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

# 2) Abfragen – setze die erhaltene taskId ein
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxxxxxx \
  -H "Authorization: Bearer sk-YOUR_KEY"
# -> während der Ausführung ist data.status "handling", danach "success" oder "fail"

Wenn Schritt 1 200 und eine taskId zurückgibt, sind dein Key und die Schnittstelle in Ordnung; jeder Fehlschlag ist dann ein Problem der einzelnen Aufgabe, kein Integrationsproblem. Wenn Schritt 1 401 zurückgibt, ist der Key falsch – verwalte ihn in der HiAPI-Konsole. Hinweis: Dieses Beispiel reicht eine echte Generierung ein und verursacht Kosten.

Zur Abrechnung: Zahle nicht wiederholt für zum Scheitern verurteilte Aufgaben

Ob fehlgeschlagene Aufgaben berechnet werden und wie Vorabbelastung und Rückerstattung ablaufen, findest du unter Werden fehlgeschlagene HiAPI-Anfragen berechnet?. Zwei wichtige Punkte:

• Deterministische Fehlschläge nicht blind automatisch wiederholen. Bei CONTENT_POLICY_VIOLATION, nicht erreichbaren URLs und Ähnlichem ist jede Wiederholung eine neue Aufgabe und kann berechnet werden. Ändere zuerst die Eingabe, damit deine Wiederholungslogik nicht im Leerlauf Geld verbrennt.
• Prüfe die Eingabe-URL vor dem Einreichen mit curl -I. Eine HEAD-Prüfung ist kostenlos, während eine wegen eines defekten Links zum Scheitern verurteilte Aufgabe kostenpflichtig sein kann.

FAQ

Ist TASK_FAILED ein HTTP-Statuscode? Nein. Der HTTP-Aufruf gibt 200 zurück. TASK_FAILED ist der Wert von data.error.code in der Rückgabe im Endzustand, und diese Rückgabe hat data.status gleich "fail".

data.status ist "fail", aber ich suche "TASK_FAILED" – wonach soll ich schauen? Jedes an seiner Stelle. Bei einer abgeschlossenen Aufgabe ist data.status immer "success" oder "fail"; "TASK_FAILED" ist ein generisches data.error.code, und fehlgeschlagene Aufgaben können auch spezifischere codes (wie INVALID_REQUEST, CONTENT_POLICY_VIOLATION) und eine umsetzbare message tragen.

Welche TASK_FAILED kann man wiederholen, welche nicht? Das generische "task failed" (ohne weitere Details) ist meist ein vorübergehendes Problem und kann ein- bis zweimal wiederholt werden; deterministische Fehlschläge mit eindeutigem code (fehlerhafte URL → INVALID_REQUEST, Inhaltsverstoß → CONTENT_POLICY_VIOLATION, vom Modell abgelehnter Parameter) sind durch Wiederholen nicht zu beheben – die Eingabe muss geändert werden.

Meine Aufgabe bleibt bei handling stehen, weder Fehlschlag noch Erfolg. Das ist ein Timeout, kein Fehlschlag. Frage weiter ab oder erhöhe den Client-Timeout; siehe HiAPI-Aufgaben-Timeout und 504-Fehler.

Ich erhalte 400 / 401 / 402 statt einer taskId. Das sind abgelehnte Anfragen – es wurde keine Aufgabe erstellt, also gibt es auch kein „Fehlschlagen“. Behebe Anfrage, Key oder Guthaben mit den oben verlinkten Leitfäden.

Werden fehlgeschlagene Aufgaben berechnet? Siehe Werden fehlgeschlagene HiAPI-Anfragen berechnet?, um zu erfahren, wie Vorabbelastung und Rückerstattung bei Fehlschlägen gehandhabt werden.

Wie bestätige ich eine fehlerhafte Eingabe-URL? Lies data.error.message. URL-Probleme weisen meist darauf hin, dass das Bild oder Video nicht heruntergeladen werden kann; prüfe mit curl -I, dass der Link 200 und eine direkte Mediendatei zurückgibt.