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

Funktionen und Einsatzszenarien von flux-3-max/text-to-video

flux-3-max/text-to-video ist der Text-zu-Video-Endpunkt auf HiAPI: Sie senden einen Prompt, der eine Szene beschreibt, und das Modell liefert einen generierten Videoclip zurück. Wenn Sie eine textliche Idee statt fertigen Materials haben – etwa Produktteaser, kurze Social-Media-Videos, Storyboard-Vorschauen oder in großem Umfang generierte B-Roll-Aufnahmen – und den Generierungsprozess als gehostete Aufgabe statt als eigene Laufzeit betreiben möchten, ist es das passende Werkzeug.

Es eignet sich für Workflows, in denen Video nur ein Glied in einem größeren Ablauf ist. Ein Skriptgenerator erzeugt Prompts, flux-3-max/text-to-video verwandelt sie in Videoclips, und Ihre Anwendung speichert oder liefert die Ergebnisse aus. Da der Aufruf asynchron ist, eignet es sich auch für Backend-Dienste, die eine Anfrage nicht für die Dauer des Renderings offen halten können.

Verwenden Sie es nicht, wenn Sie frame-genaue Bearbeitungen an bestehenden Videos benötigen oder Ihr Prompt eigentlich nur ein statisches Bild beschreibt – für Letzteres ist der Text-zu-Bild-Endpunkt günstiger und schneller. Wenn die Ausgabe auf bereitgestelltes Material reagieren muss, sollte die Bild-zu-Video-Variante verwendet werden. Betrachten Sie flux-3-max/text-to-video als Einstieg für die Generierung vom Prompt zum Videoclip und gestalten Sie Ihre Integration rund um das Einreichen von Aufgaben statt um synchrone Antworten.

Anfragestruktur: Endpunkt, Authentifizierung und Payload

Jede Anfrage an flux-3-max/text-to-video besteht aus drei Teilen: dem Endpunktpfad, dem Authentifizierungs-Header und einem JSON-Anfragekörper, der das Modell und seine Eingaben angibt.

Authentifizierung

HiAPI verwendet Bearer-Token. Legen Sie Ihren API-Schlüssel im Authorization-Header ab:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Halten Sie den Schlüssel serverseitig. Betten Sie ihn nicht in Client-Code ein und committen Sie ihn nicht ins Versionskontrollsystem; laden Sie ihn in der Entwicklung aus Umgebungsvariablen und in der Produktion aus einem Secret Manager.

Modellbezeichner

Im Anfragekörper wählt das Feld model den Endpunkt. Verwenden Sie den exakten Bezeichner flux-3-max/text-to-video; ein Tippfehler an dieser Stelle ist die häufigste Ursache für abgelehnte Anfragen.

Payload-Struktur

Der minimale Anfragekörper enthält den Modellnamen und den Prompt:

{
  "model": "flux-3-max/text-to-video",
  "prompt": "Bei Sonnenaufgang langsam über einen nebligen Kiefernwald fliegen, filmische Beleuchtung"
}

Optionale Felder – Dauer und native Audio-Umschalter – werden im nächsten Abschnitt behandelt. Da die Generierung asynchron ist, ist die unmittelbare Antwort auf diese POST-Anfrage ein Aufgabenobjekt mit einer Kennung, die Sie abfragen müssen, statt eines fertigen Videos. Gestalten Sie Ihren Code so, dass er zuerst diese Kennung liest und alles andere danach.

Dauer und natives Audio steuern

Zwei Steuerungen auf Anfrageebene bestimmen das Ergebnis: die Länge des Videoclips und ob das Modell zusammen mit dem Video auch Audio generiert.

Dauer

Legen Sie die Cliplänge über das Feld duration in der Payload fest. Wählen Sie die kürzeste Dauer, die die Erzählung erfüllt – kurze Clips rendern schneller, sind leichter zu prüfen, und Sie können jederzeit einen weiteren anfordern. Validieren Sie den Wert vor dem Absenden anhand des in der Dokumentation von flux-3-max/text-to-video angegebenen Bereichs; Dauern außerhalb des Bereichs werden beim Absenden abgelehnt, und das lokale Abfangen spart einen Roundtrip.

Natives Audio

Der native Audio-Umschalter bestimmt, ob das Modell zusammen mit dem Videoclip eine Tonspur generiert. Aktivieren Sie ihn, wenn das Video mit Ton angesehen wird, und deaktivieren Sie ihn, wenn das Video stummgeschaltet, untertitelt oder in der Postproduktion separat vertont wird. Audio zu generieren, das Sie ohnehin verwerfen, erhöht nur die Aufgabenzeit ohne Nutzen.

Bewusst entscheiden

Vermeiden Sie es, die Entscheidung den Standardwerten zu überlassen. Für eine schnelle Storyboard-Prüfung reicht oft ein kurzer stummer Clip. Für finales Social-Media-Material kann ein längerer Clip mit nativem Audio das Ziel sein. Kodieren Sie diese Wahl in Ihrer Anwendungskonfiguration statt an der Aufrufstelle, damit Sie sie funktionsweise ändern können, ohne den Anfragecode anzupassen. Senden Sie nur die Felder, die Sie tatsächlich überschreiben wollen, und lassen Sie den Endpunkt für die übrigen Felder seine Standardwerte anwenden.

Ein funktionierender curl-Aufruf

Der schnellste Weg, Anmeldedaten und Payload zu überprüfen, ist das Einreichen einer Aufgabe mit einem einzigen curl-Aufruf.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "Ein Papierboot treibt über eine regennasse Straße, warme Straßenlaternen, geringe Schärfentiefe",
    "duration": 5,
    "native_audio": false
  }'

Setzen Sie HIAPI_BASE_URL und HIAPI_API_KEY zuerst in Ihrer Shell. Die Dauer- und Audiowerte hier sind nur Beispiele – verwenden Sie Werte innerhalb des in der Dokumentation des Modells angegebenen Bereichs.

Die unmittelbare Antwort lesen

Die Antwort ist ein Aufgabenobjekt, kein Video. Sie enthält eine job_id (oder eine gleichwertige Kennung) sowie einen Status wie queued oder processing. Speichern Sie diese Kennung; sie ist Ihr Handle für jeden weiteren Aufruf. Wenn die Antwort wie ein Fehlerobjekt aussieht, prüfen Sie Statuscode und Meldung, bevor Sie es erneut versuchen – eine fehlerhafte Payload schlägt jedes Mal auf dieselbe Weise fehl.

Eine erfolgreiche Einreichung bedeutet nur, dass die Aufgabe angenommen wurde, mehr nicht. Suchen Sie nicht in der ersten Antwort nach einer Video-URL; sie erscheint dort erst, wenn die Aufgabe abgeschlossen ist.

Den Lebenszyklus asynchroner Aufgaben behandeln

Die Videogenerierung dauert Sekunden bis Minuten, daher modelliert HiAPI sie als Aufgabe. Ihr Client reicht einmal ein und prüft dann den Status, bis die Aufgabe einen Endzustand erreicht.

Status

Aufgaben durchlaufen queued, dann processing und schließlich einen Endzustand – completed oder failed. Nur Endzustände sind final; jeder Zwischenzustand bedeutet, weiter zu warten.

Abragen ohne Bombardement

Fragen Sie den Status-Endpunkt mit der gespeicherten Aufgabenkennung ab. Zwei Regeln halten das Abfragen gesund:

• Warten Sie zwischen den Abfragen. Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es schrittweise, oder verwenden Sie ein festes Intervall, das deutlich länger als die typische Wartezeit ist. Den Status-Endpunkt zu bombardieren bringt keinen Nutzen.
• Setzen Sie Obergrenzen. Begrenzen Sie die Gesamtwartezeit und die Gesamtzahl der Versuche. Ist die Aufgabe dann noch nicht abgeschlossen, melden Sie dies an Ihre Anwendung statt in einer endlosen Schleife zu verharren.

Blockieren Sie in Web-Handlern nicht den Anfraget-Thread mit einer Abfrageschleife. Reichen Sie ein, speichern Sie die Aufgabenkennung, antworten Sie sofort und lassen Sie einen Hintergrund-Worker oder den Client den Lebenszyklus abfragen. In Batch-Szenarien genügt eine einfache Schleife mit sleep.

Das Ergebnis lesen

Wenn die Aufgabe als completed gemeldet wird, trägt die Antwort eine Ausgabe-Referenz – eine Video-URL oder ein Material-Handle, das Ihre Anwendung herunterladen oder streamen kann. Im Fehlerfall lesen Sie das Feld error; es nennt in der Regel die Ursache (ungültige Parameter, Inhaltsablehnung, interner Fehler). Protokollieren Sie die Aufgabenkennung zusammen mit der Fehlermeldung, damit Support-Anfragen oder Wiederholungen nachvollziehbar sind. Betrachten Sie ein fehlendes Ausgabefeld niemals als Erfolg – prüfen Sie den Status explizit.

Dieselbe Anfrage in Python

Der curl-Ablauf lässt sich direkt auf Python übertragen. Ein minimaler Client braucht das Einreichen, eine Abfrageschleife und genug Fehlerbehandlung, um eine fehlerhafte Anfrage von einer langsamen Aufgabe zu unterscheiden.

import os, time
import requests

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

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

Hinweise zur Implementierung

raise_for_status() trennt Transport- und HTTP-Fehler (Authentifizierung, fehlerhafte Payload) von Fehlern auf Aufgabenebene, die innerhalb einer erfolgreichen Antwort auftreten. Die Prüfung auf failed liest das Feld error explizit, statt einen Status completed anzunehmen. Die Obergrenze der Versuche verwandelt unbegrenztes Warten in eine vorhersehbare Ausnahme.

Umwickeln Sie das Abfragen in der Produktion mit einer Retry-Strategie für vorübergehende Netzwerkfehler und verwenden Sie eine einzige requests.Session wieder. Wenn Sie viele Aufgaben ausführen, verlagern Sie wait in einen Worker-Thread statt in den Anfragepfad.

Häufige Fehler beheben

Die meisten Integrationsprobleme lassen sich in einige Kategorien einordnen. Jede hat eine konkrete Prüfmethode.

Authentifizierungsfehler

401 oder 403 bedeutet, dass der Schlüssel fehlt, abgelaufen oder fehlerhaft formatiert ist. Vergewissern Sie sich, dass der Authorization-Header vorhanden ist, das Schema Bearer verwendet und die Umgebungsvariable in der Laufzeit tatsächlich gesetzt ist – nicht nur in Ihrer Shell.

Fehlerhafte Payload

400 bedeutet in der Regel, dass der Anfragekörper nicht dem Schema entspricht. Prüfen Sie, dass das JSON parsbar ist, model exakt flux-3-max/text-to-video entspricht und die Anfrage Content-Type: application/json sendet. Serialisieren Sie mit einer JSON-Bibliothek statt Strings von Hand zu bauen.

Ungültige Parameterwerte

Eine Dauer außerhalb des dokumentierten Bereichs, ein unbekannter Feldname oder ein falscher Typ beim Audio-Umschalter führen beim Absenden zur Ablehnung. Validieren Sie vor dem Senden lokal anhand der Parameter in der Modelldokumentation.

Zu frühes Abfragen

Sofortiges und wiederholtes Abfragen nach dem Absenden lässt die Aufgabe nicht schneller fertig werden. Verwenden Sie Backoff oder ein festes Intervall und lassen Sie das Aufgabenobjekt Ihnen mitteilen, wann es den Status queued überschritten hat.

Unbehandelte Aufgabenfehler

Eine Aufgabe, die failed erreicht, bedeutet nicht unbedingt, dass Ihre Anfrage einen Bug hat – es kann eine Inhaltsablehnung oder ein interner Fehler sein. Lesen Sie die Fehlermeldung, protokollieren Sie die Aufgabenkennung und entscheiden Sie, ob Sie mit einem geänderten Prompt erneut versuchen oder es melden.

Die Einreichungsantwort als Ergebnis behandeln

Wenn Ihr Code nach dem Absenden sofort eine Video-URL erwartet, wird er scheitern. Die erste Antwort ist eine Aufgabe; nur ein Endzustand trägt die Ausgabe. Sind diese sechs Prüfungen erst einmal vorhanden, lassen sich die meisten Integrationsprobleme lösen.