So verwendest du die hiapi API für KI-Videobearbeitung mit flux-3

„Bearbeiten“ hat hier eine spezifische Bedeutung: flux-3 (FLUX.3 Video von Black Forest Labs) erweitert einen bestehenden Clip – es setzt dessen Bewegung, Kameraführung und Ton fort und erzeugt neues Bildmaterial – oder es baut eine Einstellung aus einer geordneten Reihe von Keyframe-Bildern auf. Es schneidet, kürzt, maskiert, coloriert oder bearbeitet vorhandenes Material nicht in-place. Wenn du hier nach einem Cutter suchst, ist die FAQ unten der schnellste Weg, um vor dem Schreiben von Code zu entscheiden, ob flux-3 wirklich zu dir passt.

Worin es wirklich gut ist: aus einem vorhandenen Video eine Fortsetzung generieren, die dasselbe Subjekt, dieselbe Bildsprache und dasselbe Audio beibehält – geeignet, um eine zu früh endende Einstellung zu verlängern oder mehrere generierte Segmente zu einer längeren Einstellung zu verketten. Der andere Modus nimmt eine Reihe von Standbildern als geordnete Keyframes und generiert die Bewegung dazwischen – das ist wie ein Schnitt auf Basis eines Storyboards, allerdings ohne dass ein vorhandenes Video beteiligt ist.

1. Was du brauchst

Einen hiapi API-Schlüssel (sk-...) aus dem Dashboard. flux-3 wird wie alle anderen hiapi-Modelle über die einheitliche task-API aufgerufen, es gibt hier also keine modellspezifische Einrichtung – wenn du zuvor schon ein anderes hiapi-Videomodell aufgerufen hast, hast du bereits alles Nötige.

2. Minimal lauffähiges Beispiel

Erstelle eine Aufgabe und poll sie dann (oder nutze einen Callback – siehe Produktionsmuster), bis sie einen Endzustand erreicht.

# 1. Aufgabe erstellen – Fortsetzungsmodus (start_video)
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "Schwenk fortsetzen, Kamera driftet weiter nach rechts, gleiche Beleuchtung beibehalten",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Pollen bis zum Endzustand
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video ist eine öffentliche HTTPS-URL, die auf eine MP4-Datei verweist (Quellmaterial bis maximal 50 MB und 15 Sekunden) – das ist der Clip, den flux-3 fortsetzt. duration ist eine ganze Zahl von 5 bis 20 Sekunden und steuert die Länge des neu generierten Segments, nicht die Länge der zusammengesetzten Ausgabe. resolution ist 720p oder 1080p; aspect_ratio akzeptiert auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 oder 9:16. generate_audio ist ein Boolean – wenn true, werden die vom Modell generierten Umgebungsgeräusche direkt in die Ausgabe-MP4 eingebettet, nicht als separate Audiodatei. Setze draft: true, während du den Prompt iterierst; Entwurfsaufgaben sind günstiger, erzwingen aber, dass resolution nur 720p sein kann (Anfragen mit sowohl draft: true als auch resolution: "1080p" werden abgelehnt).

Keyframe-Storyboard (keine Bearbeitung von vorhandenem Material)

Der alternative Eingabemodus ersetzt start_video durch image_urls – ein geordnetes Array mit 1 bis 10 Bild-URLs, die flux-3 als Storyboard behandelt und zwischen denen es die Bewegung in Reihenfolge generiert:

{
  "model": "flux-3",
  "input": {
    "prompt": "Fließend durch jede Szene dolly-fahren",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls und start_video sind zwei verschiedene Aufgabenformen auf demselben Modell – sende sie nicht zusammen in einer Anfrage. Verwende image_urls, wenn du eine Einstellung von Grund auf aus Standbildern aufbaust; verwende start_video, wenn du vorhandenes generiertes (oder Quell-)Material hast, das du vorwärts fortsetzen willst.

3. Produktionsmuster

Nutze Callbacks statt Polling im großen Maßstab. Übergib im selben Request-Body ein callback-Objekt, statt in einer Schleife zu pollen:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" wird nur einmal ausgelöst, wenn die Aufgabe einen beliebigen Endzustand erreicht – sowohl succeeded als auch failed sind Endzustände, also entdupliziere deinen Webhook-Handler anhand der taskId, statt anzunehmen, dass ein Callback nur Erfolg bedeutet. Polling von GET /v1/tasks/:id eignet sich besser für lokales Debugging, einmalige Aufgaben mit geringer Frequenz oder als Abgleich-Fallback, falls ein Callback nicht ankommt.

Idempotenz. Wiederholungen nach Timeouts oder Verbindungsabbrüchen können unbeabsichtigt doppelte (abrechenbare) Aufgaben erzeugen – verfolge die id der Aufgabe, die der Erstellungsaufruf zurückgibt, und verwandle einen Retry in ein GET auf diese id, bevor du erwägst, eine neue Aufgabe einzureichen.

Ausgabe-URLs laufen ab. Das Feld expireAt an jedem Ausgabeeintrag ist kein Dekorationselement – egal ob du von einem Callback oder per Polling vom Erfolg der Aufgabe erfährst, lade das Video sofort nach erfolgreichem Abschluss herunter und speichere es dauerhaft in deinem eigenen Speicher.

Authentifizierungsfehler. Ein falscher oder fehlender Schlüssel liefert HTTP 401 mit dem Inhalt {"error": {"code": "permission_denied", ...}}. Prüfe diesen Status/Code explizit, statt anzunehmen, dass jeder Nicht-2xx-Status bedeutet, die Generierung selbst sei fehlgeschlagen – „mein Schlüssel ist falsch“ und „das Modell hat meine Eingabe abgelehnt“ erfordern unterschiedliche Korrekturen.

Validiere Medien-URLs vor dem Absenden. start_video und image_urls prüfen Typ und Format, aber nicht, ob die Datei unter der URL tatsächlich existiert oder dekodierbar ist – eine syntaktisch gültige, aber defekte URL erzeugt trotzdem eine Aufgabe, die erst nach einigen Sekunden Laufzeit fehlschlägt, statt schon beim Absenden abgelehnt zu werden. Bevor du URLs in Batch-Aufgaben einspeist, vergewissere dich, dass sie tatsächlich auflösen.

4. Verwandte Seiten

• flux-3-Modellseite – vollständige Parameterreferenz, Playground und die aktuellen Preise pro Sekunde und Auflösung für alle drei Modi (Text-zu-Video, Keyframe-Storyboard und Fortsetzung).
• Dokumentation zum Erstellen von Aufgaben – vollständige /v1/tasks-Request/Response-Referenz einschließlich Callback-Optionen.
• Authentifizierungsdokumentation – wie der Authorization: Bearer sk-...-Header und Schlüssel-Scopes funktionieren.
• Erst- und Letztbild-Steuerung in KI-Videos – ein verwandter Ansatz für Modelle, die zwischen zwei Standbildern interpolieren, falls der Multi-Keyframe-Storyboard-Modus von flux-3 für deine Einstellung nicht granular genug ist.
• hiapi-Preise – aktuelle Tarife (Fortsetzungen sind teurer als Standardgenerierung, der Entwurfsmodus ist günstiger als beide – schau auf der Live-Seite nach, statt Zahlen hart zu kodieren).

5. Häufig gestellte Fragen

Kann flux-3 vorhandene Videos zuschneiden, kürzen, maskieren oder colorieren? Nein. Der „Video-zu-Video“-Modus von flux-3 ist Fortsetzung – es generiert neues Bildmaterial, das Subjekt, Kamerabewegung und Ton des Quellclips fortsetzt. Bereits vorhandene Frames werden nicht verändert. Derzeit kann kein hiapi-Modell zeitleistenartiges Schneiden/Kürzen oder Bearbeiten maskierter Bereiche in Videos durchführen.

Was ist der Unterschied zwischen Fortsetzung und Keyframe-Storyboard? Fortsetzung (start_video) benötigt eine vorhandene Videodatei und erweitert sie. Keyframe-Storyboard (image_urls) benötigt nur Standbilder und generiert die Bewegung dazwischen – kein Quellvideo nötig. Es sind sich gegenseitig ausschließende Eingaben auf derselben flux-3-Modell-id.

Kann ich start_video und image_urls in einer Anfrage zusammen verwenden? Nein – pro Aufgabe wählst du einen Modus. Beide zusammen zu senden ist keine unterstützte Eingabeform.

Funktioniert draft: true im Fortsetzungsmodus? Ja, und es ist der günstigere Weg, den Fortsetzungs-Prompt zu iterieren, bevor du einen Lauf in voller Auflösung startest – aber wie im Standardmodus ist auch die Entwurfsfortsetzung auf 720p beschränkt.

Warum schlägt meine Aufgabe fast sofort fehl, statt die übliche Generierungszeit zu brauchen? Die häufigste Ursache ist, dass ein start_video- oder image_urls-Eintrag zum Zeitpunkt der Anfrage nicht tatsächlich zu einer gültigen Datei auflöst – die API akzeptiert syntaktisch korrekt formatierte URLs, ohne sie synchron abzurufen, daher äußert sich ein defekter Link als schneller failed-Status statt als vorgelagerter Validierungsfehler.

Wie lang darf der Quellclip im Fortsetzungsmodus sein? Maximal 15 Sekunden und 50 MB im MP4-Format. Längere oder größere Quelldateien werden als start_video-Eingabe nicht akzeptiert.