DEV Community

Cover image for Grok Text zu Video API nutzen: Vollständige Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Grok Text zu Video API nutzen: Vollständige Anleitung

Kurz gesagt

Die Grok Text-zu-Video API generiert Videos aus einer Textaufforderung. Sie rufen POST /v1/videos/generations auf, erhalten sofort eine request_id zurück und fragen dann GET /v1/videos/{request_id} ab, bis der Status "done" ist. Das Modell ist grok-imagine-video, die Preise beginnen bei 0,05 $ pro Sekunde bei 480p. Das xAI Python SDK übernimmt das Polling automatisch.

Teste Apidog jetzt

Einleitung

xAI generierte allein im Januar 2026 1,2 Milliarden Videos. Dies war der erste Monat nach der Einführung der Grok Text-zu-Video API am 28. Januar 2026. Das Modell belegte im selben Monat den ersten Platz in der Text-zu-Video-Bestenliste von Artificial Analysis. Diese Zahlen zeigen, dass die Infrastruktur im großen Maßstab erprobt ist.

In diesem Leitfaden lernst du Schritt für Schritt: Erste Anfrage stellen, Ergebnis abfragen, Parameter anpassen, bessere Prompts schreiben. Du erfährst außerdem, wie du Referenzbilder verwendest, bestehende Videos erweiterst oder bearbeitest und wann Text-zu-Video die richtige Wahl ist.

💡 Tipp: Die API ist asynchron. Das Frontend kann nicht warten, bis das Video fertig ist, um etwas zu rendern. Entwickle deine Video-UI mit einem Polling-Workflow – ohne jedes Mal Credits auszugeben. Mit Apidogs Smart Mock kannst du beide Endpunkte simulieren. So entwickelt das Team die UI parallel zum Backend.

Was ist die Grok Text-zu-Video API?

Die Grok Text-zu-Video API ist Teil der Mediengenerierungs-Suite von xAI unter https://api.x.ai. Du sendest einen Textprompt, das Modell grok-imagine-video generiert daraus einen neuen Videoclip. Kein Quellbild nötig.

Neben dem Text-zu-Video-Endpunkt gibt es einen synchronen Bildgenerator (POST /v1/images/generations, Modell grok-imagine-image, 0,02 $ pro Bild) sowie Endpunkte zum Erweitern und Bearbeiten von Videos.

Anders als beim Bild-zu-Video-Modus lieferst du beim Text-zu-Video nur Worte. Szene, Bewegung und Stil entstehen komplett durch die Beschreibung. Den Bild-zu-Video-Leitfaden findest du hier.

Wie die Text-zu-Video-Generierung funktioniert (das asynchrone Muster)

Die API setzt auf ein asynchrones Muster:

  1. POST-Anfrage mit Prompt senden.
  2. Sofortige Antwort mit request_id.
  3. Video wird im Hintergrund generiert.
  4. Wiederholt GET-Anfrage mit request_id senden.
  5. Sobald status auf "done" steht, enthält die Antwort die Video-URL.

Das Frontend muss den Ladezustand anzeigen, bis das Video bereit ist.

Voraussetzungen

Vor dem Start:

  • xAI-Konto: Anlegen unter console.x.ai. Abrechnung aktivieren.
  • API-Schlüssel: In der xAI-Konsole unter "API Keys" erstellen und sicher speichern. Als Bearer-Token im Header jeder Anfrage nutzen.

API-Key als Umgebungsvariable setzen:

export XAI_API_KEY="your_api_key_here"
Enter fullscreen mode Exit fullscreen mode

Optional: xAI Python SDK installieren:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Erste Text-zu-Video-Anfrage

Der Endpunkt: POST https://api.x.ai/v1/videos/generations

Pflichtfelder: model, prompt

Mit curl:

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
  }'
Enter fullscreen mode Exit fullscreen mode

Antwort:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

Mit Python (requests):

import requests
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

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

payload = {
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload
)

data = response.json()
request_id = data["request_id"]
print(f"Generation gestartet. Request ID: {request_id}")
Enter fullscreen mode Exit fullscreen mode

Videoergebnis abfragen

Mit der erhaltenen request_id wiederholt GET /v1/videos/{request_id} abfragen, bis status "done" ist.

Mögliche Statuswerte:

  • "processing": Wird noch generiert
  • "done": Abgeschlossen, Video-URL verfügbar
  • "failed": Fehler aufgetreten

Komplette Python-Polling-Schleife:

import requests
import time
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
    url = f"{BASE_URL}/v1/videos/{request_id}"
    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"Attempt {attempt + 1}: status={status}, progress={progress}%")
        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"Video generation failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Video nicht bereit nach {max_attempts} Versuchen")

def generate_video(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/videos/generations",
        headers={**headers, "Content-Type": "application/json"},
        json={"model": "grok-imagine-video", "prompt": prompt}
    )
    request_id = response.json()["request_id"]
    print(f"Request ID: {request_id}")
    result = poll_video(request_id)
    video_url = result["video"]["url"]
    print(f"Video bereit: {video_url}")
    return video_url

video_url = generate_video(
    "A timelapse of a city skyline at sunset transitioning to night, aerial view"
)
Enter fullscreen mode Exit fullscreen mode

Typische finale Antwort:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}
Enter fullscreen mode Exit fullscreen mode

xAI Python SDK verwenden

Das SDK übernimmt das Polling. Beispiel:

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

result = client.video.generate(
    model="grok-imagine-video",
    prompt="A golden retriever running through autumn leaves in slow motion",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {result.video.url}")
print(f"Dauer: {result.video.duration}s")
Enter fullscreen mode Exit fullscreen mode

Für maximale Kontrolle über Wiederholungen, Fortschritt und Intervall: Roh-Requests verwenden. Für produktiven Schnellstart: SDK.

Effektive Prompts für die Videogenerierung

  • Szenenbeschreibung: Motiv und Umgebung klar beschreiben. Beispiel: „Weiße Keramiktasse auf Holztisch neben regennassem Fenster“
  • Bewegung: Was bewegt sich wie? Beispiel: „Kamera umkreist langsam die Tasse, Dampf steigt auf“
  • Kamerastil: Begriffe wie „Nahaufnahme“, „Drohnenaufnahme“, „Handkamera“
  • Beleuchtung/Stimmung: „Goldene Stunde“, „Studio-Dreipunktbeleuchtung“, „neblig, melancholisch“
  • Stilreferenzen: „kinematisch“, „Anime“, „Stop-Motion“

Empfohlene Prompt-Struktur:

A lone astronaut floats past the International Space Station,
tether drifting behind them. The camera tracks slowly
alongside, showing Earth below. Cinematic, IMAX quality,
warm sunrise light reflecting off the visor.
Enter fullscreen mode Exit fullscreen mode

Auflösung, Dauer und Seitenverhältnis steuern

  • Dauer: 
  "duration": 10
Enter fullscreen mode Exit fullscreen mode

(1–15 Sekunden, Default: 6)

  • Auflösung: 
  "resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

"480p" (Default) oder "720p"

  • Seitenverhältnis: 
  "aspect_ratio": "9:16"
Enter fullscreen mode Exit fullscreen mode

| Verhältnis | Am besten für |
|------------|---------------------------|
| 16:9 | Desktop, YouTube, Präsentationen |
| 9:16 | TikTok, Instagram Reels, Mobil |
| 1:1 | Instagram Feed, Social Cards |
| 4:3 | Klassisches Video, Präsentationen|
| 3:4 | Hochformat-Apps |
| 3:2 | Standard-Fotoformat |
| 2:3 | Porträtfotografie |

Komplettes Beispiel:

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
Enter fullscreen mode Exit fullscreen mode

Referenzbilder zur Steuerung des Videostils

Bis zu 7 Bild-URLs im Parameter reference_images:

{
  "model": "grok-imagine-video",
  "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Wähle stilistisch konsistente Bilder für eine klare Führung. Unterschied zu Bild-zu-Video: Bei Referenzbildern bleibt die Szene prompt-gesteuert, Bilder steuern nur Look & Feel.

Generierte Videos erweitern und bearbeiten

  • Video erweitern:

    POST /v1/videos/extensions

    Übergebe die request_id des Originalvideos + neuen Prompt.

  • Video bearbeiten:

    POST /v1/videos/edits

    Passe Stil oder Inhalt per Textanweisung an.

Beide Endpunkte sind asynchron (request_id → polling mit GET /v1/videos/{request_id}).

Kosten aus der API-Antwort auslesen

Im Antwort-Objekt:

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

Umrechnung:

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Kosten: ${cost_in_usd:.4f}")
# Output: Kosten: $0.0500
Enter fullscreen mode Exit fullscreen mode

Referenztabelle:

Auflösung Preis pro Sekunde 10-Sekunden-Clip
480p 0,05 $ 0,50 $
720p 0,07 $ 0,70 $

Verfolge cost_in_usd_ticks zur Kostenkontrolle ohne separate Abrechnungs-API.

So testest du die Grok Video-API mit Apidog

Das asynchrone Muster verlangt, dass du Lade-, Erfolgs- und Fehlerzustände im Frontend testest – ohne echte Credits zu verbrauchen. Mit Apidogs Smart Mock simulierst du beide Endpunkte.

Use Case 1: Smart Mock für Frontend-Entwicklung

  • Generierungs-Endpunkt simulieren: In Apidog POST /v1/videos/generations anlegen, Antwortschema mit request_id definieren. Smart Mock erzeugt automatisch eine passende UUID.

Beispielantwort:

  {
    "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
  }
Enter fullscreen mode Exit fullscreen mode
  • Abfrage-Endpunkt simulieren: GET /v1/videos/{request_id} mit vollständigem Schema (Status, Video-URL etc.) anlegen. Mock-Antwort für "status": "done" festlegen.

Beispielantwort:

  {
    "status": "done",
    "video": {
      "url": "https://vidgen.x.ai/mock-video-12345.mp4",
      "duration": 8,
      "respect_moderation": true
    },
    "progress": 100,
    "usage": {
      "cost_in_usd_ticks": 400000000
    }
  }
Enter fullscreen mode Exit fullscreen mode

Frontendentwickler können die UI gegen diese Mock-Server testen – inkl. Lade-, Erfolgs- und Fehlerzustand (z.B. "status": "failed" mocken). Keine echten API-Credits nötig.

Use Case 2: Testszenarien für die Abfrageschleife

  • 1. Schritt:

    POST /v1/videos/generations als ersten Testschritt. request_id mit JSONPath $.request_id als Variable extrahieren.

  • 2. Schritt:

    GET /v1/videos/{{videoRequestId}} als zweiten Testschritt, in einer For-Schleife mit Abbruchbedingung response.body.status == "done". Wartezeit (z.B. 5s) zwischen den Polls einbauen.

  • 3. Schritt:

    Nach Schleifenende Assertion, dass $.video.url nicht leer ist.

Dieses Testszenario lässt sich automatisiert in CI laufen – für stabile Integrationen.

Text-zu-Video vs. Bild-zu-Video: Wann welchen Modus?

Beide nutzen das Modell grok-imagine-video, aber die Anwendung unterscheidet sich:

Text-zu-Video, wenn:

  • Originelle Inhalte aus Konzept/Skript generiert werden sollen
  • Das Modell volle kreative Kontrolle haben soll
  • User Prompts eingeben
  • Kein Quellbild vorhanden ist

Bild-zu-Video, wenn:

  • Produktfotos, Illustrationen, Assets animieren
  • Konkrete Bilddetails erhalten bleiben sollen
  • Konsistente Animationen aus Bilderserien gebraucht werden
  • Eigene Kunstwerke/Fotos animiert werden sollen

Text-zu-Video = Szene aus Prompt.

Bild-zu-Video = Bild wird animiert.

Vollständigen Bild-zu-Video-Leitfaden siehe hier.

Häufige Fehler und Lösungen

  • 401 Unauthorized: API-Schlüssel fehlt, abgelaufen oder falsch. Authorization-Header prüfen: Bearer YOUR_XAI_API_KEY (ohne Leerzeichen am Ende), Schlüssel in der Konsole aktiv?
  • 429 Too Many Requests: Ratenlimit erreicht (60/min, 1/sec). Abfrageintervall erhöhen, mindestens 5s zwischen Polls.
  • status: "failed": Prompt von Inhaltsmoderation abgelehnt. Siehe Feld respect_moderation. Prompt präzisieren, keine sensiblen Begriffe.
  • Video-URL 404: URLs sind temporär, Video direkt nach Erhalt herunterladen und selbst speichern.
  • Leeres/eingefrorenes Video: Zu vage oder ohne Bewegungshinweise. Prompt um klare Bewegungsanweisungen ergänzen.
  • Lange Wartezeiten: 720p und lange Clips dauern länger. Für Entwicklung 480p und kurze Clips nutzen.

Fazit

Die Grok Text-zu-Video API bietet einen klaren Weg von Prompt zu Video: Anfrage, request_id, Polling, MP4-Download. Das asynchrone Abfragemuster ist der Kern. Wenn die Polling-Logik steht, kannst du Dauer, Auflösung, Seitenverhältnis und Referenzbilder gezielt optimieren.

Für Produktionsbuilds: Kostenverfolgung via cost_in_usd_ticks jeder Antwort. Simuliere die Endpunkte mit Apidog, damit das Frontend unabhängig vom Backend entwickelt werden kann. Automatisiere Testszenarien für stabile Integrationen.

FAQ

Welchen Modellnamen verwende ich für die Text-zu-Video-Generierung?

grok-imagine-video ist das erforderliche model-Feld für POST /v1/videos/generations.

Wie lange dauert die Videogenerierung?

Je nach Dauer/Auflösung. Kurze 480p-Clips: <30s, lange 720p-Clips: mehrere Minuten. Poll alle 5–10 Sekunden.

Kann ich Videos länger als 15 Sekunden generieren?

Nicht in einer Anfrage. Maximal duration: 15. Für längere Videos: Clip generieren, dann mit POST /v1/videos/extensions erweitern.

Wie lade ich das Video herunter?

Nutze die URL aus result.video.url der fertigen Antwort. MP4 direkt downloaden, URL ist temporär.

Was passiert, wenn der Prompt moderiert wird?

Status bleibt failed, Feld respect_moderation zeigt Moderation an. Prompt anpassen und erneut versuchen.

Gibt es eine kostenlose Stufe?

xAI berechnet pro generierter Sekunde. Keine Gratisstufe für Videos. Ggf. aktuelle Aktionen in console.x.ai prüfen.

Unterschied zwischen reference_images und Quellbild?

reference_images steuern Stil bei Text-zu-Video. Sie beeinflussen die Optik, werden aber kein direktes Motiv. Beim Bild-zu-Video wird das Bild der Startframe.

Wie teste ich Polling ohne Credits?

Mit Apidogs Smart Mock beide Endpunkte simulieren. Schemata definieren, Mock-Antworten für "processing" und "done" anlegen – dein Polling-Code funktioniert dann ohne echte API.

Top comments (0)