So verwendest du die grok-imagine-1.5-lite Text-zu-Video-API (curl + Python)

Wenn du aus einem Satz ein kurzes Video mit Ton erzeugen möchtest, ist grok-imagine-1.5-lite/text-to-video die günstigste Option auf hiapi, die 1080P erreicht. Es nimmt einen Prompt entgegen und liefert eine 1–15 Sekunden lange MP4-Datei zurück, in die der Ton bereits eingemischt ist, und läuft auf derselben einheitlichen Task-API wie alle anderen Modelle der Plattform. Diese Seite zeigt dir Anfragen, die du direkt einfügen und ausführen kannst, das exakte Schema (gegen den Live-Endpunkt verifiziert, nicht aus der Spezifikation abgeschrieben), wie eine echte Antwort aussieht und die Fallstricke, in die ich beim Testen getreten bin.

Alles Folgende wurde am 2026-10-21 gegen die Live-API geprüft. Die Preise stammen aus meinen eigenen Messungen; falls sie sich ändern, gilt die Preisseite.

1. Was du baust und was du vorbereiten musst

Ziel: einen Text-Prompt senden und einen herunterladbaren MP4-Clip mit Audio zurückbekommen.

Du brauchst nur eine Sache: einen hiapi-API-Key. Erstelle einen in der Konsole und bewahre ihn serverseitig auf – er hat die Form sk-... und gehört in den Header Authorization: Bearer. Es gibt keinen Weg ohne Key; jede Anfrage unten muss authentifiziert sein.

Das Modell ist asynchron. Du bekommst das Video nicht direkt in der POST-Antwort. Du legst zuerst einen Task an, erhältst eine taskId und pollst dann (oder verwendest einen Callback), bis der Task abgeschlossen ist und eine Ausgabe-URL liefert.

2. Minimal lauffähiges Beispiel

Zwei Schritte: Task anlegen, dann das Ergebnis pollen.

Task anlegen (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "Im Morgengrauen läuft ein Rotfuchs über frisch gefallenen Schnee, sein Atem wird zu weißem Nebel, sanftes Morgenlicht, leises Umgebungsrauschen des Windes. Filmisch, natürliche Farben. Kein Text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Achte auf die Struktur: model steht auf oberster Ebene, alles andere ist unter input verschachtelt. Wenn du Felder flach sendest (ohne input-Wrapper), lehnt die API den gesamten Request-Body mit invalid input: must be a JSON object ab – das ist der häufigste Fehler.

Bei erfolgreichem Anlegen wird sofort eine Task-ID zurückgegeben:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB" }, "message": "success" }

Ergebnis pollen (Python)

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("Im Morgengrauen läuft ein Rotfuchs über frisch gefallenen Schnee, leises Umgebungsrauschen des Windes. Filmisch."))

Schema (live verifiziert)

Die Felder gehören in input. Das Schema ist geschlossen – jeder Key, den es nicht kennt, liefert 400, also sende kein seed, negative_prompt oder motion_mode (die gibt es hier nicht; alle Kamerafahrten und Bewegungsrichtungen werden über die Prompt-Formulierung ausgedrückt).

Feld	Typ	Erforderlich	Zulässige Werte
prompt	string	ja	Freitext
duration	integer	ja	1–15 (ganze Sekunden; 5.5 wird abgelehnt)
resolution	string	—	480p, 720p, 1080p
aspect_ratio	string	—	16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16

Dieses Modell hat kein auto-Seitenverhältnis (sein Bild-zu-Video-Pendant hat eines; dieser Text-zu-Video-Endpunkt nicht). Gib das Verhältnis explizit an, sonst bekommst du das Standardverhältnis des Modells.

Hier ist eine echte Antwort eines abgeschlossenen Tasks:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

Hier ist ein von diesem Modell generierter Clip (Referenzausgabe von hiapi für grok-imagine-1.5-lite/text-to-video, erzeugt aus dem Beispiel-Prompt seiner Dokumentation – „Bei Sonnenaufgang schwebt ein Heißluftballon aus Glas über Reisterrassen"):

3. In die Produktion überführen

Verwende Callbacks statt Polling. Polling ist für Skripte in Ordnung; für Server fügst du callback hinzu, damit du nicht ständig eine Anfrage offen halten musst. Wenn ein Task einen Endzustand erreicht, sendet die Plattform die Task-Details per POST an deine URL:

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

Bei diesem Task-Typ akzeptiert when nur "final". Dedupliziere in deinem Handler anhand der taskId – Callbacks können wiederholt werden, also gestalte den Handler idempotent.

Ausgabe-URLs laufen ab. Beachte storage: "temp" und den expireAt-Unix-Zeitstempel – temporäre Ausgaben liegen etwa 7 Tage auf temp.hiapi.ai und liefern danach 404. Speichere keine Hotlinks. Lade die Bytes in dem Moment herunter, in dem der Task erfolgreich ist, oder rufe den Storage-Promote-Endpunkt auf, um das Artefakt vor Ablauf der TTL in permanenten Speicher zu verschieben.

Die Kosten richten sich nach den Ausgabesekunden. Die Abrechnung hängt nur von duration und der angeforderten Auflösung ab. Beim Testen: 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. Ein 5-Sekunden-Clip in 720P kostet also etwa $0.215, ein 5-Sekunden-Clip in 1080P etwa $1.00, ein 1-Sekunden-Clip in 480P etwa $0.029. Der 1080P-Tarif ist etwa 5-mal so hoch wie 720P – verwende ihn nur, wenn du diese Auflösung wirklich brauchst. Die aktuellen Zahlen findest du auf der Preisseite.

Fehlerbehandlung. Abgelehnte Anfragen kommen als HTTP 400 mit einer präzisen Meldung zurück, die du protokollieren und anhand derer du reagieren kannst. Die Validierung erfolgt, bevor ein Task angelegt wird, ein 400 hier verursacht also keine Kosten. Echte Antworten, die ich tatsächlich ausgelöst habe:

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

Wenn ein Task akzeptiert, aber später fehlschlägt, erscheint das als data.status: "fail" mit einem data.error-Objekt am Detail-Endpunkt – nicht als HTTP-Fehler –, also prüfe status und verlasse dich nicht auf den HTTP-Statuscode des Pollings.

4. Was ich tatsächlich beobachtet habe

Ich habe eine echte Generierung durchgeführt, um den End-to-End-Ablauf zu bestätigen (nicht nur das Schema): duration: 1, resolution: "480p", aspect_ratio: "16:9".

• Es funktioniert tatsächlich und wird abgerechnet – der POST gab eine taskId zurück, und der Task wurde mit einer echten Ausgabe-URL abgeschlossen. Das serverseitige Rendern eines 1-Sekunden-Clips dauerte tatsächlich etwa 51 Sekunden; selbst winzige Clips sind nicht sofort fertig, also setze die Polling-Deadline großzügig (ich habe 300 Sekunden gesetzt).
• Tasks durchlaufen Zwischenzustände. Das Feld status durchläuft nacheinander handling → archiving → success. Nur success und fail sind Endzustände; behandle archiving nicht als abgeschlossen.
• 480P wird bei 16:9 als 848×480 H.264 gerendert. ffprobe auf die heruntergeladene Datei angewendet: ein H.264-Videostream (848×480) plus ein eingebetteter MJPEG-Thumbnail-Stream. Die 495-KB-Datei ist eine gültige MP4.
• Audio ist immer eingebaut. Selbst wenn mein Prompt nur „leises Umgebungsrauschen des Windes" erwähnte, enthielt die Ausgabe eine AAC-Spur – das Modell synthetisiert passendes Audio und mischt es in dieselbe MP4. Es gibt keine separate Audio-URL und keinen Schalter, um es zu deaktivieren; wenn du einen stummen Clip brauchst, entferne die Tonspur selbst (ffmpeg -an).

Hinweis zum Umfang: Ich habe den API-Vertrag, die oben genannten drei Fehlertypen und eine 480P-Renderung verifiziert. Ich habe die Ausgabequalität von 720P/1080P oder lange (15 Sekunden) Dauern nicht benchmarkiert, daher mache ich dazu keine Qualitätsaussagen – ich sage nur, dass das Schema sie akzeptiert und pro Sekunde abgerechnet wird.

5. Lite im Vergleich zur standardmäßigen Grok Imagine Video API

Wähle den richtigen Endpunkt, bevor du baust:

• grok-imagine-1.5-lite/text-to-video (diese Seite): 480P/720P/1080P, 1–15 Sekunden (du kannst also 1- oder 2-Sekunden-Clips erzeugen), Preis $0.029–$0.20/s. Es ist der einzige von hiapi gehostete Text-zu-Video-Endpunkt der 1.5-Generation und die einzige Grok-t2v-Stufe, die 1080P erreicht.
• grok-imagine/text-to-video (die ältere Standardstufe, siehe diesen Leitfaden): günstiger pro Sekunde ($0.0114–$0.0214/s) und bietet Motion Modes, erreicht aber nur 720p und erfordert 6–30 Sekunden Dauer – es kann keine Clips unter 6 Sekunden erzeugen.

„Lite" ist hier also nicht die günstigste Option pro Sekunde; es ist die Stufe, die 1080P und extrem kurze Clips freischaltet. Wenn du statt Text ein einzelnes statisches Bild einspeisen möchtest, verwende den Endpunkt grok-imagine-1.5-lite/image-to-video derselben Stufe (gleiche Preisgestaltung, Eingabe über image_urls).

6. Relevante Links

• grok-imagine-1.5-lite Text-zu-Video-Modellseite / Playground
• Task anlegen – API-Referenz
• Task-Details abrufen – API-Referenz
• Preise

Häufig gestellte Fragen

Muss ich pollen, oder gibt es einen Callback? Beides geht. Skripte pollen mit GET /v1/tasks/{taskId}; Server hängen callback.url an und setzen when auf "final". Dedupliziere anhand der taskId.

Warum liefert meine Anfrage 400 mit „must be a JSON object"? Deine Felder sind nicht in input verpackt. Der Request-Body muss {"model": "...", "input": { ... }} sein.

Kann ich Audio deaktivieren? Nicht bei der Anfrage – jede Ausgabe enthält eine eingemischte AAC-Tonspur. Wenn du Stille brauchst, entferne sie nachgelagert mit ffmpeg -an.

Wie lange ist eine Ausgabe-URL gültig? Es ist eine temporäre URL mit expireAt (etwa 7 Tage). Lade sie sofort herunter oder verschiebe sie in permanenten Speicher; verlinke sie nicht per Hotlink.

Was ist die günstigste gültige Anfrage? 1 Sekunde bei 480P kostet etwa $0.029. Das ist eine gute Kanarienvogel-Anfrage, bevor du Massenverarbeitung startest, um zu prüfen, ob dein Key Guthaben hat.