Asynchroner Workflow und Abfrage
Auf dieser Seite
Aktualisiert am 2. November 2026. Basierend auf der xAI Video-API-Referenz: Die URL befindet sich in
video.url(nichtvideo_url), eine Generierung verfügt über genau drei Zustände (pending,done,failed, wobei der letzte von einem Fehlercode begleitet wird), und Rate Limits werden in Anfragen pro Sekunde basierend auf dem Team-Tier ausgedrückt. Quellen: Video-Generierung · Videos-Referenz · Rate Limits.
Das Video-Lebenszyklus verstehen
Alle Video-Operationen in der xAI-API sind asynchron, und dieses Merkmal prägt Ihre Anwendungsarchitektur mehr, als Sie zunächst erwarten mögen. Ein Chat-Aufruf oder eine Bildgenerierung liefert ein Ergebnis sofort; die Video-Generierung hingegen benötigt erhebliche Verarbeitungszeit und liefert lediglich eine Bestätigung zurück. Es liegt an Ihnen, die Verfolgung zu implementieren: Abfragen Sie den Aufgabenstatus in regelmäßigen Abständen, erkennen Sie den Abschluss und laden Sie die Datei herunter. Der vollständige Zyklus besteht aus vier Schritten.
Anfrage einreichen
POST an den Endpunkt für Generierung, Bearbeitung oder Erweiterung. Sofortige Antwort mit einer request_id.
Status abfragen
GET /v1/videos/{request_id} in regelmäßigen Abständen. progress-Feld von 0 bis 100.
Ergebnis abrufen
Wenn der Status `done` ist (progress = 100), ist die Video-URL verfügbar.
Sofort herunterladen
Die Video-URL ist temporär. Laden Sie sie so schnell wie möglich herunter.
Generierungsstatus prüfen
Die Verfolgung umfasst eine einfache GET-Anfrage an den Status-Endpunkt unter Verwendung des Identifikators, der bei der Einreichung erhalten wurde.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Die Antwort stellt folgende nützliche Informationen bereit:
- status : der aktuelle Generierungszustand
- progress : eine ganze Zahl von 0 bis 100, die den Fortschritt angibt
- video.url : die Video-URL, innerhalb des
video-Objekts, das vorhanden ist, wenn der Statusdoneist, zusammen mit seiner Dauer (video.duration) - video.respect_moderation : ein Boolean, das angibt, ob der Inhalt den Moderationsrichtlinien entspricht
- error : im Falle eines Fehlers ein Code (
invalid_argument,permission_denied,failed_precondition,service_unavailableoderinternal_error) und eine Nachricht - usage.cost_in_usd_ticks : die Kosten der Anfrage, in Zehntel-Milliarden Dollar
Das progress-Feld verdient eine Anmerkung: Es steuert nicht Ihre Steuerungslogik, die sich immer auf status verlassen sollte, aber es ist Gold wert für eine Benutzeroberfläche. Die Anzeige von “62%” statt eines statischen Spinners verändert die Wahrnehmung einer Wartezeit, die mehrere Minuten dauern kann, vollständig.
Drei Zustände, drei Aktionen
| Status | Progress | Bedeutung |
|---|---|---|
pending | 0-99 | Generierung läuft |
done | 100 | Abgeschlossen, URL verfügbar |
failed | fehlt | Generierung fehlgeschlagen |
Solange der Status pending ist, läuft die Generierung weiter: Sie müssen lediglich in regelmäßigen Abständen abfragen und den progress an Ihre Oberfläche weiterleiten. Wenn er sich auf done ändert, ist das Video bereit, und das Einzige, was zu tun ist, ist das Lesen von video.url und das sofortige Herunterladen der Datei – diese URLs sind temporär, und die Dokumentation gibt ihre Lebensdauer nicht an, was das Speichern in einer Datenbank für einen späteren Gebrauch untersagt.
Schließlich zeigt der failed-Status einen Produktionsfehler an, und das error-Feld sagt Ihnen, welcher es ist. Die Unterscheidung ist für das Folgende wichtig: service_unavailable (Dienst vorübergehend überlastet) oder internal_error rechtfertigen einen späteren Neustart, während invalid_argument oder permission_denied – abgelehnter Prompt, ungültige Quellbild- oder Videodatei – eine Korrektur der Anfrage erfordern. Der Python-SDK signalisiert seinerseits ebenfalls über einen Fehler eine verzögerte Anfrage, die abgelaufen ist, bevor sie abgerufen wurde.
Abfrage implementieren
Die synchrone Version passt in eine einzelne Funktion. Sie läuft bis zum Timeout, bricht bei einem Fehler frühzeitig ab, indem sie den entsprechenden Code wirft, und gibt die URL zurück, sobald das Video bereit ist.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Warten auf Abschluss der Video-Generierung."""
headers = {"Authorization": f"Bearer {api_key}"}
debut = time.time()
while time.time() - debut < timeout:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
status = resp.get("status")
progress = resp.get("progress", 0)
if status == "done":
return resp["video"]["url"]
elif status == "failed":
erreur = resp.get("error", {})
raise RuntimeError(f"Generierung fehlgeschlagen [{erreur.get('code')}] : {erreur.get('message')}")
print(f"In Fortschritt... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout nach {timeout} Sekunden")
In einem Dienst, der mehrere Anfragen gleichzeitig verarbeitet, wird diese blockierende Version zum Flaschenhals: Jedes Warten immobilisiert einen Thread für Minuten. Die asynchrone Umsetzung setzt den Event-Loop zwischen den Abfragen frei und ermöglicht es Ihnen, Dutzende Generierungen parallel zu verfolgen.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asynchrone Version der Abfrage."""
headers = {"Authorization": f"Bearer {api_key}"}
async with httpx.AsyncClient() as client:
debut = asyncio.get_event_loop().time()
while asyncio.get_event_loop().time() - debut < timeout:
resp = await client.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
)
data = resp.json()
if data["status"] == "done":
return data["video"]["url"]
elif data["status"] == "failed":
raise RuntimeError(f"Generierung fehlgeschlagen : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Das Abfrage-Intervall festlegen
Die Wahl des Intervalls balanciert Reaktionsfähigkeit gegen verschwendete Anfragen. Fünf Sekunden sind in den meisten Fällen ein guter Kompromiss. Für lange Generierungen – zehn bis fünfzehn Sekunden Video – sind zehn bis fünfzehn Sekunden zwischen Abfragen ausreichend und reduzieren den Datenverkehr. Umgekehrt rechtfertigt eine interaktive Anwendung, in der der Nutzer einen Fortschrittsbalken beobachtet, das Absenken auf zwei oder drei Sekunden. Unter einer Sekunde werden Sie jedoch nichts beschleunigen: Die Generierung verläuft in ihrem eigenen Tempo, und Sie multiplizieren lediglich Anfragen ohne Nutzen.
Kernaussagen
- Alle Video-Operationen sind asynchron: POST zum Einreichen, GET zum Abrufen
- Drei mögliche Zustände: pending, done, failed (mit einem Fehlercode)
- Das
progress-Feld (0-100) ermöglicht die Verfolgung des Fortschritts - Implementieren Sie ein Timeout und ein Abfrage-Intervall, das Ihrem Anwendungsfall entspricht
- Video-URLs sind temporär: Laden Sie sie sofort herunter