HiAPI Aufgaben-Ausgabe-URL abgelaufen (expireAt): Ergebnis vor dem Ablauf herunterladen und umspeichern

Du erzeugst mit POST /v1/tasks ein Bild oder Video, und nach Abschluss der Aufgabe erhältst du aus data.output[0].url einen Link auf temp.hiapi.ai – damals ließ er sich öffnen, doch ein paar Tage später erscheint beim Zugriff eine HTML-Seite „Not Found“:

HTTP/2 404
content-type: text/html

Zurückgegeben werden keine Bild-/Videobytes, sondern eine Cloudflare-404-Seite. Der Grund ist eindeutig: Ausgabe-URLs von Aufgaben sind temporäre Links mit begrenzter Gültigkeit. Sobald das expireAt (Unix-Zeitstempel) im finalen Zustand erreicht ist, wird das Objekt auf temp.hiapi.ai bereinigt und der Hotlink ungültig.

Zunächst die Felder im finalen Zustand verstehen

Wenn das Polling der Aufgabe den finalen Zustand (GET /v1/tasks/{taskId}) erfolgreich liefert, sehen die Schlüsselfelder so aus:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "status": "success",
    "storage": "temp",
    "created": 1791828181,
    "completed": 1791828201,
    "output": [
      {
        "artifactId": "...",
        "type": "image",
        "url": "https://temp.hiapi.ai/....png",
        "expireAt": 1792432981
      }
    ]
  },
  "message": "success"
}

• data.status == "success" bedeutet finaler Erfolg (Fehler ist "fail", in Warteschlange/Verarbeitung sind queued / handling / archiving).
• data.output ist ein Array, jedes Element hat seine eigene url und sein eigenes expireAt.
• expireAt ist ein ganzzahliger Unix-Zeitstempel (kein ISO-String). Ob abgelaufen, entscheidet allein dieses Feld: now >= expireAt bedeutet abgelaufen.
• Der Wert von data.storage ist "temp" – das ist selbst ein Hinweis: temporärer Speicher, nicht zur langfristigen Referenzierung gedacht.

Wie lange ist die Gültigkeit? Bei einem gemessenen Beispiel gilt expireAt - completed = 604800 Sekunden (genau 7 Tage). Aber schreibe „7 Tage“ nicht fest in den Code – maßgeblich ist das eigene expireAt jeder Ausgabe; je nach Modell/Speicherstrategie kann es abweichen.

Häufige Ursachen (nach Trefferwahrscheinlichkeit sortiert)

1. Hotlinks als langfristige Referenz in die Datenbank geschrieben: Beim Speichern wurde die temporäre URL temp.hiapi.ai/... abgelegt, und nach expireAt gibt es massenhaft 404. Das ist die häufigste Falle.
2. Nach Erhalt des finalen Zustands nicht sofort heruntergeladen: Erst lange nach Abschluss (über die TTL hinaus) wurden die Bytes abgerufen.
3. Annahme, erneutes Polling „erneuere“ den Link: Ein erneutes GET auf dieselbe taskId liefert dieselbe URL und dasselbe expireAt – die Metadaten sind persistent, aber das Objekt selbst wird nach Ablauf nicht neu erzeugt; ein erneutes GET liefert keinen neuen Link.
4. 404 fälschlich als Aufgabenfehler gedeutet: Die Aufgabe war längst success, nur das Ausgabe-Asset ist abgelaufen – das sind zwei verschiedene Dinge.

Behebungsschritte

1. Sobald der finale Zustand da ist, sofort die Bytes herunterladen. Nach dem Polling bis data.status == "success" sofort für jede output[].url ein GET ausführen und die Binärdaten abrufen – nicht in die Warteschlange, nicht aufschieben.
2. In deinen eigenen Objektspeicher umspeichern (R2 / S3 / lokale Platte) und durch eine eigene persistente URL ersetzen.
3. In der Datenbank nur deine eigene persistente URL speichern, niemals den Hotlink von temp.hiapi.ai.
4. Vor dem Download prüfen, ob abgelaufen: erst herunterladen, wenn now < expireAt; ist es bereits abgelaufen, direkt die Neustart-Logik verwenden.
5. Nach Ablauf hilft nur ein erneuter Lauf der Aufgabe. Es gibt kein „neuen Link per taskId tauschen“ – ein erneutes GET auf dieselbe taskId liefert weiterhin die abgelaufene URL. Um wieder ein herunterladbares Ergebnis zu erhalten, muss die Aufgabe erneut eingereicht werden (wird erneut berechnet).
6. Download-Zeitpunkt bei Stapelaufgaben steuern: Das zuerst fertiggestellte Element einer Reihe hat auch das früheste expireAt. Sofort nach Fertigstellung herunterladen, nicht erst warten, bis die gesamte Reihe durch ist – sonst kann das früh fertige Element schon kurz vor dem Ablauf stehen.

Minimales Verifizierungsbeispiel

Bestätige, dass dein Key funktioniert, die Aufgaben-API Ergebnisse liefert und du expireAt selbst siehst. Verwende für die model id die nackte id (z-image, keinen Suffix wie /text-to-image anhängen, sonst 400):

# 1. Aufgabe einreichen
curl -s 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 apple on a wooden table" }
  }'
# → {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

# 2. Mit der taskId aus dem vorherigen Schritt den finalen Zustand pollen, url und expireAt auslesen
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxx \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# Sobald data.status zu "success" wird, stehen data.output[0].url / .expireAt bereit

Scheitert die Authentifizierung, kommt HTTP 401 + {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} zurück – das ist ein Key-Problem, kein Ablaufproblem. Wird die Aufgabe nicht gefunden, ist es {"code":404,"data":null,"message":"task not found"} – meist wurde die taskId falsch abgeschrieben oder ein Key aus der falschen Umgebung verwendet.

Relevante Links

• Wie man Aufgaben einreicht und pollt: HiAPI Schnellstart-Dokumentation
• Deinen API-Key nachschlagen, Aufgabenverlauf ansehen: Konsole
• Welche Modelle verfügbar sind: Modellmarkt
• Beispiel einer Modellseite (die in diesem Artikel zur Verifizierung genutzte): Z-Image Text-zu-Bild

FAQ

Frage: Welches Format hat expireAt genau? Antwort: Ein ganzzahliger Unix-Zeitstempel (Sekunden), z. B. 1792432981, kein ISO-String. Zur Prüfung auf Ablauf genügt now >= expireAt.

Frage: Kann man nach Ablauf des Links durch ein erneutes GET der Aufgabe den Link „verlängern“? Antwort: Nein. Ein erneutes GET auf dieselbe taskId liefert weiterhin die ursprüngliche URL und das ursprüngliche expireAt, das Objekt wurde bereits bereinigt. Um wieder ein herunterladbares Ergebnis zu erhalten, muss die Aufgabe erneut laufen (wird erneut berechnet).

Frage: Liefert der Zugriff nach Ablauf 403 oder 404? Antwort: HTTP 404, und der Body ist eine Cloudflare-„Not Found“-Seite mit text/html, keine Bildbytes und kein XML-AccessDenied. Wenn deine Download-Logik nur 200 akzeptiert, denke daran, „alles außer 200 als Fehler“ zu behandeln.

Frage: Ist die Gültigkeit fest 7 Tage? Antwort: Das gemessene Beispiel sind 7 Tage (604800 Sekunden), aber maßgeblich ist das eigene expireAt jeder Ausgabe; schreibe die Anzahl der Tage nicht fest in den Code.

Frage: Wie lädt man eine Reihe von Aufgaben am zuverlässigsten herunter? Antwort: Nach Fertigstellungsreihenfolge – wer zuerst success ist, dessen Bytes zuerst herunterladen. Die zuerst fertiggestellte Ausgabe hat auch das früheste expireAt; wartet man bis zum Schluss mit dem gemeinsamen Download, gerät man leicht in die Nähe des Ablaufs.