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

TL;DR

Die Grok Bild-zu-Video API verwendet das Modell grok-imagine-video, um ein statisches Bild in einen Videoclip zu animieren. Sie senden Ihre Bild-URL, einen Prompt und optionale Einstellungen per POST an https://api.x.ai/v1/videos/generations. Die API gibt sofort eine request_id zurück. Anschließend fragen Sie GET /v1/videos/{request_id} ab, bis der status zu "done" wird. Die Dauer liegt zwischen 1 und 15 Sekunden. Die Preise beginnen bei 0,05 $ pro Sekunde für 480p-Ausgabe.

Einführung

Am 28. Januar 2026 hat xAI das Modell grok-imagine-video für den öffentlichen API-Zugang freigegeben. Innerhalb dieses ersten Monats generierte das Modell 1,2 Milliarden Videos und belegte Platz eins auf dem Artificial Analysis Text-zu-Video-Leaderboard. Bild-zu-Video ist eine seiner Vorzeigefunktionen: Sie übergeben der API ein Foto und einen beschreibenden Prompt, und es animiert das Foto zu einem kurzen Videoclip, der als MP4 heruntergeladen werden kann.

Dieser asynchrone Workflow, bei dem Sie einen Auftrag übermitteln und dann auf dessen Abschluss warten, stellt eine Test-Herausforderung dar, die viele Entwickler überspringen. Ihre Integration ist nicht abgeschlossen, wenn der erste POST 200 zurückgibt. Sie ist abgeschlossen, wenn Sie bestätigt haben, dass die Abfrageschleife die Zustände "processing", "done" und "failed" unter realen Netzwerkbedingungen korrekt verarbeitet.

Apidogs Test-Szenarien lösen dies direkt. Sie können eine verkettete Sequenz erstellen: POST an /v1/videos/generations senden, die request_id extrahieren, die Abfrage in einer Schleife wiederholen, bis status == "done", und dann überprüfen, ob die Video-URL vorhanden ist. Laden Sie Apidog kostenlos herunter, um den Test-Walkthrough später in diesem Leitfaden zu verfolgen.

Was ist die Grok Bild-zu-Video API?

Die Grok Bild-zu-Video API ist Teil des Videoerstellungsprodukts von xAI. Sie läuft unter dem Modell grok-imagine-video und akzeptiert ein Bild als Startrahmen des Ausgabevideos. Das Modell analysiert den Bildinhalt und den Textprompt und erzeugt dann natürliche Bewegung, um die Szene zu animieren.

Der API-Endpunkt ist:

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

Die Authentifizierung verwendet einen Standard-Bearer-Token:

Authorization: Bearer YOUR_XAI_API_KEY

Sie erhalten Ihren Schlüssel von der xAI-Konsole. Die gleiche API-Oberfläche unterstützt auch Text-zu-Video (lassen Sie den Parameter image weg), Video-Erweiterungen und Video-Bearbeitungen.

Wie der Bild-zu-Video-Prozess funktioniert

Der Parameter image im Anfragetext bezeichnet den ersten Frame des Ausgabevideos. Das Modell ersetzt das Bild nicht. Es beginnt damit. Jedes Pixel im ersten Frame stammt aus Ihrem Quellbild. Das Modell sagt dann voraus, wie sich die Szene basierend auf Ihrem Prompt in der Zeit entwickeln würde.

Zum Beispiel: Sie stellen ein Foto eines Bergsees bei Sonnenaufgang zur Verfügung. Ihr Prompt lautet: "Sanfte Wellen breiten sich über das Wasser aus, während morgendlicher Nebel aufzieht." Der erste Frame des Ausgabevideos ist Ihr Foto. Nachfolgende Frames zeigen, wie sich Wasser und Nebel gemäß dem Prompt animieren.

Dies unterscheidet sich von Text-zu-Video, wo das Modell den ersten Frame selbst generiert. Bild-zu-Video gibt Ihnen genaue Kontrolle über die Startszene.

Sie sollten Bild-zu-Video wählen, wenn: - Sie vorhandene Produktfotos, Landschaften oder Porträts haben, die Sie in Bewegung bringen möchten. - Ihre Markenwerte eine konsistente visuelle Identität im ersten Frame benötigen. - Sie möchten, dass die Bewegung in einer realen oder spezifischen Szene verwurzelt ist.

Sie sollten Text-zu-Video wählen, wenn: - Sie visuelle Ideen ohne Referenzbild erkunden. - Sie möchten, dass das Modell die Szenenkomposition vollständig entscheidet. - Die Iterationsgeschwindigkeit wichtiger ist als die Präzision des ersten Frames.

Voraussetzungen

Bevor Sie Ihren ersten Aufruf tätigen, benötigen Sie:

1. Ein xAI-Konto unter console.x.ai.
2. Einen API-Schlüssel von der xAI-Konsole. Bewahren Sie diesen in einer Umgebungsvariablen auf, nicht fest codiert.
3. Python 3.8+ oder Node.js 18+ (Beispiele in diesem Leitfaden verwenden beides).
4. Eine öffentlich zugängliche Bild-URL oder ein base64-kodiertes Bild als Daten-URI.

Legen Sie Ihren Schlüssel als Umgebungsvariable fest:

export XAI_API_KEY="your_key_here"

Installieren Sie das xAI Python SDK, wenn Sie den höherwertigen Client wünschen:

pip install xai-sdk

Für reine HTTP-Aufrufe sind keine zusätzlichen Pakete über requests (Python) oder fetch (Node.js) hinaus erforderlich.

Ihre erste Bild-zu-Video-Anfrage stellen

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"
  }'

Die Antwort kommt sofort mit einer request_id zurück:

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

Das Video ist noch nicht bereit. Die Generierung erfolgt asynchron in der Infrastruktur von xAI. Sie müssen das Ergebnis abfragen.

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}")

Verwenden eines Base64-Bildes

Wenn Ihr Bild lokal oder nicht öffentlich zugänglich ist, kodieren Sie es als Daten-URI:

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. Die API gibt die request_id zurück, während Ihr Video auf den Servern von xAI gerendert wird. Sie müssen den Statusendpunkt abfragen:

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

Das Statusfeld durchläuft diese Werte:

Eine abgeschlossene Antwort sieht so aus:

{
  "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")

Halten Sie das Abfrageintervall bei 5 Sekunden oder länger. Die API hat ein Ratenlimit von 60 Anfragen pro Minute (1 pro Sekunde). Eine zu enge Abfrage mehrerer Jobs gleichzeitig kann dieses Budget schnell aufbrauchen.

Verwenden des xAI Python SDK

Die xai-sdk-Bibliothek kapselt das asynchrone Muster für Sie. client.video.generate() übermittelt den Auftrag und blockiert, bis das Video fertig ist, wobei das gesamte Polling intern gehandhabt wird:

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 übernimmt die Abfrageschleife, Statusprüfungen und Fehlerfortpflanzung. Verwenden Sie diesen Ansatz, wenn Sie sauberen Anwendungscode wünschen, ohne das HTTP-Polling selbst verwalten zu müssen.

Für eine feingranulare Kontrolle über Abfrageintervalle, Wiederholungsstrategien oder Protokollierung bietet der Raw-Requests-Ansatz mehr Flexibilität.

Auflösung, Dauer und Seitenverhältnis steuern

Die Grok Video API gibt Ihnen direkte Kontrolle über das Ausgabeformat.

Dauer

Der Parameter duration akzeptiert ganze Zahlen von 1 bis 15 Sekunden. Der Standardwert ist 6.

"duration": 10

Längere Videos kosten mehr. Ein 10-Sekunden-Clip kostet etwa das 10-fache eines 1-Sekunden-Clips bei gleicher Auflösung.

Auflösung

Zwei Optionen sind verfügbar:

"resolution": "720p"

Seitenverhältnis

Der Parameter aspect_ratio steuert die Abmessungen des Ausgabebildes:

Wenn Sie ein image angeben, wird das Seitenverhältnis standardmäßig an die Abmessungen des Quellbildes angepasst. Legen Sie es explizit fest, um es zu überschreiben oder zuzuschneiden.

Verwenden von Referenzbildern zur Stilführung

Der Parameter reference_images unterscheidet sich vom Parameter image. Das Verständnis des Unterschieds ist wichtig.

image: Das Quellfoto, das zum ersten Frame des Videos wird. Das Modell animiert von diesem Startpunkt aus.

reference_images: Ein Array von bis zu 7 Bildern, die den Stil, Inhalt oder visuellen Kontext des generierten Videos leiten. Diese sind keine Frames in der Ausgabe. Sie beeinflussen, wie das Modell Bewegung und Aussehen rendert.

Verwenden Sie reference_images, wenn Sie möchten, dass das Ausgabevideo visuelle Merkmale aus vorhandenen Assets übernimmt, aber nicht als Start-Frame:

{
  "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"
}

In diesem Beispiel ist product-shot.jpg der erste Frame. Die Referenzbilder leiten die Beleuchtung und die stilistische Behandlung.

Sie können Referenzbilder ohne ein First-Frame-Bild angeben. In diesem Fall generiert das Modell eine Text-zu-Video-Ausgabe, während es Stilführung von den Referenzen bezieht.

Videos erweitern und bearbeiten

Die API unterstützt zwei zusätzliche Operationen über die ursprüngliche Generierung hinaus.

Ein Video erweitern

POST /v1/videos/extensions nimmt ein bestehendes Video und generiert zusätzliche Sekunden ab dem Punkt, an dem es aufgehört hat. Dies ist nützlich, um längere Clips aus mehreren Generierungsdurchläufen zu erstellen, während das Limit von 15 Sekunden pro Aufruf eingehalten wird.

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
  }'

Die Antwort folgt dem gleichen asynchronen Muster: Fragen Sie GET /v1/videos/{request_id} für den erweiterten Clip ab.

Ein Video bearbeiten

POST /v1/videos/edits wendet prompt-gesteuerte Änderungen auf ein bestehendes Video an. Sie können bestimmte Aspekte des Inhalts oder der Bewegung ändern, ohne von Grund auf neu zu generieren.

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"
  }'

Sowohl Erweiterungen als auch Bearbeitungen sind asynchron und verwenden dasselbe Abfragemuster.

Preisübersicht: Was ein 10-Sekunden-Video kostet

Die xAI Video API berechnet zwei Komponenten: die Verarbeitung des Eingabebildes und die Dauer des Ausgabevideos.

Beispiel: 10-Sekunden-Video bei 720p

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

Beispiel: 6-Sekunden-Video bei 480p (Standardeinstellungen)

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

Die Gebühr für das Eingabebild fällt jedes Mal an, wenn Sie eine Generierungsanfrage senden, selbst wenn Sie dieselbe Bild-URL wiederverwenden. Planen Sie Ihre Generierungsaufrufe entsprechend, wenn Sie an demselben Basisbild iterieren.

Text-zu-Video (ohne image-Parameter) entfällt die Eingabegebühr von 0,002 $, folgt aber ansonsten der gleichen Preisgestaltung pro Sekunde.

So testen Sie Ihre Grok Video API Integration mit Apidog

Das asynchrone Muster stellt eine Testherausforderung dar, die einfache Einzelschuss-Anfragetests nicht abdecken können. Sie müssen überprüfen, ob:

1. Die Generierungsanfrage eine request_id zurückgibt.
2. Die Abfrageanfrage den Status "processing" korrekt handhabt, während sie wartet.
3. Die endgültige Antwort status == "done" und eine nicht leere Video-URL enthält.

Apidogs Test-Szenarien verketten diese Schritte in einem automatisierten Workflow. So erstellen Sie ihn:

Schritt 1: Ein neues Test-Szenario erstellen

Öffnen Sie in Apidog das Modul "Tests" und klicken Sie auf die Schaltfläche +, um ein neues Szenario zu erstellen. Nennen Sie es "Grok Bild-zu-Video asynchroner Workflow".

Schritt 2: Die Generierungsanfrage hinzufügen

Fügen Sie einen benutzerdefinierten POST-Anforderungsschritt hinzu:

• URL: https://api.x.ai/v1/videos/generations
• Methode: POST
• Header: Authorization: Bearer {{xai_api_key}}
• Body (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

Schritt 3: Die request_id extrahieren

Fügen Sie nach dem POST-Schritt einen Variablenextraktions-Prozessor hinzu. Konfigurieren Sie ihn:

• Variablenname: video_request_id
• Quelle: Antwortkörper
• Extraktionsmethode: JSONPath
• JSONPath-Ausdruck: $.request_id

Apidog speichert den extrahierten Wert in {{video_request_id}} zur Verwendung in späteren Schritten.

Schritt 4: Die Abfrageschleife erstellen

Fügen Sie einen For-Schleifenprozessor hinzu. Fügen Sie innerhalb der Schleife die Abfrageanfrage hinzu:

• URL: https://api.x.ai/v1/videos/{{video_request_id}}
• Methode: GET
• Header: Authorization: Bearer {{xai_api_key}}

Fügen Sie innerhalb der Schleife einen Variablenextraktions-Prozessor hinzu, um den aktuellen Status zu erfassen:

• Variablenname: video_status
• JSONPath: $.status

Fügen Sie nach der Statusextraktion einen Warte-Prozessor (5000 ms) hinzu, um das Ratenlimit nicht zu überschreiten.

Setzen Sie die Break If-Bedingung der Schleife auf: {{video_status}} == "done".

Schritt 5: Die Video-URL bestätigen

Fügen Sie nach der For-Schleife einen letzten GET-Schritt zum selben Abfrageendpunkt hinzu. Fügen Sie einen Assertions-Prozessor hinzu:

• Feld: $.video.url
• Bedingung: Ist nicht leer

Diese Assertion bestätigt, dass die Video-URL vorhanden ist, bevor Ihr Test bestanden wird.

Einen tieferen Einblick, wie asynchrone APIs mit Apidog getestet werden, einschließlich komplexerer Abfragemuster und CI/CD-Integration, finden Sie in dem entsprechenden Leitfaden.

Das Szenario ausführen

Klicken Sie in der Test-Szenario-Ansicht auf "Ausführen". Apidog führt den POST aus, extrahiert die request_id, wiederholt die Abfrage, bis status == "done" ist, und bewertet dann Ihre Assertions. Der Testbericht zeigt den Status und die Zeit jedes Schritts an.

Sie können dieses Szenario mit der Apidog CLI in Ihre CI/CD-Pipeline integrieren:

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

Häufige Fehler und Behebungen

401 Unauthorized

Ihr API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie das Format des Authorization-Headers: Bearer YOUR_XAI_API_KEY. Bestätigen Sie, dass der Schlüssel in der xAI-Konsole aktiv ist.

422 Unprocessable Entity

Der Anfragetext ist fehlerhaft. Häufige Ursachen: Das Feld model fehlt, der prompt ist leer oder die image.url ist nicht zugänglich. Testen Sie die Bild-URL in einem Browser, bevor Sie sie verwenden.

Bild-URL nicht zugänglich

Die Server von xAI müssen in der Lage sein, die Bild-URL zum Zeitpunkt der Generierung abzurufen. Private URLs, Localhost-Adressen oder URLs hinter einer Authentifizierung werden fehlschlagen. Verwenden Sie stattdessen ein öffentliches CDN oder eine Base64-Daten-URI.

Status bleibt auf "processing" auf unbestimmte Zeit

Eine Generierung kann je nach Auflösung und Dauer zwischen 30 Sekunden und mehreren Minuten dauern. Wenn der Status länger als 10 Minuten auf "processing" bleibt, ist der Job möglicherweise ins Stocken geraten. Senden Sie eine neue Anfrage. Die xAI API gibt derzeit kein Timeout-Signal getrennt von "failed" aus.

Ratenlimit-Fehler (429)

Die API erlaubt 60 Anfragen pro Minute und 1 pro Sekunde. Wenn Sie mehrere Jobs gleichzeitig abfragen, staffeln Sie Ihre Anfragen. Fügen Sie mindestens ein time.sleep(1) zwischen den Abfrageaufrufen ein.

Base64-Upload abgelehnt

Stellen Sie sicher, dass Ihre Daten-URI das korrekte MIME-Typ-Präfix enthält. Verwenden Sie data:image/jpeg;base64, für JPEG-Dateien und data:image/png;base64, für PNG-Dateien.

Seitenverhältnis-Fehler

Wenn Sie ein explizites aspect_ratio festlegen, das erheblich von den Proportionen Ihres Quellbildes abweicht, kann das Modell zuschneiden oder Letterboxing anwenden. Passen Sie das Seitenverhältnis an Ihr Quellbild an, um die besten Ergebnisse zu erzielen.

Fazit

Die Grok Bild-zu-Video API bietet Ihnen einen direkten Weg von einem statischen Foto zu einem kurzen animierten Clip. Sie senden das Bild und den Prompt per POST, erhalten eine request_id, fragen ab, bis es fertig ist, und laden das MP4 herunter. Das Modell grok-imagine-video belegte im Januar 2026 den ersten Platz auf dem Artificial Analysis Leaderboard. In diesem einzelnen Monat wurden über eine Milliarde Videos generiert. Dieser Umfang spiegelt wider, wie leistungsfähig das zugrunde liegende Modell ist.

Das asynchrone Abfragemuster ist der Punkt, an dem die meisten Integrationen schiefgehen. Ein richtiger Test in Apidogs Test-Szenarien deckt den Schritt der Variablenextraktion, die Abfrageschleife mit Abbruchbedingung und eine abschließende URL-Assertion ab. Diese Kombination fängt Probleme ab, bevor sie die Produktion erreichen.

Beginnen Sie kostenlos mit der Entwicklung Ihrer Integration mit Apidog. Keine Kreditkarte erforderlich.

FAQ

Welchen Modellnamen verwende ich für die Grok Bild-zu-Video API?

Der Modellname ist grok-imagine-video. Übergeben Sie ihn als model-Feld in Ihrem POST-Anfragetext.

Was ist der Unterschied zwischen den Parametern image und reference_images?

Der Parameter image legt den ersten Frame des Ausgabevideos fest. Das Modell animiert von diesem Startbild aus weiter. Das reference_images-Array bietet Stil- und Inhaltsführung, ohne als Frame verwendet zu werden. Sie können beides in derselben Anfrage kombinieren.

Wie lange dauert die Videoerstellung?

Die Generierungszeit variiert je nach Dauer und Auflösung. Ein 6-Sekunden-480p-Video dauert typischerweise 1 bis 3 Minuten. Ein 15-Sekunden-720p-Video kann 4 bis 8 Minuten dauern. Fragen Sie alle 5 Sekunden ab, um den Status zu überprüfen, ohne Ihr Ratenlimit zu überschreiten.

Kann ich eine lokale Datei als Quellbild verwenden?

Ja. Kodieren Sie Ihre lokale Datei als Base64-Daten-URI: data:image/jpeg;base64,{encoded_bytes}. Übergeben Sie diesen String als url-Wert innerhalb des image-Objekts.

Was passiert, wenn ich aspect_ratio nicht angebe?

Wenn Sie einen image-Parameter angeben, wird das Seitenverhältnis standardmäßig an die nativen Proportionen des Quellbildes angepasst. Bei der Generierung von Text-zu-Video ohne Bild ist der Standardwert 16:9.

Wie viel kostet ein 10-Sekunden-720p-Video?

Das Eingabebild kostet 0,002 $. Die Ausgabe kostet 10 × 0,07 $ = 0,70 $. Gesamt: ca. 0,702 $ pro Video.

Wie sind die Ratenlimits?

Die API erlaubt 60 Anfragen pro Minute und 1 Anfrage pro Sekunde. Dies umfasst sowohl die Generierungs-POST- als auch die Abfrage-GET-Anfragen zusammen.

Kann ich ein Video über 15 Sekunden hinaus verlängern?

Ja, indem Sie den Endpunkt POST /v1/videos/extensions verwenden. Sie generieren einen ersten Clip von bis zu 15 Sekunden und erweitern ihn dann mit zusätzlichen Generierungsdurchläufen. Jede Erweiterung folgt ebenfalls dem asynchronen Abfragemuster.