So rufen Sie flux-3-video über die HiAPI API auf: curl, Python und praxistaugliche Request-Beispiele

Was flux-3-video über die API bietet

Bevor Sie die erste Codezeile schreiben, ist es hilfreich zu verstehen, was das Modell flux-3-video über die HiAPI API tatsächlich leisten kann. Diese Endpunkt-Familie umfasst zwei Aufrufmodi, die dieselbe Request-Struktur teilen, sowie eine optionale Audio-Funktion, die Sie je nach Anwendungsfall aktivieren oder ignorieren können.

Die zwei Aufrufmodi

• Text-zu-Video – Sie senden einen Text-Prompt und erhalten einen neu generierten Videoclip. Verwenden Sie diesen Modus, wenn Sie nur eine Idee haben und das Modell Bewegung, Bildkomposition und Rhythmus erzeugen soll.
• Videofortsetzung – Sie senden einen vorhandenen Videoclip (oder einen Verweis darauf) sowie eine Anweisung, und das Modell erweitert ihn. Verwenden Sie diesen Modus, wenn Sie bereits Material haben und mehr Inhalte ohne sichtbare Nahtstellen wünschen.

Natives Audio

Das Modell kann außerdem während der Videogenerierung natives Audio erzeugen, gesteuert durch optionale Parameter in derselben Request-Payload. Da diese Parameter optional sind, können reine Video-Workflows sie vollständig ignorieren – Sie lassen einfach die Audio-Felder weg, und die Anfrage verhält sich genau wie ohne sie.

Das zentrale mentale Modell, auf dem der Rest dieses Leitfadens aufbaut, lautet: Dies sind keine zwei voneinander unabhängigen APIs und auch keine zwei getrennten Tutorials. Es sind zwei Formen derselben Anfrage; hat man das gemeinsame Grundgerüst einmal verstanden, ist der Wechsel zwischen beiden nur das Austauschen einiger Eingaben. Alles andere – Anmeldedaten, Request-Header, Modellkennung, Antwortverarbeitung – bleibt gleich.

Dieses Design ist bewusst gewählt. Es bedeutet, dass Ihr Authentifizierungscode, Ihre Fehlerbehandlung, Ihre Retry-Logik und Ihre Antwortauswertung nur einmal geschrieben und in beiden Modi wiederverwendet werden können; auch das spätere Hinzufügen von Audio zwingt Sie nicht zu einem Rewrite.

Authentifizierung, Endpunkt und Aufbau der Anfrage

Jeder Aufruf von flux-3-video folgt demselben Grundgerüst. Einmal verstanden, werden die beiden Aufrufmodi zu Varianten desselben Themas.

Anmeldedaten

HiAPI authentifiziert Anfragen über einen API key. Sie übergeben ihn im Request-Header, üblicherweise als Bearer-Token. Schreiben Sie den Schlüssel nicht in den Quellcode – lesen Sie ihn aus einer Umgebungsvariable oder einem Secret-Manager, damit er niemals in die Versionskontrolle gelangt:

export HIAPI_API_KEY="your-key-here"

Endpunkt und Modellkennung

Der Aufruf geht an die Basis-URL der HiAPI API, und die Payload gibt das Modell explizit über die Kennung flux-3-video an. Dass der Modellname im Request-Body statt hartkodiert in der URL steht, bedeutet, dass derselbe Client-Code später mit einer einzigen Zeilenänderung auf ein anderes Modell zeigen kann.

Die gemeinsame Payload-Struktur

Unabhängig vom Modus ist die Payload ein JSON-Objekt, das konzeptionell aus drei Teilen besteht:

• Das model-Feld – immer flux-3-video.
• Die modusdefinierenden Eingaben – im Text-zu-Video-Modus ein Prompt; im Fortsetzungsmodus ein Quellvideoclip plus ein Prompt. Dies ist der einzige Teil, der sich zwischen den beiden Modi wesentlich ändert.
• Optionale Modifikatoren – Audio-Parameter und weitere Einstellungen. Lassen Sie sie weg, erhalten Sie das Standardverhalten.

Die Pseudostruktur einer Anfrage sieht so aus:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

Das ist die gesamte Idee: eine Modellkennung, ein verschachteltes input-Objekt mit den modusspezifischen Feldern und optionale Schlüssel, die nur bei Bedarf hinzugefügt werden. Die folgenden Abschnitte erläutern die Besonderheiten der einzelnen Modi.

Text-zu-Video: Ihr erster funktionierender curl-Request

Hier ist eine minimale, aber vollständige Anfrage, die aus einem Prompt einen Videoclip generiert. Sie setzt voraus, dass HIAPI_API_KEY in Ihrer Shell exportiert wurde.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

Die Aufgabe der einzelnen Felder

• Authorization – trägt Ihr Bearer-Token. Fehlt es, wird die Anfrage abgelehnt, bevor irgendeine Generierung beginnt.
• Content-Type: application/json – der Request-Body ist JSON, deklarieren Sie das also; das Weglassen ist eine häufige Ursache für verwirrende 4xx-Antworten.
• model – legt flux-3-video als Zielmodell fest.
• input.prompt – die einzige erforderliche kreative Eingabe im Text-zu-Video-Modus. Schreiben Sie sie wie eine Kamerabeschreibung: Subjekt, Bewegung, Bildkomposition, Licht, Stimmung.

Prompt-Tipps, die sich lohnen

Da der Prompt im diesem Modus der einzige kreative Hebel ist, bestimmt seine Qualität direkt das Ergebnis. Zwei Gewohnheiten helfen:

• Beschreiben Sie Bewegung, nicht nur Inhalt. „A dolly shot through…“ (eine Kamerafahrt durch…) gibt dem Modell ein animierbares Kameravehalten; eine statische Beschreibung lässt ihm keinen Spielraum.
• Bleiben Sie konkret. Konkrete Hinweise zu Licht und Material („wet asphalt“, „neon reflections“) führen oft zu kohärenteren Bildern als abstrakte Adjektive.

Nachdem Sie diese Anfrage ausgeführt und die Antwort geprüft haben, haben Sie Schlüssel, Header und Basis-Payload verifiziert – die Grundlage für alles Weitere.

Videofortsetzung: einen vorhandenen Clip erweitern

Die Fortsetzung nutzt das Grundgerüst aus dem vorigen Abschnitt, aber die Form des input-Objekts ändert sich. Der Prompt steht nicht mehr allein, sondern ist mit dem Quellclip gepaart, den das Modell erweitern soll.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

Was sich gegenüber Text-zu-Video ändert

• Eine Video-Eingabe kommt hinzu. Sie liefern den vorhandenen Clip, auf dem das Modell aufbauen soll. Das ist der entscheidende Unterschied zwischen den beiden Modi.
• Der Prompt wird lenkend statt erzeugend. Im Text-zu-Video-Modus beschreiben Sie die gesamte Szene; hier beschreiben Sie, was als Nächstes passiert. Schreiben Sie ihn als Fortsetzungsanweisung: wohin die Kamera geht, was ins Bild tritt, wie sich die Szene entwickelt.
• Alles andere bleibt identisch. Derselbe Endpunkt, dieselben Header, dieselbe Modellkennung, dieselbe input-Hülle. Ihr Client-Code muss erst beim Zusammenbauen der Payload verzweigen.

Konsistenz an der Nahtstelle wahren

Das Modell muss die Anmutung des Quellclips treffen, um sichtbare Schnitte zu vermeiden. Kurze, konkrete Anweisungen, die den vorhandenen Stil beibehalten, funktionieren oft besser als lange Beschreibungen, die die Szene neu erfinden. Driftet die erste Fortsetzung, sollten Sie den Prompt näher am tatsächlichen Inhalt des Quellclips halten, statt anderswo mehr Details hinzuzufügen.

Hinweis zu Clip-Verweisen

Die genaue Eingabekonvention für den Quellclip wird durch das Input-Schema dieses Modells auf HiAPI definiert. Folgen Sie diesem Schema, statt das Feldformat zu raten – es ist die maßgebliche Quelle dafür, was als Fortsetzungseingabe akzeptiert wird.

Native Audio-Parameter hinzufügen

Natives Audio ist der Punkt, an dem das Muster der optionalen Modifikatoren seinen Wert zeigt. Die Audio-Parameter liegen im selben input-Objekt wie die übrigen Felder, und da sie optional sind, bleiben die Anfragen der beiden vorigen Abschnitte ohne sie weiterhin gültig.

Wo sie hingehören

Die Audio-Einstellungen gehören in input, neben prompt und (im Fortsetzungsmodus) video. Konzeptionell:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

Reine Video-Workflows sicher halten

Die wichtige Disziplin hier ist einfach: Behandeln Sie den Audio-Block als rein additiv.

• Setzen Sie Audio-Felder nicht explizit auf einen „aus“-Wert – lassen Sie sie einfach weg. Das Fehlen des Blocks ist sauberer und kollidiert weniger wahrscheinlich mit künftigen Schema-Änderungen.
• Bauen Sie die Payload inkrementell auf. Beginnen Sie mit dem minimalen Body und fügen Sie den audio-Schlüssel nur in dem Codepfad hinzu, in dem der Nutzer tatsächlich Audio verlangt. So bleibt Ihr Standardpfad exakt identisch mit den reinen Video-Beispielen.
• Prüfen Sie das Schema auf die genauen Flag-Namen und akzeptierten Werte, bevor Sie Audio in die Produktion bringen. Die Parameternamen werden durch das Input-Schema dieses Modells auf HiAPI definiert; der obige Block zeigt nur die Position und garantiert nicht die Feld-Schreibweise.

Wann aktivieren

Aktivieren Sie Audio, wenn das Ergebnis ein fertiger, in sich geschlossener Videoclip ist – Social-Media-Inhalte, Präsentationen, kurze erzählerische Werke. Lassen Sie es aus, wenn Sie nachgelagert eine eigene Tonspur oder einen Voiceover hinzufügen; Audio zu erzeugen, das Sie später ohnehin verwerfen, verschwendet Rechenleistung in der Pipeline.

Da Audio zusammen mit allem anderen in derselben Payload liegt, gibt es keinen separaten Aufruf, keine zweite Anmeldedaten und – außer dem Auslesen dessen, was die Antwort zurückgibt – auch keine zusätzliche Verzweigung in der Antwortverarbeitung.

Dieselbe Anfrage in Python schreiben

Den curl-Aufruf nach Python zu übertragen ist mechanisch, weil die Request-Struktur identisch ist. Das folgende Beispiel verwendet nur die Standardbibliothek und läuft daher in jeder Umgebung; wenn Sie requests oder httpx bevorzugen, lässt sich die Struktur direkt übertragen.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

Warum das so organisiert ist

• Eine Funktion, zwei Modi. Der Parameter video ist optional; ist er None, erzeugt die Funktion eine Text-zu-Video-Anfrage. Ist er gesetzt, erzeugt dieselbe Funktion eine Fortsetzungsanfrage. Kein separater Client, keine doppelten Header.
• Audio muss explizit aktiviert werden. Das Flag audio ist standardmäßig False, sodass der Audio-Block niemals hinzugefügt wird, außer er wird ausdrücklich verlangt – genau das zuvor beschriebene Muster.
• Der Schlüssel kommt aus der Umgebung. Der API key wird aus HIAPI_API_KEY gelesen und niemals hartkodiert.

Zum Anpassen ersetzen Sie einfach die print-Aufrufe durch die Operation, die Ihre Pipeline braucht – die Antwort in ein Manifest schreiben, Folgeaufgaben einreihen oder eine Queue benachrichtigen. Die Request-Logik selbst muss sich nicht ändern.

Fehlerbehebung und Checkliste für die Produktion

Wenn ein Aufruf fehlschlägt, arbeiten Sie die folgende Liste der Reihe nach durch – sie deckt die allermeisten Probleme ab.

Diagnose-Checkliste

• 401 oder Authentifizierungsfehler – wurde HIAPI_API_KEY tatsächlich in der Shell bzw. dem Prozess exportiert, der den Code ausführt? Ein in einem Terminal gesetzter Schlüssel wird nicht an einen Cron-Job weitergegeben.
• 415 oder unerwartete Parsing-Fehler – ist Content-Type: application/json vorhanden? Das Weglassen ist der klassischste stille Fehler.
• Fortsetzungsaufruf gibt 4xx zurück – enthält Ihre Payload den Quellclip in der Form, die das Input-Schema des Modells erwartet? Ein fehlerhafter Clip-Verweis schlägt fehl, bevor die Generierung beginnt.
• Audio fehlt in der Ausgabe – ist der audio-Block tatsächlich in die Payload gelangt? Protokollieren Sie beim Debuggen den serialisierten Request-Body; ein gebautes Dictionary, bei dem man vergisst, den Schlüssel anzuhängen, ist schnell passiert.
• input leer oder abgeschnitten – drucken Sie exakt das JSON, das Sie tatsächlich senden. Fast jeder „seltsame“ Fehler löst sich auf, sobald man den Body sieht, der wirklich über die Leitung geht.

Vor dem Go-live

• Schlüssel niemals hartkodieren. Immer Umgebungsvariablen oder einen Secret-Manager verwenden.
• Request-Body und Response-Body protokollieren, zumindest in der Staging-Umgebung. Fehler ohne die exakte Payload zu reproduzieren, ist reines Raten.
• Optionale Felder als optional behandeln. Payload inkrementell aufbauen – zuerst den minimalen Body, dann video hinzufügen, zuletzt audio nur bei Bedarf. So bleibt Ihr Standardpfad konsistent mit den Dokumentationsbeispielen.
• Die Moduswahl im eigenen Code explizit sichtbar halten. Eine Funktion mit optionalem video-Parameter ist in Ordnung; einen Boolean drei Ebenen tief zu vergraben nicht.
• Immer wenn Sie Felder hinzufügen, prüfen Sie erneut das Input-Schema dieses Modells auf HiAPI. Es ist die maßgebliche Referenz für Parameternamen und akzeptierte Formate und stets aktueller als jedes Tutorial.

Die Kernaussage lohnt der Wiederholung: Text-zu-Video, Fortsetzung und natives Audio sind drei Varianten derselben Request-Form. Verstehen Sie das Grundgerüst einmal, ist jede neue Fähigkeit nur eine additive Änderung statt eines Rewrites. Viel Spaß beim Bauen.