So verwendest du die Grok Imagine API für Text-zu-Video: curl, Python und eine ausführbare Anfrage

Grok Imagine ist das Videogenerierungsmodell von xAI. HiAPI stellt seine Text-zu-Video-Variante über denselben einheitlichen asynchronen Endpunkt wie alle anderen Generierungsmodelle bereit: POST /v1/tasks. Du sendest einen Prompt (plus optional Dauer, Modus, Seitenverhältnis und Auflösung), erhältst sofort eine taskId und bekommst nach Abschluss der Aufgabe eine .mp4-URL.

Dieser Leitfaden ist der kürzeste Weg zu einer ausführbaren Anfrage: das exakte Eingabeschema (gegen die Live-API verifiziert, einschließlich des 400-Fehlers, den du bekommst, wenn du einen Feldnamen falsch errätst), ein kopierfertiger curl-Ablauf, ein kleiner Python-Client mit Polling und das Callback-Muster, das du in der Produktion verwenden würdest.

Was du baust und was du brauchst

Ziel: Text-Prompts in Videoclips von 6–30 Sekunden verwandeln – vollständig über HTTP, mit grok-imagine/text-to-video.

Du brauchst nur eines: einen HiAPI-API-Schlüssel. Erstelle einen im HiAPI-Dashboard – ein einziger Schlüssel gilt für alle Modelle, wenn du also bereits Bildmodelle über HiAPI aufrufst, funktioniert derselbe Schlüssel auch hier. Anfragen werden mit dem Standard-Bearer-Header authentifiziert:

Authorization: Bearer sk-<your-key>

Eingabeschema (bevor du Code schreibst)

Die Task-API validiert input streng pro Modell – unbekannte Felder werden mit 400 abgelehnt, nicht stillschweigend ignoriert. Hier ist das vollständige Schema für grok-imagine/text-to-video:

Feld	Typ	Erforderlich	Werte	Standard
prompt	string	Ja	max. 5000 Zeichen, Englisch funktioniert am besten	—
duration	integer	Nein	6–30 (Sekunden)	6
mode	enum	Nein	fun, normal	normal
aspect_ratio	enum	Nein	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	Nein	480p, 720p	480p

Drei Dinge solltest du vorab wissen:

• mode ist der „Bewegungsmodus“-Schalter. normal ist ausgewogen; fun erzeugt kreativere, übertriebenere Bewegungen. Wenn du Grok Imagines Modi anderswo unter anderen Namen beschrieben siehst, der API-Parameter ist mode – etwas wie motion_mode zu senden, beschert dir 400 additional properties 'motion_mode' not allowed.
• duration wirkt linear auf die Kosten. Grok Imagine wird pro Ausgabesekunde abgerechnet, ein 30-Sekunden-Clip kostet also fünfmal so viel wie ein 6-Sekunden-Clip. Die aktuellen Sekundensätze findest du auf der HiAPI-Preisseite.
• Das Standard-Seitenverhältnis ist 2:3 (Hochformat). Wenn du Breitbild willst, gib explizit 16:9 an – das überrascht Nutzer, die von Modellen mit standardmäßig horizontalem Format kommen.

Werte außerhalb des Bereichs schlagen schnell mit einer beschreibenden Meldung fehl, z. B. liefert duration: 31:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Minimales ausführbares Beispiel: curl

Zwei Aufrufe: Aufgabe erstellen, dann pollen.

1. Aufgabe erstellen:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Beachte, dass die Modell-ID der reine String grok-imagine/text-to-video ist – kein Anbieter-Präfix und kein Versions-Suffix.

2. Pollen bis zum Endzustand:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

Die .mp4-URL ist temporär – expireAt ist ein Unix-Zeitstempel, etwa eine Woche in der Zukunft. Lade die Bytes sofort nach erfolgreichem Task herunter und speichere sie selbst; verlinke temp.hiapi.ai-URLs nicht von benutzernahen Stellen aus direkt. (Wenn dir schon einmal Ausgabelinks abgelaufen sind, liegt hier die Ursache – siehe hiapi Ausgabe-URL abgelaufen: vor Ablauf herunterladen.)

Python: ein kleiner Polling-Client

Ein wiederverwendbares Skript für denselben Ablauf – Erstellen, Pollen mit Deadline, Herunterladen:

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

6-Sekunden-Clips sind in der Regel weit vor der obigen 15-Minuten-Deadline fertig; längere Dauern brauchen proportional länger, also behalte dieses großzügige Timeout für 30-Sekunden-Tasks bei.

Hinweise für die Produktion

Callback statt Polling. Für alles außerhalb von Skripten übergib beim Erstellen ein Top-Level-callback-Objekt, und HiAPI POSTet den Endzustand der Aufgabe an deinen Endpunkt – keine Polling-Schleife nötig:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when akzeptiert nur "final" (du erhältst einen POST, wenn die Aufgabe success oder fail erreicht, nicht inkrementellen Fortschritt). Faustregel: Polling eignet sich für CLIs, Batch-Jobs und alles Kurzlebige; Callbacks eignen sich für Web-Backends, sonst blockieren mehrminütige Renderings deine Worker-Kapazität. Wenn dein Callback-Endpunkt scheinbar nichts empfängt, schau dir warum dein hiapi-Task-Callback nicht ausgelöst wird an.

Idempotenz. Das Erstellen von Aufgaben ist nicht idempotent – ein wiederholter Create-Request nach Timeout kann zwei abgerechnete Aufgaben erzeugen. Sobald du die taskId hast, protokolliere sie, und prüfe bei unklaren Fehlern (Netzwerk-Timeout beim Erstellen) vor dem erneuten Senden deine Aufgabenhistorie. Da duration pro Sekunde abgerechnet wird, sind doppelte 30-Sekunden-Aufgaben die teure Art der Duplizierung.

Fehlerbehandlung. Die zwei Fehlerklassen, die dir tatsächlich begegnen werden:

• Schema-400-Fehler (error_code: "INVALID_REQUEST") – falscher Feldname, Dauer außerhalb des Bereichs, ungültiger Enum-Wert. Diese sind deterministisch; korrigiere die Anfrage, wiederhole sie nicht.
• Authentifizierungsfehler – ein ungültiger Schlüssel oder ein Schlüssel ohne Zugriff auf dieses Modell liefert 401 mit "code": "permission_denied" und der Meldung "This API key cannot use the selected model." Prüfe den Schlüssel im Dashboard und vergewissere dich, dass das Modell für ihn freigegeben ist.
• Fehler auf Aufgabenebene – die Erstellung gelingt, aber die Aufgabe endet später mit status: "fail" und einem error-Objekt (Inhaltsrichtlinie, Upstream-Kapazität). Diese lohnen einen Wiederholungsversuch mit Backoff. Wenn eine Aufgabe in handling festzuhängen scheint, siehe Diagnose hängender oder abgelaufener /v1/tasks-Jobs.

Nächste Schritte

• Grok Imagine Text-zu-Video-Modellseite – Playground und aktuelle Preise
• Modell-Eingabereferenz – das normative Schema für dieses Modell
• Aufgabe erstellen und Aufgabendetails abrufen – der vollständige asynchrone API-Umschlag
• Schnellstart – führe deinen ersten HiAPI-Aufruf von Anfang bis Ende aus, und Authentifizierung für den Umgang mit Schlüsseln

Häufige Fragen

Was ist die Grok Imagine API und wie greife ich darauf zu? Grok Imagine ist das Videogenerierungsmodell von xAI. Über HiAPI rufst du es mit einem einzigen HiAPI-Schlüssel am einheitlichen POST /v1/tasks-Endpunkt als grok-imagine/text-to-video auf – kein separates xAI-Konto oder SDK erforderlich.

Wie lang können Grok Imagine-Videos sein? duration akzeptiert ganze Zahlen von 6 bis 30 Sekunden (Standard 6). Werte außerhalb dieses Bereichs werden beim Erstellen mit 400 abgelehnt, die Abrechnung erfolgt pro Ausgabesekunde.

Was ist der Unterschied zwischen fun- und normal-Modus? normal (Standard) liefert ausgewogene, realistische Bewegung; fun neigt zu mehr Kreativität und Übertreibung. Dies ist der einzige Bewegungsstil-Schalter, den die API bietet – pro Anfrage gewählt, nicht pro Konto.

Unterstützt grok-imagine/text-to-video 1080p? Derzeit nicht – resolution akzeptiert 480p (Standard) oder 720p. Wenn du eine höhere Ausgabeauflösung brauchst, skaliere nachgelagert hoch oder vergleiche andere Videomodelle auf der Modellseite.

Kann ich mit Grok Imagine vorhandene Bilder animieren? Mit diesem Modell nicht – es unterstützt nur Text. Am selben Task-Endpunkt gibt es ein separates grok-imagine/image-to-video-Modell, das Bildeingaben akzeptiert; der asynchrone Lebenszyklus (Erstellen → Polling/Callback → Herunterladen) ist identisch.

Gibt es eine kostenlose Stufe für die Grok Imagine API? Die Generierung wird pro Videosekunde von deinem HiAPI-Guthaben abgebucht – es gibt keinen schlüssellosen kostenlosen Endpunkt. Aktuelle Tarife findest du auf der Preisseite; was „kostenlos“ in diesem Bereich realistisch bedeutet, deckt dieser Vergleich kostenloser Text-zu-Video-APIs ab.