HiAPI-Ausgabe-URLs abgelaufen? Innerhalb von 7 Tagen herunterladen oder persistent speichern

TL;DR

• Die von POST /v1/tasks zurückgegebenen Ausgabelinks sind temporär: Sie werden etwa 7 Tage nach Abschluss der Aufgabe gelöscht. Das expireAt jeder Ausgabe gibt dir den genauen Ablaufzeitpunkt in Unix-Sekunden an.
• Einmal abgelaufene Links lassen sich nicht wiederherstellen. Eine erneute Abfrage der Aufgabe liefert nur denselben Link, und ein erneutes Ausführen der Aufgabe wird erneut berechnet.
• Zwei Lösungen: Lade die Dateien direkt nach erfolgreichem Abschluss der Aufgabe herunter, oder behalte sie mit "storage": "persistent" auf HiAPI (0,05 $ pro GB und Monat). Du kannst temporäre Ausgaben auch jederzeit vor ihrem Ablauf auf persistenten Speicher upgraden.

So sieht eine abgeschlossene Aufgabe aus

Hier sind echte Aufgabendetails von GET https://api.hiapi.ai/v1/tasks/{taskId}:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01M59F0HVM9QSCYPDT4BHABD3K",
    "model": "grok-imagine/text-to-image",
    "status": "success",
    "created": 1792392841,
    "completed": 1792392863,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../01M59F0HVM9QSCYPDT4BHABD3K-0.png",
        "expireAt": 1792997663
      }
    ]
  }
}

• storage: "temp" ist die Standardstufe.
• expireAt minus completed ergibt 604.800 Sekunden, also genau 7 Tage. Wir haben vier Aufgaben geprüft (zwei Bilder und zwei Videos); bei allen vier betrug das Aufbewahrungsfenster 7 Tage.
• status durchläuft nacheinander queued, handling und archiving und endet schließlich bei success oder fail. Nur diese letzten beiden sind Endzustände.

Warum Links „plötzlich“ ungültig werden

1. Du speicherst den Link statt der Datei. In einer Datenbankzeile, einem CMS-Feld oder einer Notion-Seite liegt eine temp.hiapi.ai-URL, die in der ersten Woche funktioniert und danach für niemanden mehr erreichbar ist.
2. Die Datei wird zu spät abgerufen. Eine Warteschlange holt das Ergebnis erst Tage später ab, wenn expireAt bereits überschritten ist.
3. Beim Batch-Job fehlt der Upload-Schritt. Die Logs sehen in Ordnung aus, aber eine Woche später sind die Dateien weg.
4. Die Ausgabe einer Aufgabe dient als Eingabe der nächsten. Heute funktioniert es, aber nach Ablauf des Links schlägt die zweite Aufgabe fehl, wenn sie erneut ausgeführt wird.

Lösung 1: Im selben Codepfad herunterladen

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run_and_save(model, inp, path, timeout_s=600):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)
    task_id = r["data"]["taskId"]          # store this before polling
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            out = d["output"][0]
            with open(path, "wb") as f:      # or upload to S3 / R2 here
                f.write(requests.get(out["url"], timeout=120).content)
            return task_id, out["expireAt"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(3)
    raise TimeoutError(task_id)

run_and_save("z-image", {"prompt": "a red ceramic teapot on a wooden table", "aspect_ratio": "1:1"},
             "teapot.png")

Speichere deine eigene Speicher-URL in der Datenbank, nicht den Link von HiAPI. Wenn der Prozess nach dem Absenden abstürzt, frage erneut die gespeicherte taskId ab, statt eine neue Aufgabe anzulegen; die Datei ist innerhalb von 7 Tagen noch vorhanden.

Lösung 2: Ausgaben auf HiAPI behalten

Wenn du keinen eigenen Speicher aufbauen möchtest, kannst du HiAPI bitten, die Dateien zu behalten:

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

storage steht auf der obersten Ebene, gleichrangig zu model, und nicht innerhalb von input. Prüfe data.storage in den Aufgabendetails: Wenn dein Guthaben nicht ausreicht oder das Speicherlimit überschritten ist, fällt die Ausgabe stillschweigend auf temp zurück, während die Aufgabe trotzdem erfolgreich ist.

Du hast bereits temporäre Ausgaben, die du behalten möchtest? Stufe sie vor ihrem Ablauf hoch. Hole dir zuerst ihre IDs über GET /v1/storages, dann:

curl -s -X POST https://api.hiapi.ai/v1/storages/promote \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '["90216", "90215"]'

Pro Aufruf sind höchstens 50 IDs möglich. Die Antwort listet die accepted und rejected IDs auf und gibt für jede abgelehnte ID einen Grund an, z. B. cap_exceeded. Das Upgrade läuft im Hintergrund; die Dateien behalten ihren ursprünglichen Pfad und werden auf die persistente Domain migriert. Du kannst das Upgrade auch unter Dashboard → Storage durchführen.

	temp (Standard)	persistent
Aufbewahrungsdauer	etwa 7 Tage	bis du sie löschst
Kosten	kostenlos	0,05 $ pro GB und Monat, tageweise abgerechnet
Download	kostenlos	kostenlos
Größenlimit	keins	standardmäßig 100 GB pro Konto

Kostenbeispiel: 5 GB einen Monat lang kosten 0,25 $; 50 GB kosten 2,50 $. Nach dem Löschen von Dateien mit POST /v1/storages/delete wird die Abrechnung ab dem nächsten Tag eingestellt. Persistente Dateien können nicht wieder in den temporären Speicher zurückversetzt werden.

Wenn dein Guthaben 3 Tage in Folge die Speicherkosten nicht decken kann, geraten persistente Dateien in eine 7-tägige Kulanzfrist, und du erhältst eine E-Mail. Nach einer Aufladung bleiben die Dateien erhalten; wenn die Kulanzfrist endet, ohne dass du aufgeladen hast, werden die Dateien gelöscht.

Welche Lösung solltest du wählen?

• Du hast bereits S3, R2 oder ein CDN: Nutze Lösung 1. Lade einmal herunter und stelle die Dateien aus deinem eigenen Speicher bereit.
• Du möchtest, dass Links dauerhaft gültig bleiben, ohne eigenen Speicher aufzubauen: Nutze Lösung 2 und setze "storage": "persistent".
• Du musst nur wenige Ergebnisse behalten: Lass alle Ausgaben in temp und stufe nur die hoch, die du behalten möchtest.

FAQ

Wie lange bleiben Ausgabelinks erhalten?

Etwa 7 Tage nach Abschluss der Aufgabe. Der genaue Zeitpunkt steht in expireAt (Unix-Sekunden) jeder Ausgabe.

Bekomme ich beim erneuten Abfragen der Aufgabe einen neuen Link?

Nein. GET /v1/tasks/{taskId} liefert denselben Link. Nach Ablauf des Links ist die Datei weg, es sei denn, du hast ein Upgrade durchgeführt.

Kostet ein erneutes Ausführen der Aufgabe Geld?

Ja. Eine neue Aufgabe wird erneut berechnet, daher ist es günstiger, die Dateien gleich beim ersten Mal zu speichern.

Sind Ausgabelinks öffentlich?

Ja. Jeder, der die URL hat, kann die Datei herunterladen, aber der Pfad ist zufällig und nicht erratbar. Signierte oder private Links werden derzeit nicht angeboten.

Zählen bei persistentem Speicher auch Videos?

Ja. Jede Bild-, Video- und Audiodatei, die du behältst, zählt zur Speichergröße.

Die vollständige Referenz findest du in der Output Storage-Dokumentation und der Dokumentation zu Aufgabendetails.