Zugang zur Grok-Video-3 API über OpenAI-kompatible Endpunkte
Zielmodelle:
grok-video-1.5,grok-video-1.0
Inferenz-Endpunkt:https://api.toapis.com/v1/videos/generations
Verwandt: Praxis-Guide zu Grok Video · API des offiziellen Grok Imagine Kanals · Chatbox OpenAI-kompatible Einrichtung · Modelle auflisten
1. Kurzüberblick und Leistungsübersicht
- Was „OpenAI-kompatibel“ hier bedeutet: ToAPIs dokumentiert einen einzigen
/v1Ursprung, Bearer-Authentifizierung sowie eine Modellliste und Chat-Completions-API im OpenAI-Stil. Öffentliche Grok Video IDs sind in deropenai-videoEndpunktfamilie des Katalogs registriert. Das bedeutet nicht, dass eine unveröffentlichtegrok-video-3ID funktioniert, und es dokumentiert für sich genommen keine OpenAI Videos SDK-Methode. - IDs: Verwenden Sie
grok-video-1.5odergrok-video-1.0, nachdem sie für Ihren Schlüssel inGET /v1/models?type=videoerscheinen. Die öffentliche Katalog-Momentaufnahme vom 2026-11-10 listetgrok-video-3nicht. - Videopfad: Erstellen mit
POST /v1/videos/generations. Abfragen mitGET /v1/videos/generations/{id}. Offizielle Beispiele verwendenhttps://toapis.com(undhttps://toapis.cnfür Festlandchina). Diese Reihe verwendet auchhttps://api.toapis.com. - Gemeinsame Authentifizierung: Ein API-Schlüssel in
Authorization: Bearer. Es gibt kein separates öffentliches OAuth-Scope-Dokument für diese Videoaufrufe. - Client-Wahl: Verwenden Sie das OpenAI SDK gegen
base_url="https://api.toapis.com/v1"für Chat-Arbeit und für eine vertraute Schlüssel- und Ursprungskonfiguration. Für Grok Video nutzt dieser Guide den dokumentierten REST-JSON-Body, damitvideo_generation_modeund Bild-URL-Felder explizit bleiben.
2. Kompatibler Ursprung, Modellliste und Videopfade
Halten Sie Ursprung, /v1 Präfix und Schlüssel zusammen. Einen ToAPIs Schlüssel mit https://api.openai.com/v1 zu mischen oder einen ToAPIs Ursprung mit einem anbieternativen Grok-Pfad, ist eine andere – und undokumentierte – Konfiguration.
| Schritt | Dokumentierter Pfad | Hinweise |
|---|---|---|
| Modelle auflisten | GET /v1/models?type=video | Das Standard-GET /v1/models liefert nur Textmodelle. Verwenden Sie type=video oder type=all |
| Ein lokales Bild hochladen | POST /v1/uploads/images (multipart file) | Lesen Sie data.url. Senden Sie kein base64 im Generierungsaufruf |
| Einen Grok Video Job erstellen | POST /v1/videos/generations | Der Body enthält model, prompt und die 1.5 Modus- und Medienfelder |
| Status abfragen | GET /v1/videos/generations/{id} | Endzustände sind completed und failed |
| Chat (kein Video) | POST /v1/chat/completions | Teilt nur Ursprung und Schlüssel |
Setzen Sie bei grok-video-1.5 video_generation_mode auf text_to_video, first_frame_image_to_video oder reference_images_to_video, damit das JSON zu den gesendeten Medien passt. Der Feldvertrag steht im Praxis-Guide zu Grok Video und in der Grok Video 1.5 API-Referenz.

Abbildung 1: Richten Sie den Client auf einen ToAPIs /v1 Ursprung, entdecken Sie grok-video-1.5 oder grok-video-1.0 über die Modellliste und senden und fragen Sie dann unter /v1/videos/generations ab – nicht unter chat/completions.
Wenn Sie einen Desktop-Client statt Anwendungscode konfigurieren, beschreibt der Chatbox Einrichtungs-Guide das Host-Feld-Muster für Chat. Erwarten Sie nicht, dass derselbe Chat-Pfad eine Videodatei zurückgibt.
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.
Schritt 1: ID entdecken, dann mit cURL senden
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
Prüfen Sie die Modellliste auf die exakte id Zeichenkette, bevor Sie sie fest verdrahten. Wenn grok-video-3 fehlt, senden Sie es nicht.
Schritt 2: Python – gemeinsamer Ursprung, REST-Videoaufrufe
Das OpenAI SDK wird nur für die gemeinsame base_url und den API-Schlüssel gezeigt. Video-Erstellung und -Abfrage bleiben auf den dokumentierten generations-Pfaden, damit die 1.5 Body-Felder nicht in einem inoffiziellen Client-Mapping verloren gehen.
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
Wenn der Listenaufruf eine unerwartete Struktur zurückgibt, protokollieren Sie das rohe JSON und gleichen Sie den Parser mit der Seite Modelle auflisten für Ihr Konto ab. Erfinden Sie keinen Ausweichweg, der grok-video-3 sendet, wenn die ID fehlt.
4. Fehlerbehandlung und Statusmatrix
Die folgenden Kategorien sind Diagnose-Ausgangspunkte und keine Garantie für exakte ToAPIs Fehlercodes. Eine erfolgreiche HTTP-Abfrage erfordert weiterhin, den Task-status zu lesen. Siehe die Fehlerreferenz.
| HTTP- oder Task-Zustand | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Unbekannte Modell-ID, Modus-/Medien-Mismatch oder ein Video-Body, der an einen Chat-Pfad gesendet wurde | Bestätigen Sie die ID in GET /v1/models?type=video, dass Sie an /v1/videos/generations gesendet haben und dass 1.5-Jobs einen passenden video_generation_mode setzen |
401 | Fehlender oder ungültiger API-Schlüssel | Verwenden Sie einen ToAPIs Schlüssel, keinen OpenAI-Plattformschlüssel, und bestätigen Sie den Bearer-Header |
404 | Falscher Ursprung, fehlendes /v1 oder ein erfundener Pfad wie /videos/tasks/{id} | Wechseln Sie zu GET /v1/videos/generations/{id} auf dem Ursprung, mit dem Sie gesendet haben |
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: failed | Generierung nicht erfolgreich | Lesen Sie error.code und error.message. Wiederholen Sie keinen unveränderten, durch Policy abgelehnten Payload |
5. Preise und FinOps-ROI
- Kompatibilität ändert die abrechenbare SKU nicht. Abgerechnet wird die Katalog-Modell-ID, die Sie senden (
grok-video-1.5odergrok-video-1.0), nicht die „Nutzung des OpenAI SDK“. - Verwenden Sie keine Stückpreise aus Planungsentwürfen erneut. Die Grok Video 1.5 Referenz garantiert keinen festen Preis pro Sekunde. Offizielle Anbieter-Referenzzeilen auf der ToAPIs Preisseite dienen nur der Anzeige und können von der Kontoabrechnung abweichen.
- Eine fehlgeschlagene Discovery ist günstig; eine doppelte Generierung nicht. Cachen Sie die Modellliste kurz, prüfen Sie aber nach einer clientseitigen Zeitüberschreitung immer den Task-Status, bevor Sie einen weiteren Job anlegen.
- 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: eine kompatible Basis-URL schaltet grok-video-3 nicht frei; /v1 genau einmal angeben; GET /v1/videos/generations/{id} abfragen; keine SDK-Hilfsfunktion videos.create annehmen; Chat-Abschlüsse liefern kein MP4.
7. Aktionscheckliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Richten Sie Ihren Client auf
https://api.toapis.com/v1(oderhttps://toapis.cn/v1in Festlandchina) mitAuthorization: Bearer. - Rufen Sie
GET /v1/models?type=videoauf und notieren Sie die exakten Grok Video IDs, die Ihr Schlüssel sieht. - Testen Sie kurz
POST /v1/videos/generationsmitgrok-video-1.5undvideo_generation_mode: "text_to_video"und fragen Sie dann dieselbe ID ab. - Nächster Schritt: der Praxis-Guide zu Grok Video für Details zu Modus und Bildfeldern und der Grok Video 1.5 Modell-Leitfaden für den Live-Status im Katalog.







