Praxis mit der Grok-Video-3 API: alles Wichtige zur Video-Engine von xAI
Zielmodelle:
grok-video-1.5,grok-video-1.0
Inferenz-Endpunkt:https://api.toapis.com/v1/videos/generations
Verwandt: OpenAI-kompatibler Zugang · API des offiziellen Grok Imagine Kanals · Hailuo 2.3 Video-Leitfaden · Grok Video 1.5 Referenz
1. Kurzüberblick und Leistungsübersicht
- Katalog zuerst: Auch Anfragen für eine praktische Grok Video 3 Integration müssen mit den IDs beginnen, die ToAPIs tatsächlich veröffentlicht. Die öffentliche Produktions-Katalog-Momentaufnahme vom 2026-11-10 listet
grok-video-1.0undgrok-video-1.5amopenai-videoEndpunkt. Eine Prüfung dergrok-video-3Dokumentations- und Modell-Leitfaden-URLs am 2026-11-17 ergab HTTP 404. - Vertrag: Senden Sie asynchron an
POST /v1/videos/generationsund fragen Sie dannGET /v1/videos/generations/{id}ab, biscompletedoderfailederreicht ist. Offizielle Beispiele verwendenhttps://toapis.com(undhttps://toapis.cnfür Festlandchina). Andere Guides dieser Reihe verwendenhttps://api.toapis.com. Wählen Sie einen Ursprung und bleiben Sie konsistent. - Modi:
grok-video-1.5dokumentierttext_to_video,first_frame_image_to_videoundreference_images_to_video. Setzen Sievideo_generation_modeexplizit, damit ein einzelnes Referenzbild nicht als Legacy-Startbild-Job behandelt wird. - Medien: Senden Sie nur öffentliche
http://oderhttps://URLs. Laden Sie lokale Dateien mitPOST /v1/uploads/imageshoch und nutzen Sie die zurückgegebenedata.url. Senden Sie kein base64. - Nicht verifizierte Aussagen streichen: Planungsentwürfe, die eine
grok-video-3ID, ein SLA von 99,95 %, einen festen Satz von$0.030–$0.038pro Sekunde oder ein künftiges Audio-Release-Datum nennen, sind keine aktuelle ToAPIs Dokumentation. Bestätigen Sie Live-Tarife und Kanalunterstützung in Ihrem Konto.
2. Aktuelle Grok Video IDs und Generierungsmodi
Verwenden Sie den öffentlichen Modellnamen im Feld model. Ersetzen Sie ihn nicht durch einen anbieternativen Namen, einen URL-Slug oder eine unveröffentlichte grok-video-3 Zeichenkette.
| Katalog-ID | Dokumentierte Jobs | Dauer (Docs) | Auflösung | Bildeingaben |
|---|---|---|---|---|
grok-video-1.5 | Text, Startbild oder 1–7 Referenzbilder, ausgewählt über video_generation_mode | Ganzzahl 1–15 Sekunden | 480p oder 720p im Referenzmodus; Text und Startbild können 1080p nutzen, wenn der Kanal das unterstützt | Startbild: genau ein image oder input_reference. Referenzmodus: 1–7 reference_images |
grok-video-1.0 | Text-zu-Video und Bild-zu-Video | Generierungsreferenz: 1–15 Sekunden (Standard 8). Modell-Leitfaden / Playground: eine 6-Sekunden-Grenze bei der aktuell verfügbaren Variante | 480p, 720p | Optionales image plus reference_images; bis zu 8 Bilder insgesamt |
Für grok-video-1.5 sollten neue Integrationen den Modus explizit setzen:
video_generation_mode | Erforderliche Eingabe | Muss weggelassen werden |
|---|---|---|
text_to_video | Nicht leerer prompt | Jedes Bildfeld |
first_frame_image_to_video | Genau ein Startbild in image oder input_reference | Widersprüchliche Werte in beiden Aliasen; senden Sie außerdem keine Referenzliste, sofern die Referenz Ihres Kontos nichts anderes sagt |
reference_images_to_video | prompt plus 1–7 reference_images (Strings oder {"url":"..."}-Objekte) | Sich auf einen einzelnen reference_images-Eintrag ohne diesen Modus verlassen – die Legacy-Eingabe mit einem Bild bleibt Startbild-Verhalten |
Ein erfolgreiches Preisangebot garantiert nicht, dass ein Generierungskanal offen ist. Modi sind nur verfügbar, wenn sie auf einem kompatiblen Kanal freigeschaltet sind; nicht unterstützte Kombinationen können abgelehnt werden, bevor ein Task entsteht.
Übliche Seitenverhältniswerte in den Grok Video Referenzen sind 16:9, 9:16, 3:2, 2:3 und 1:1. Die Verfügbarkeit hängt weiter vom Kanal ab, senden Sie also einen Wert, den Sie für diese ID bestätigt haben.

Abbildung 1: Senden Sie einen Prompt (und optionale öffentliche Bild-URLs) an POST /v1/videos/generations, fragen Sie dieselbe Task-ID ab und lesen Sie result.data[0].url erst, wenn der Status completed ist.
Wenn Sie Funktionen des offiziellen Grok Imagine Kanals wie Videoverlängerung benötigen, ist das eine andere ID-Familie – siehe den Leitfaden zum offiziellen Imagine-Kanal. Für einen zweiten Videovertrag mit anderer Dauer-Matrix siehe den Hailuo 2.3 Leitfaden.
3. Produktionsumsetzung: cURL und Python
Die internationalen Beispiele dieser Reihe verwenden https://api.toapis.com. Die offizielle Dokumentation verweist Nutzer in Festlandchina auf https://toapis.cn. Behalten Sie einen Ursprung pro Umgebung. Pfade, Modell-IDs und der Bearer-Header bleiben gleich.
Schritt 1: cURL-Versand für grok-video-1.5
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Ein Startbild-Job nutzt denselben Pfad mit "video_generation_mode": "first_frame_image_to_video" und einer URL in image. Ein Referenzbild-Job setzt "video_generation_mode": "reference_images_to_video" und eine reference_images Liste und hält resolution bei 480p oder 720p.
Schritt 2: Python-Hilfe und Poller
Der Ausschnitt folgt dem dokumentierten Task-Status-Pfad und den Zuständen queued / in_progress / completed / failed. Bestätigen Sie id, result.data[0].url und die Antwortstruktur anhand der API-Referenz Ihres Kontos, bevor Sie ausliefern.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Speichern Sie die Version der Prompt-Vorlage beim Task-Datensatz, damit Sie einen Modell- oder Moduswechsel von einer Formulierungsänderung unterscheiden können. Laden Sie die Datei vor expires_at herunter; die Statusreferenz dokumentiert ein 30-Tage-Aufbewahrungsfenster.
4. Fehlerbehandlung und Statusmatrix
Die folgenden Kategorien sind Ausgangspunkte für die Diagnose und keine Garantie für exakte ToAPIs Fehlercodes. Eine erfolgreiche HTTP-Abfrage erfordert weiterhin, den Task-status zu lesen. Siehe die Fehlerreferenz für Request-Fehler gegenüber status: failed Gründen wie content_policy_rejected, insufficient_user_balance oder generation_timeout.
| HTTP- oder Task-Zustand | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld, Modus-/Medien-Mismatch oder nicht unterstützte Kombination | Prüfen Sie die exakte Katalog-ID, ob video_generation_mode zu den Bildfeldern passt, ob der Referenzmodus bei 480p oder 720p bleibt und ob Bildwerte öffentliche URLs sind |
401 | Fehlender oder ungültiger API-Schlüssel | Rotieren Sie den Schlüssel im ToAPIs Dashboard und bestätigen Sie den Authorization: Bearer Header |
429 | Rate- oder Parallelitätslimit | Beachten Sie Retry-After, wenn vorhanden; weichen Sie mit Jitter zurück; wiederholen Sie nur, wenn es sicher ist |
5xx oder clientseitige Zeitüberschreitung | Vorübergehendes Gateway- oder Upstream-Problem | Fragen Sie die bestehende Task-ID ab, bevor Sie erneut senden |
status: queued oder in_progress | Kein Fehler | Warten und erneut abfragen; keinen zweiten Job anlegen |
status: failed | Generierung nicht erfolgreich | Lesen Sie error.code und error.message (und error.reason, falls vorhanden). Wiederholen Sie keinen unveränderten, durch Policy abgelehnten Payload |
5. Preise und FinOps-ROI
- Verwenden Sie keine Stückpreise aus Planungsentwürfen erneut. Die API-Referenz von
grok-video-1.5stellt fest, dass die Preisgestaltung der aktuellen Konto- und SKU-Konfiguration folgt und die Seite keinen festen Preis pro Sekunde garantiert. Offizielle Anbieter-Referenzzeilen auf der ToAPIs Preisseite dienen nur der Anzeige und können von der Abrechnung Ihres Kontos abweichen. - Ein Angebot ist keine Kanalgarantie. Die 1.5-Referenz merkt an, dass ein erfolgreiches Preisangebot nicht bedeutet, dass ein Generierungskanal verfügbar ist.
- Steuern Sie die Kosten in der Prompt-Ebene: Entwerfen Sie in
720pund mittlerer Dauer wie 8 Sekunden, halten Sie eine versionierte Vorlage, ändern Sie jeweils nur eine Variable und senden Sie nach einer clientseitigen Zeitüberschreitung erst erneut, wenn Sie den Task-Status geprüft haben. - Offizielle Anbieterverträge enthalten oft Jahresverpflichtungen, Sitzkontingente und Vorauszahlungsuntergrenzen. Die ToAPIs Abrechnung erfolgt typischerweise als Bezahlung nach Verbrauch – bestätigen Sie die aktiven Bedingungen Ihres Kontos.
6. Häufig gestellte Fragen
Siehe den FAQ-Block im Frontmatter. Kurzfassung: grok-video-3 ist keine aktuelle öffentliche Katalog-ID; beginnen Sie mit grok-video-1.5 oder grok-video-1.0; behandeln Sie die 1.0-Dauergrenze als kanalspezifische Prüfung; synchronisiertes Audio ist nicht dokumentiert; fragen Sie immer den Generierungs-Status-Pfad ab und speichern Sie die Task-ID.
7. Aktionscheckliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Bestätigen Sie über
GET /v1/models?type=video, dassgrok-video-1.5odergrok-video-1.0für Ihren Schlüssel erscheint – senden Sie keingrok-video-3, solange es nicht später in dieser Liste und in der API-Referenz auftaucht. - Testen Sie den cURL-Ausschnitt kurz mit
video_generation_mode: "text_to_video",duration: 8undresolution: "720p". - Fragen Sie
GET /v1/videos/generations/{id}mit einer begrenzten Frist ab und laden Sie das Ergebnis vorexpires_atherunter. - Nächster Schritt: der Leitfaden zum OpenAI-kompatiblen Zugang, wenn Sie einen bestehenden Client auf ToAPIs zeigen lassen, der Grok Video 1.5 Modell-Leitfaden für den Live-Status im Katalog und der Grok Video 1.0 Modell-Leitfaden, bevor Sie sich bei dieser ID auf eine Dauer über 6 Sekunden verlassen.







