So rufen Sie flux-3-max/keyframes-to-video über die HiAPI API auf: curl- und Python-Leitfaden

Was diese Integration tatsächlich tut

flux-3-max/keyframes-to-video ist eine asynchrone Task-API zur Videogenerierung aus Keyframe-Bildern. Anders als synchrone Endpunkte, die Ergebnisse in derselben HTTP-Antwort zurückgeben, nimmt dieses Modell Ihre Keyframes entgegen, erstellt eine Hintergrundaufgabe und gibt eine Aufgabenkennung zurück, mit der Sie den Fortschritt prüfen können.

Der End-to-End-Lebenszyklus gliedert sich in vier Phasen:

1. Authentifizierung — jede Anfrage trägt Ihren HiAPI API-Schlüssel.
2. Übermittlung — Keyframes und Parameter senden, um die Videoaufgabe zu starten.
3. Polling — den Aufgabenstatus wiederholt abfragen, bis ein Endzustand erreicht ist.
4. Abruf — das generierte Video von der URL herunterladen, die bei erfolgreicher Aufgabe zurückgegeben wird.

Wenn Sie diesen Lebenszyklus im Kopf behalten, bestimmt er, wie Sie Ihren Client schreiben: Übermittlung und Ergebnisabruf sind getrennte Aufrufe, und Ihre Anwendung muss eine Aufgabe tolerieren, die Dutzende Sekunden bis mehrere Minuten dauern kann. Die folgenden curl- und Python-Beispiele folgen denselben vier Phasen, sodass Sie diesen Ablauf in jede Sprache oder jeden Job-Runner portieren können.

API-Schlüssel beziehen und authentifizieren

Ihr API-Schlüssel wird im HiAPI-Dashboard ausgestellt. Behandeln Sie ihn wie ein Passwort: Er identifiziert Ihr Konto und autorisiert kostenpflichtige Aufrufe, daher sollte er niemals im Quellcode, in der Commit-Historie oder in Logausgaben erscheinen.

Die Authentifizierung wird bei jeder Anfrage als HTTP-Header übergeben:

Authorization: Bearer $HIAPI_API_KEY

In der Praxis speichern Sie den Schlüssel in einer Umgebungsvariablen und lesen ihn zur Laufzeit. Für die Shell-Beispiele exportieren Sie ihn einmal pro Sitzung:

export HIAPI_API_KEY="your-key-here"

Für Python lesen Sie ihn mit os.environ["HIAPI_API_KEY"] statt eine Zeichenkette fest zu kodieren. Fügen Sie die .env-Datei zu .gitignore hinzu, und wenn Sie Anfragen zum Debuggen protokollieren, maskieren Sie den Authorization-Header, bevor er den Log-Aggregator erreicht. Wenn der Schlüssel jemals offengelegt wurde, rotieren Sie ihn sofort über das Dashboard.

Anfrage mit curl erstellen

Eine Videoaufgabe zu übermitteln bedeutet, einen JSON-Body zu senden, der das Modell angibt und Ihre Keyframes enthält. Die genauen Feldnamen für die Keyframe-Eingabe und die Generierungsparameter sind auf der Modellseite dokumentiert, daher ist diese die maßgebliche Quelle; die folgende Struktur zeigt die Form der Anfrage.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

Die Rolle der einzelnen Teile:

• model — wählt flux-3-max/keyframes-to-video, sodass derselbe Endpunkt später auf andere Modelle umgeleitet werden kann, ohne Ihren Transportcode zu ändern.
• input.keyframes — geordnete Liste von Bild-URLs. Die Reihenfolge ist wichtig: Der erste Frame verankert den Beginn des Clips, nachfolgende Frames führen spätere Momente.
• Authorization — der oben genannte Bearer-Header.
• Content-Type — erforderlich für den JSON-Body.

Die Antwort ist ein Aufgabenobjekt mit einer Kennung. Speichern Sie diese ID; sie ist das Handle für jedes spätere Polling.

Dieselbe Anfrage in Python

Die Python-Version spiegelt den curl-Aufruf. Mit requests bleibt sie kurz, aber die Standardbibliothek funktioniert ebenso, wenn Sie Abhängigkeitsfreiheit wünschen.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

Zwei Details, die es sich zu behalten lohnt: das explizite timeout, damit hängende Verbindungen Ihren Worker nicht ewig blockieren; und raise_for_status(), damit 4xx oder 5xx als Ausnahme auftauchen statt als stille Fehler-Payload. Halten Sie die Funktion klein und rein — sie sollte übermitteln und die ID zurückgeben, mehr nicht. Polling ist eine andere Sache.

Aufgabenstatus abfragen und Ergebnisse abrufen

Die Videogenerierung braucht echte Rechenzeit, daher blockiert die API nicht, bis die Datei vorliegt. Stattdessen fragen Sie die Aufgabe ab, bis sie abgeschlossen ist. Der Status succeeded enthält die Ausgabe-URL; failed enthält einen Fehler; jeder andere Wert bedeutet weiter warten.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

Hinweise für den Produktivbetrieb:

• Polling-Intervall — einige Sekunden reichen. Den Endpunkt zu hämmern erhöht die Last, lässt die Aufgabe aber nicht schneller fertig werden.
• Deadline — begrenzen Sie stets die Gesamtwartezeit und werfen Sie bei Überschreitung laut einen Fehler, statt endlos zu schleifen.
• Download — die zurückgegebene URL ist temporär; holen Sie die Datei sofort nach erfolgreicher Aufgabe und verschieben Sie sie in Ihren eigenen Speicher.
• Entkopplung — in einer Webanwendung führen Sie diese Schleife in einem Hintergrund-Worker aus und benachrichtigen den Client über einen Webhook oder eine Queue, statt die HTTP-Anfrage offen zu halten.

Fehler und Randfälle behandeln

Die meisten Integrationsfehler fallen in vier Kategorien.

Authentifizierungsfehler (401/403). Der Schlüssel fehlt, ist fehlerhaft formatiert oder nicht mehr gültig. Prüfen Sie, ob die Umgebungsvariable tatsächlich in dem Prozess exportiert wurde, der den Aufruf ausführt — eine häufige Falle ist, dass die lokale Shell funktioniert, aber der Container oder Cron-Job die Variable nicht hat.

Eingabefehler (4xx). Nicht erreichbare Keyframe-URLs, nicht unterstützte Bildformate oder Parameter außerhalb des erlaubten Bereichs lassen die Übermittlung scheitern. Vergewissern Sie sich vor der Übermittlung, dass jede Keyframe-URL öffentlich abrufbar ist; langsame oder eingeschränkte Hosts sind die häufigste Ursache dafür, dass eine an sich korrekte Anfrage fehlschlägt.

Aufgabenfehler. Eine Aufgabe kann angenommen und dann während der Generierung fehlschlagen. Prüfen Sie stets das Fehlerfeld, statt ein abgeschlossenes Polling als Erfolg zu werten. Protokollieren Sie die Aufgaben-ID zusammen mit dem Fehler, damit Sie sie einer Support-Anfrage zuordnen können.

Timeouts und Wiederholungen. Netzwerkfehler bei der Übermittlung lassen sich in der Regel sicher mit Backoff wiederholen. Nach einer erfolgreichen Übermittlung ist das nicht der Fall — Sie könnten doppelte Aufgaben und doppelte Kosten verursachen. Lesen Sie die Antwort vor dem Wiederholen, und verwenden Sie auch in der Polling-Schleife exponentielles Backoff mit Jitter.

Ein letzter Hygienetipp: Protokollieren Sie niemals den Authorization-Header, und wenn Keyframe-URLs signierte Query-Strings enthalten, bereinigen Sie diese. Bei Zweifeln an den Feldnamen oder Limits dieses Modells konsultieren Sie die flux-3-max/keyframes-to-video-Dokumentation und übernehmen Sie diese Werte exakt in Ihren Client.