FLUX 3 Max API: Text-zu-Video, Bild-zu-Video und Keyframes auf hiapi

Zusammenfassung

• FLUX 3 Max auf hiapi sind drei eigenständige Modell-IDs am selben POST /v1/tasks-Endpunkt: flux-3-max/text-to-video, flux-3-max/image-to-video und flux-3-max/keyframes-to-video. Um den Modus zu wechseln, ändern Sie nur model und ein Eingabefeld.
• Alle drei erzeugen Clips von 5–20 Sekunden in 720p oder 1080p; abgerechnet wird nach Ausgabesekunden und Auflösung. Aktuelle Preise finden Sie unter /en/pricing.
• Die Frame-Nummernregeln für Keyframes werden beim Einreichen nicht geprüft. Bei einer fehlerhaften Zeitachse liefert die API dennoch HTTP 200 und eine taskId, aber der Task schlägt nach etwa 2 Sekunden fehl. Validieren Sie daher vorab lokal.

Diese Anleitung behandelt die Max-Stufe. Das Basis-flux-3-Modell mit Entwurfsmodus und Videofortsetzung finden Sie im FLUX.3 Video-API-Leitfaden, das Bearbeiten vorhandenen Materials unter flux-3 Videobearbeitung.

Voraussetzungen

Erstellen Sie einen Schlüssel in der hiapi-Konsole und exportieren Sie ihn:

export HIAPI_KEY=sk-your-key

Der Anfrageablauf ist in allen Modi gleich: POST /v1/tasks liefert eine taskId, dann pollen Sie GET /v1/tasks/<taskId> (oder nutzen einen Callback), bis status success ist, und laden anschließend data.output[0].url herunter.

Welche Modell-ID für welche Eingabe

Vorhandene Eingabe	Modell-ID	Zu ändernde Eingabe
Nur ein Text-Prompt	flux-3-max/text-to-video	prompt
Ein Standbild (optional zusätzlich ein Endframe)	flux-3-max/image-to-video	image_url, optional end_image_url
1–10 Bilder, die zu bestimmten Zeitpunkten liegen müssen	flux-3-max/keyframes-to-video	keyframes: [{image_url, frame_index}]

Von allen drei gemeinsam genutzte optionale Felder: duration (ganzzahlige Sekunden, 5–20, Standard 5), resolution (720p oder 1080p), aspect_ratio (auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16), generate_audio (Boolescher Wert, standardmäßig aktiviert) und reasoning_level (low oder high, Standard high). Modellseiten: Text-zu-Video, Bild-zu-Video, Keyframes-zu-Video.

Minimalbeispiel: Text-zu-Video mit curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "input": {
      "prompt": "a slow aerial shot of ocean waves at sunrise, photorealistic",
      "duration": 5,
      "resolution": "720p",
      "generate_audio": false,
      "reasoning_level": "low"
    }
  }'

Bei gültiger Anfrage wird {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"} zurückgegeben. Danach:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... -H "Authorization: Bearer $HIAPI_KEY"

generate_audio plus 5 Sekunden low-Reasoning ist eine günstige Möglichkeit, Prompts zu testen; laut Modellseite verändert Audio den Preis nicht.

Ein Python-Helferskript für alle drei Modi

# pip install requests
import os, time, requests

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

def submit(mode: str, **inp) -> str:
    """mode: text-to-video | image-to-video | keyframes-to-video"""
    body = {"model": f"flux-3-max/{mode}", "input": inp}
    res = requests.post(BASE, json=body, headers=H, timeout=30).json()
    if res.get("code") != 200:
        # sync 400s look like {"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}
        raise RuntimeError(res)
    return res["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900, every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

# 1) text-to-video
t2v = submit("text-to-video",
    prompt="A single white sneaker rotates slowly on a wet black plinth, studio softbox lighting, macro product shot",
    duration=5, resolution="720p", aspect_ratio="16:9", generate_audio=False)

# 2) image-to-video: first frame, optional last frame
i2v = submit("image-to-video",
    prompt="Morning mist drifts over the harbor; the boats rock gently and the camera slowly pushes forward.",
    image_url="https://example.com/harbor.jpg",
    # end_image_url="https://example.com/harbor-end.jpg",   # optional fixed ending
    duration=5, resolution="720p", generate_audio=False)

# 3) keyframes-to-video
FPS = 24
def keyframes_ok(duration: int, frames: list[dict]) -> None:
    idx = [f["frame_index"] for f in frames]
    assert 1 <= len(frames) <= 10, "1-10 keyframes"
    assert len(set(idx)) == len(idx), "frame_index must be unique"
    assert all(0 <= i <= duration * FPS for i in idx), f"frame_index must be 0..{duration * FPS}"

frames = [
    {"image_url": "https://example.com/harbor.jpg", "frame_index": 0},
    {"image_url": "https://example.com/latte.jpg",  "frame_index": 120},
]
keyframes_ok(5, frames)
kf = submit("keyframes-to-video",
    prompt="A continuous cinematic morph from the misty harbor into a close-up of an iced matcha latte.",
    keyframes=frames, duration=5, resolution="720p", generate_audio=False)

url = wait(kf)
open("clip.mp4", "wb").write(requests.get(url).content)

Ausgabe-URLs laufen ab; laden Sie die Datei daher sofort nach erfolgreichem Task herunter oder kopieren Sie sie, statt den Link zu speichern.

Keyframes: So funktioniert die Zeitachse

frame_index ist eine Position auf einer 24-fps-Uhr, die bei 0 beginnt, kein Prozentwert. Der maximal erlaubte Wert ist duration × 24: 120 bei 5 Sekunden, 240 bei 10 Sekunden, 480 bei 20 Sekunden. Die Indizes müssen eindeutig sein; Sie können 1 bis 10 Keyframes übergeben. Für einen sauberen Übergang von A nach B setzen Sie den ersten Anker auf 0 und den letzten auf duration × 24; ein früher gesetzter letzter Anker hält das Ende, ein späterer komprimiert die Veränderung. Halten Sie das Seitenverhältnis aller Keyframes konsistent; für eine nahtlose Schleife sollten erstes und letztes Bild wie derselbe Moment wirken.

Hinweise für den Produktivbetrieb

• Polling und Callback. Die Task-API akzeptiert callback.url und when: "final", sodass kein Polling nötig ist; ein Polling alle 10 Sekunden wie oben ist für Skripte und Batch-Jobs ebenfalls in Ordnung.
• Setzen Sie für Polling-Schleifen immer ein Timeout und persistieren Sie die taskId vor dem Polling, damit ein Programmabsturz keine bereits bezahlten Tasks verloren gehen lässt.
• Sofort herunterladen. Behandeln Sie output[0].url als kurzzeitig gültig.
• Kostenkontrolle. Abgerechnet wird nach Ausgabesekunden und Auflösung, daher kostet ein 20-Sekunden-1080p-Clip ein Vielfaches eines 5-Sekunden-720p-Tests. Prototypisieren Sie zuerst mit 5 Sekunden und 720p und erhöhen Sie beides erst, wenn der Prompt funktioniert. Aktuelle Tarife finden Sie auf der Preisseite.

Was ich getestet habe und was nicht

Diese Prüfungen wurden am 23. Oktober 2026 mit einem schreibgeschützten Testschlüssel gegen die Live-API durchgeführt. Dieser Artikel rendert keine vollständigen Clips, daher mache ich keine Aussagen zur Ausgabequalität; die Beispiel-Prompts stammen aus den mitgelieferten Beispielen der Modellseiten.

Synchronvalidierung (HTTP 400, nicht in die Warteschlange gestellt). Werte außerhalb des Bereichs werden bereits beim Einreichen abgelehnt, mit error_code: INVALID_REQUEST und einer lesbaren message:

Anfrage	Antwort-message
duration: 3	invalid input: duration: minimum: got 3, want 5
resolution: "4k"	value must be one of '720p', '1080p'
aspect_ratio: "5:4"	value must be one of 'auto', '21:9', '2:1', '16:9', '4:3', '1:1', '3:4', '9:16'
reasoning_level: "medium"	value must be one of 'low', 'high'
Bild-zu-Video verwendet image_urls statt image_url	image_url: missing required field "image_url"; ... additional properties 'image_urls' not allowed

Die letzte Zeile ist ein häufiger Fehler: Andere Bild-Eingabemodelle von hiapi verwenden ein Pluralfeld, aber FLUX 3 Max Bild-zu-Video akzeptiert nur ein einzelnes image_url. Unbekannte Felder werden abgelehnt, nicht ignoriert.

Fehler in der Keyframe-Zeitachse sind asynchron. Ich habe zwei 5-Sekunden-Keyframe-Anfragen mit fehlerhafter Zeitachse eingereicht: eine mit frame_index: 121 (über dem Limit von 120), die andere mit zwei Keyframes bei frame_index: 0. Beide wurden akzeptiert und lieferten HTTP 200 und eine taskId. Etwa 1–2 Sekunden nach der Erstellung lieferte das Polling den Endzustand:

{"code":200,"data":{"status":"fail","model":"flux-3-max/keyframes-to-video",
 "error":{"code":"INVALID_REQUEST","message":"Invalid request parameters for this model. Please check the request and try again."},
 "taskId":"tk-hiapi-..."},"message":"success"}

Daraus folgen zwei Punkte. Erstens bedeutet eine 200-Antwort beim Einreichen nicht, dass die Zeitachse gültig ist, prüfen Sie daher beim Polling status und error.code. Zweitens ist die Fehlermeldung sehr allgemein und nennt nicht, welcher Frame das Problem ist; deshalb lohnt es sich, die obige keyframes_ok-Prüfung vor dem Einreichen auszuführen. Laut Modellseite werden fehlgeschlagene Tasks nicht berechnet; die Abrechnungsdaten dieser beiden Tasks habe ich nicht geprüft.

Häufige Fragen

Welche Modell-ID sollte ich für Anfangs- und Endframe verwenden? Verwenden Sie flux-3-max/image-to-video und übergeben Sie image_url und end_image_url. Keyframes sind nur nötig, wenn Sie Anker zwischen Anfang und Ende setzen möchten.

Wird es teurer, wenn ich mehr Keyframes hinzufüge? Laut Modellseite nein: Abgerechnet wird nach Ausgabesekunden und Auflösung, die Anzahl der Anker beeinflusst den Preis nicht.

Worin unterscheidet sich das von flux-3? flux-3-max/* sind eigenständige Modell-IDs, nach Modus aufgeteilt (Text, Bild, Keyframes); das Basis-flux-3 ist eine einzige ID, die den Modus je nach Eingabe wechselt und zudem Entwurfsmodus und Fortsetzung unterstützt. Siehe FLUX.3 Video-API-Leitfaden. Ich habe die Ausgabequalität beider nicht verglichen; entscheiden Sie daher anhand der Funktionen und der Tarife auf der Preisseite.

Kann ich ein anderes Bild-zu-Video-Modell verwenden? Ja. Weitere Bild-zu-Video-Optionen finden Sie unter So verwenden Sie die Ray 3.2 Bild-zu-Video-API.