Grok Imagine 1.0 Video Generation API: Endpunkte, Auth-Scopes und Fehlerbehandlung
Zielmodelle:
grok-imagine-video-official,grok-imagine-video-1.5-official
Inferenz-Endpunkt:https://api.toapis.com/v1/videos/generations
Verwandt: Praxisleitfaden Grok Video · OpenAI-kompatibler Zugang · Offizielle Imagine-Generierung · Offizielles Imagine Extend
1. Kurzüberblick und Leistungsübersicht
- IDs: Anfragen, die um „Grok Imagine 1.0“ herum betitelt sind, benötigen die Zeichenketten, die ToAPIs tatsächlich veröffentlicht. Die öffentliche Katalog-Momentaufnahme vom 2026-11-10 listet
grok-imagine-video-officialundgrok-imagine-video-1.5-official(beide erscheinen auch unter Bildgenerierung sowie unteropenai-video). Eine Prüfung vom 2026-11-17 einesgrok-imagine-1.0-Dokumentationspfads ergab HTTP 404. - Auth: Senden Sie
Authorization: Bearer $TOAPIS_API_KEY. Die offiziellen Seiten dokumentieren keine OAuth-Scopes, granularen Berechtigungsnamen oder einen Scope-Discovery-Endpunkt für diese Aufrufe. - Endpunkte: Erstellen mit
POST /v1/videos/generations. Abfragen mitGET /v1/videos/generations/{id}. Verlängern Sie die Ausgabe des offiziellen Kanals mitPOST /v1/videos/{video_id}/extendoder mitPOST /v1/videos/extendplusvideo_urls, wenn Sie nur eine öffentliche Video-URL haben. Laden Sie Standbilder mitPOST /v1/uploads/imageshoch. - Fähigkeiten:
grok-imagine-video-officialdeckt Text-zu-Video, Bild-zu-Video und Mehrfachreferenz-Generierung bei480poder720pab, Dauer 1–15 Sekunden, und Extend um 2–10 Sekunden.grok-imagine-video-1.5-officialist ausschließlich First-Frame-Image-to-Video, verlangt genau einimage, erlaubt1080pund unterstützt kein Extend. - Preisform (kein fester Stückpreis auf den Referenzseiten): Ausgabe wird pro Sekunde nach Auflösung abgerechnet; jedes Eingabebild wird pro Bild abgerechnet; Extend rechnet zusätzlich die Dauer des Quellvideos ab. Bestätigen Sie die Live-Tarife Ihres Kontos.
2. Endpunkte, Authentifizierung und Modellverträge
Die offizielle Dokumentation verwendet https://toapis.com (und https://toapis.cn für Festlandchina). Andere Guides dieser Reihe verwenden https://api.toapis.com. Wählen Sie einen Ursprung und bleiben Sie konsistent. Jeder Pfad unten nutzt denselben Bearer-Header.
| Aktion | Methode und Pfad | Modellhinweise |
|---|---|---|
| Standbild hochladen | POST /v1/uploads/images | Multipart-file. JPEG, PNG, WebP oder GIF, maximal 30 MB. data.url auslesen |
| Video erstellen | POST /v1/videos/generations | Beide offiziellen Imagine-IDs |
| Status abfragen | GET /v1/videos/generations/{id} | Gleicher Pfad für Generierungs- und Extend-Tasks |
| Aus vorherigem Task verlängern | POST /v1/videos/{video_id}/extend | Nur grok-imagine-video-official. video_id ist die ID des vorherigen Generierungs-Tasks |
| Aus öffentlicher URL verlängern | POST /v1/videos/extend | Gleiche offizielle ID; video_urls ist erforderlich, wenn kein Pfad-ID vorhanden ist |
| Katalog-ID | Dokumentierte Jobs | Dauer | Auflösung | Bilder | Extend |
|---|---|---|---|---|---|
grok-imagine-video-official | Text-zu-Video, Startbild und Mehrfachreferenz | 1–15 Sekunden (Standard 8) | 480p, 720p | Optionales image plus reference_images; bis zu 7 insgesamt | 2–10 Sekunden (duration Standard 6) |
grok-imagine-video-1.5-official | Ausschließlich First-Frame-Image-to-Video | 1–15 Sekunden (Standard 8) | 480p, 720p, 1080p | image ist erforderlich (genau ein Startbild). Zusätzliche reference_images zählen weiter zum 7-Bilder-Gesamtlimit | Nicht unterstützt |
Seitenverhältniswerte in den offiziellen Imagine-Referenzen umfassen 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 und 1:1. Senden Sie einen Wert, den Sie für diese ID und diesen Kanal bestätigt haben.
Es gibt keine dokumentierte öffentliche Scope-Zeichenkette, um „generieren“, „verlängern“ oder „hochladen“ separat anzufordern. Der Zugang ist das, was API-Schlüssel, Benutzergruppe und Kanal-Konfiguration bereits erlauben. Wenn ein Aufruf aus Berechtigungs- oder Verfügbarkeitsgründen fehlschlägt, prüfen Sie die Modellliste des Schlüssels und die Fehlerreferenz, statt einen erfundenen scope-Query-Parameter anzuhängen.

Abbildung 1: Ein einziger Bearer-API-Key autorisiert Upload, Generierung oder Extend und Statusabfrage; die offizielle 1.5-ID fügt keinen Extend-Zweig hinzu.
Für die nicht offizielle Grok Video Familie (grok-video-1.0 / grok-video-1.5) siehe den Praxisleitfaden Grok Video. Diese IDs sind ein anderer Vertrag und erben diesen Extend-Pfad nicht.
3. Produktionsumsetzung: cURL und Python
Schritt 1: cURL – Text-zu-Video im offiziellen Kanal
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Ein Startbild-Job auf grok-imagine-video-1.5-official nutzt denselben Pfad, verlangt "image": "https://example.com/portrait.jpg" und kann "resolution": "1080p" setzen. Ersetzen Sie die Beispiel-URL durch eine öffentliche Adresse – laden Sie die Datei zuerst hoch, wenn sie lokal ist:
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
Schritt 2: Python – generieren, abfragen und optional verlängern
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
Um aus einer öffentlichen MP4 statt einer Task-ID zu verlängern, nutzen Sie POST /v1/videos/extend mit demselben offiziellen Modell, Prompt, duration und einer video_urls-Liste. Rufen Sie Extend nicht mit grok-imagine-video-1.5-official auf.
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. Die Fehlerreferenz unterscheidet Request-Fehler, error.reason-Werte fehlgeschlagener Tasks und Webhook-Payloads.
| HTTP- oder Task-Zustand | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld, fehlendes erforderliches image bei 1.5-official, Bilderanzahl überschritten oder Extend an ein Modell gesendet, das es nicht unterstützt | Prüfen Sie die exakte offizielle ID, Dauer (1–15 bei Generierung, 2–10 bei Extend), Auflösung (1080p nur bei 1.5-official) und dass alle Medienwerte öffentliche URLs sind |
401 | Fehlender oder ungültiger API-Schlüssel | Rotieren Sie den Schlüssel und bestätigen Sie Authorization: Bearer. Fügen Sie keinen undokumentierten scope-Parameter als Workaround hinzu |
429 | Rate- oder Parallelitätslimit | Beachten Sie Retry-After, wenn vorhanden; weichen Sie mit Jitter zurück |
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 |
status: failed mit content_policy_rejected | Sicherheits- oder Urheberrechtsprüfung | Prüfen Sie Prompt und jedes Referenzasset; konforme Eingaben können dennoch eine abgelehnte Ausgabe erzeugen |
status: failed mit insufficient_user_balance oder token_quota_exceeded | Guthaben oder Token-Kontingent | Prüfen Sie sowohl Guthaben als auch periodische Limits |
status: failed mit generation_timeout, model_unavailable oder service_busy | Upstream-Timeout oder Verfügbarkeit | Prüfen Sie zuerst die bestehende ID; wiederholen Sie dann mit Backoff nur, wenn der Task endgültig ist |
5. Preise und FinOps-ROI
Die offiziellen Imagine-Seiten zu Generierung und Extend beschreiben eine Abrechnungsform und keinen festen öffentlichen Stückpreis:
Verwenden Sie die für Ihr Konto und Ihre SKU zurückgegebenen Tarife und keine Entwurfszahlen.
grok-imagine-video-1.5-officialenthält immer eine Eingabebild-Gebühr, weil ein Startbild erforderlich ist.- Extend ist keine kostenlose Fortsetzung. Die offizielle Extend-Abrechnung umfasst die generierten Verlängerungssekunden und die Dauer des Quellvideos. Gestapelte Extends rechnen daher die wachsende Quelllänge erneut ab – bestätigen Sie dieses Verhalten anhand eines Live-Angebots, bevor Sie eine Schleife bauen.
- Verwenden Sie keine Stückpreise oder SLA-Werte aus Planungsentwürfen erneut. Offizielle Anbieter-Referenzzeilen auf der ToAPIs Preisseite dienen nur der Anzeige und können von der Kontoabrechnung abweichen.
- Entwerfen Sie in
720pund mittlerer Dauer, ändern Sie jeweils nur eine Variable und senden Sie nach einer clientseitigen Zeitüberschreitung erst erneut, wenn Sie den Task-Status geprüft haben.
6. Häufig gestellte Fragen
Siehe den FAQ-Block im Frontmatter. Kurzfassung: Senden Sie grok-imagine-video-official oder grok-imagine-video-1.5-official, nicht grok-imagine-1.0; Auth ist ein Bearer-API-Key ohne öffentliche OAuth-Scope-Matrix; 1.5-official ist ausschließlich Startbild und kann nicht verlängern; die Extend-Dauer ist 2–10 Sekunden und rechnet die Quelllänge zusätzlich ab; unterscheiden Sie stets HTTP-Fehler von status: failed.
7. Aktionscheckliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Bestätigen Sie über
GET /v1/models?type=video, dassgrok-imagine-video-officialodergrok-imagine-video-1.5-officialfür Ihren Schlüssel erscheint. - Testen Sie eine offizielle Generierung in
720pkurz, fragen SieGET /v1/videos/generations/{id}ab und laden Sie die Datei vorexpires_atherunter. - Wenn Sie eine Fortsetzung benötigen, verlängern Sie nur mit
grok-imagine-video-officialund einerdurationvon 2–10 Sekunden und bestätigen Sie anschließend, dass das Angebot die Abrechnung der Quell-Dauer einschließt. - Nächster Schritt: der offizielle Imagine Modell-Leitfaden und der offizielle Imagine 1.5 Modell-Leitfaden für den Live-Status im Katalog, und der Praxisleitfaden Grok Video, falls Sie die nicht offizielle
grok-video-*Familie gemeint haben.







