Grok Image zu Video API nutzen: Schritt-für-Schritt Anleitung

TL;DR

Die Grok Bild-zu-Video API nutzt das Modell grok-imagine-video, um ein statisches Bild in einen animierten Videoclip zu verwandeln. Sende per POST deine Bild-URL, einen Prompt und optionale Einstellungen an https://api.x.ai/v1/videos/generations. Die API gibt sofort eine request_id zurück. Anschließend mit GET /v1/videos/{request_id} abfragen, bis status auf "done" steht. Die Dauer liegt zwischen 1 und 15 Sekunden. Preise starten ab 0,05 $ pro Sekunde für 480p-Ausgabe.

Probiere Apidog jetzt aus

Einführung

Am 28. Januar 2026 veröffentlichte xAI das Modell grok-imagine-video für den öffentlichen API-Zugang. Im ersten Monat generierte das Modell 1,2 Milliarden Videos und führte das Artificial Analysis Text-zu-Video-Leaderboard an. Die Bild-zu-Video-Funktion erlaubt es, ein Foto und einen Prompt zu senden, woraufhin die API das Bild in einen animierten Videoclip (MP4) verwandelt.

Für die Integration ist wichtig: Die API arbeitet asynchron. Ein erfolgreicher POST mit Status 200 reicht nicht – die Integration ist erst abgeschlossen, wenn deine Abfrageschleife die Zustände "processing", "done" und "failed" korrekt verarbeitet.

Mit Apidog kannst du Test-Szenarien für diese asynchronen Workflows direkt umsetzen: Sende POST an /v1/videos/generations, extrahiere die request_id, wiederhole GET bis status == "done", und prüfe, ob die Video-URL vorhanden ist.

Was ist die Grok Bild-zu-Video API?

Die Grok Bild-zu-Video API ist Teil des Videoerstellungsprodukts von xAI. Sie basiert auf dem Modell grok-imagine-video und akzeptiert ein Bild als Startrahmen des Ausgabevideos. Das Modell analysiert Bildinhalt und Prompt und erzeugt natürliche Bewegung, um die Szene zu animieren.

API-Endpunkt:

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

Authentifizierung:

Authorization: Bearer YOUR_XAI_API_KEY

Den Schlüssel erhältst du in der xAI-Konsole. Die API unterstützt auch Text-zu-Video (ohne image), Videoerweiterungen und Bearbeitungen.

Wie der Bild-zu-Video-Prozess funktioniert

Der Parameter image im Request bezeichnet den ersten Frame des Videos. Das Modell ersetzt das Bild nicht, sondern startet damit. Jeder Pixel des ersten Frames stammt aus deinem Quellbild. Das Modell prognostiziert, wie sich die Szene gemäß Prompt entwickeln würde.

Beispiel:

Bild: Bergsee bei Sonnenaufgang.

Prompt: "Sanfte Wellen breiten sich über das Wasser aus, während morgendlicher Nebel aufzieht."

Der erste Frame ist dein Foto. Die Folgebilder zeigen animiertes Wasser und Nebel.

Wann Bild-zu-Video verwenden?

• Du hast ein bestehendes Foto, das animiert werden soll.
• Markenidentität fordert einen festen Startframe.
• Bewegung soll an eine reale Szene gebunden sein.

Wann Text-zu-Video verwenden?

• Keine Referenzbilder vorhanden.
• Komplette Szenengenerierung dem Modell überlassen.
• Schnelle Iteration wichtiger als Frame-Präzision.

Voraussetzungen

Vor dem ersten API-Aufruf benötigst du:

1. xAI-Konto: console.x.ai
2. API-Key aus der xAI-Konsole (als Umgebungsvariable speichern)
3. Python 3.8+ oder Node.js 18+ (Beispiele für beide)
4. Öffentlich erreichbare Bild-URL oder base64-kodiertes Bild (Data-URI)

API-Key setzen:

export XAI_API_KEY="your_key_here"

xAI Python SDK installieren (optional):

pip install xai-sdk

Für reine HTTP-Aufrufe reichen requests (Python) oder fetch (Node.js).

Erste Bild-zu-Video-Anfrage

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": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Antwort:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

Das Video wird jetzt asynchron generiert – abfragen nicht vergessen!

Mit Python (raw requests)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

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

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")

Base64-Bild verwenden

Wenn das Bild lokal ist, als Data-URI kodieren:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

Abfragen des Ergebnisses

Die Videoerstellung ist asynchron. Status abfragen mit:

GET https://api.x.ai/v1/videos/{request_id}

Statuswerte:

Status	Bedeutung
"processing"	Video wird noch gerendert
"done"	Video fertig, URL in der Antwort
"failed"	Fehler aufgetreten

Abgeschlossene Antwort:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

Komplette Python-Abfrageschleife

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# Verwendung
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

Tipp: Polling-Intervall auf 5 Sekunden oder länger setzen (Ratenlimit: 60 Anfragen/Minute).

xAI Python SDK verwenden

Mit xai-sdk übernimmt das SDK das asynchrone Polling automatisch:

from xai_sdk import Client
import os

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

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")

Das SDK kümmert sich um Polling, Statusprüfungen und Fehler. Für detailliertere Kontrolle empfiehlt sich der Raw-Requests-Ansatz.

Auflösung, Dauer und Seitenverhältnis steuern

Dauer:

duration akzeptiert Werte von 1 bis 15 Sekunden (Standard: 6).

"duration": 10

Längere Videos erhöhen die Kosten linear.

Auflösung:

Wert	Beschreibung
"480p"	Standard. Günstiger, schneller
"720p"	Höhere Qualität, teurer

"resolution": "720p"

Seitenverhältnis (aspect_ratio):

Wert	Anwendungsfall
"16:9"	Standard, Landschaft
"9:16"	Vertikal, Social Stories
"1:1"	Quadrat, Instagram
"4:3"	Klassisch, Präsentation
"3:4"	Portrait
"3:2"	Foto-Zuschnitt
"2:3"	Hochformat Portrait

Standardmäßig wird das Seitenverhältnis an das Quellbild angepasst. Zum Überschreiben explizit angeben.

---

Referenzbilder zur Stilführung nutzen

Der Parameter reference_images ergänzt das Hauptbild:

• image: Startframe, wird animiert.
• reference_images: Bis zu 7 Bilder zur Stil-/Inhaltsführung. Diese beeinflussen Look und Bewegung, erscheinen aber nicht direkt im Video.

Beispiel:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

Auch ohne image kannst du Referenzbilder für Text-zu-Video nutzen.

Videos erweitern und bearbeiten

Video erweitern:

Nutze POST /v1/videos/extensions, um einen Clip zu verlängern (je Aufruf max. 15 Sekunden):

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

Ergebnis wie gewohnt mit GET /v1/videos/{request_id} abfragen.

Video bearbeiten:

Mit POST /v1/videos/edits gezielt Aspekte ändern:

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

Auch hier: asynchrones Abfragemuster nutzen.

Preisübersicht: Kosten eines 10-Sekunden-Videos

xAI berechnet:

• Eingabebild: 0,002 $ pro Bild
• Ausgabe 480p: 0,05 $/Sekunde
• Ausgabe 720p: 0,07 $/Sekunde

Beispiel: 10 Sek. bei 720p

• Eingabebild: 0,002 $
• Ausgabe: 10 × 0,07 $ = 0,70 $
• Gesamt: 0,702 $

Beispiel: 6 Sek. bei 480p

• Eingabebild: 0,002 $
• Ausgabe: 6 × 0,05 $ = 0,30 $
• Gesamt: 0,302 $

Die Bildgebühr fällt immer an, auch bei wiederverwendeter URL. Text-zu-Video (ohne image) entfällt die Bildgebühr.

Grok Video API Integration mit Apidog testen

Asynchrone Workflows können mit Apidog automatisiert getestet werden:

1. Neues Test-Szenario:
   
   Im Apidog "Tests"-Modul auf + klicken, z.B. "Grok Bild-zu-Video asynchroner Workflow".

2. Generierungsanfrage:
   
   POST-Anforderung wie oben beschrieben anlegen.

3. request_id extrahieren:
   
   Variablenextraktion (JSONPath $.request_id) auf die Antwort.

4. Abfrageschleife:
   
   For-Schleifenprozessor mit GET auf /v1/videos/{{video_request_id}}, Status extrahieren, nach jedem GET 5000 ms warten.
   
   Schleife beenden, wenn {{video_status}} == "done".

5. Video-URL bestätigen:
   
   Nach der Schleife GET auf das Ergebnis, Assertion: $.video.url ist nicht leer.

Szenario ausführen:

Auf "Ausführen" klicken. Apidog führt alle Schritte durch und zeigt die Ergebnisse an.

CI/CD-Integration:

apidog run --scenario grok-video-async-flow --env production

Weitere Details zum Testen asynchroner APIs mit Apidog findest du im Leitfaden auf apidog.com.

Häufige Fehler und Behebungen

• 401 Unauthorized:
  
  API-Key prüfen, Syntax des Headers beachten, Key in Konsole aktivieren.

• 422 Unprocessable Entity:
  
  Felder wie model, prompt oder image.url prüfen. Bild-URL vorher testen.

• Bild-URL nicht zugänglich:
  
  Nur öffentliche URLs oder Data-URIs verwenden.

• Status bleibt auf "processing":
  
  Warten (bis zu mehrere Minuten möglich). Nach 10 Minuten ggf. neuen Job starten.

• Ratenlimit (429):
  
  Max. 60 Anfragen/Minute beachten. Polling mit Delay ausstatten.

• Base64-Upload abgelehnt:
  
  Korrektes MIME-Präfix verwenden, z.B. data:image/jpeg;base64,.

• Seitenverhältnis-Fehler:
  
  Seitenverhältnis an das Quellbild anpassen, um Zuschnitt/Letterboxing zu vermeiden.

Fazit

Mit der Grok Bild-zu-Video API bringst du Fotos schnell und automatisiert in Bewegung. Der Workflow: POST mit Bild und Prompt, request_id abfragen, GET bis fertig, MP4-URL extrahieren. Das Modell grok-imagine-video ist leistungsstark und skalierbar.

Asynchrone Abläufe sind die häufigste Fehlerquelle – teste deshalb mit Apidogs Szenarien: Variablenextraktion, Polling mit Abbruch-Bedingung, finale Assertion. So verhinderst du Integrationsfehler vor dem Go-Live.

Beginne kostenlos mit der Entwicklung deiner Integration mit Apidog. Keine Kreditkarte erforderlich.

FAQ

Welcher Modellname für die Bild-zu-Video API?

grok-imagine-video – im Feld model angeben.

Unterschied zwischen image und reference_images?

image ist der Startframe, reference_images steuern Stil und Kontext, erscheinen aber nicht als Frame. Beide kombinierbar.

Wie lange dauert die Videoerstellung?

6 Sek. 480p: meist 1–3 Minuten. 15 Sek. 720p: 4–8 Minuten. Alle 5 Sek. abfragen.

Lokale Datei als Bild?

Ja, als Data-URI kodieren: data:image/jpeg;base64,{encoded_bytes}.

Kein aspect_ratio gesetzt?

Mit image: Seitenverhältnis entspricht Quellbild. Ohne: Standard ist 16:9.

Kosten für 10 Sek. 720p-Video?

0,002 $ (Bild) + 0,70 $ (Ausgabe) = 0,702 $.

Ratenlimits?

60 Anfragen/Minute, 1 Anfrage/Sekunde. POST und GET zusammen zählen.

Videos >15 Sekunden?

Mit POST /v1/videos/extensions in mehreren Schritten verlängern; jeder Schritt asynchron.