Fehlerbehandlung und Produktionsbereitstellung
Auf dieser Seite
Aktualisiert am 2. November 2026 basierend auf der xAI-Video-Dokumentation und dem
xai-sdk1.21.0-Code:client.video.generate(nichtclient.videos), Ergebnis inurl, Fehler werden durchVideoGenerationErrorgemeldet mit einem Code (invalid_argument,service_unavailable…), Rate Limits werden alsgrpc.RpcErrormit dem CodeRESOURCE_EXHAUSTEDempfangen — die KlassenRateLimitErrorund der Statusexpiredexistieren nicht. Ergänzung vom 3. November 2026: Rate Limits zählen Anfragen pro Sekunde (10 im Einstiegs-Tarif), nicht „60 RPM”, und die tatsächliche Kosten pro Generierung werden aususage.cost_in_usd_ticksgelesen. Quellen: Video-Generierung · Rate Limits.
Ihre Anwendung auf die Produktion vorbereiten
Ein Skript, das auf Ihrem lokalen Rechner ein Video generiert, und ein Dienst, der täglich hunderte Videos für echte Nutzer erstellt, haben fast nichts gemeinsam. Letzterer muss Moderationsablehnungen, Kontingentüberschreitungen, Servervorfälle und ablaufende URLs bewältigen, ohne jemals eine abgerechnete Generierung stillschweigend zu verlieren. Diese Lektion behandelt die Mechanismen, die den Unterschied ausmachen: Fehlerklassifizierung, Retry-Strategie, Warteschlangenarchitektur und Observability.
Zwei Familien von Fehlern, zwei Zeitpunkte
Die erste Familie tritt sofort auf, zum Zeitpunkt des POST-Aufrufs. Dies sind strenge Anforderungsfehler, und der HTTP-Code reicht aus, um zu entscheiden, was zu tun ist.
| HTTP-Code | Ursache | Lösung |
|---|---|---|
| 400 | Ungültige Parameter (z. B. eine unbekannte Stimme in reference_audios) | Anforderung korrigieren |
| 401 | Ungültiger oder abgelaufener API-Schlüssel | Authentifizierung überprüfen |
| 429 | Rate Limit überschritten (Anfragen pro Sekunde, abhängig vom Tarif) | Backoff implementieren |
| 500 | Serverfehler | Mit exponentiellem Backoff wiederholen |
Die zweite Familie manifestiert sich viel später, während des Abfrage-Polls, nachdem die Anfrage akzeptiert und die Generierung gestartet wurde.
| Status | Wahrscheinliche Ursache | Aktion |
|---|---|---|
failed + invalid_argument oder permission_denied | Anfrage oder Inhalt abgelehnt | Prompt oder Quelle ändern |
failed + service_unavailable oder internal_error | Dienst überlastet, Vorfall | Später wiederholen |
Diese Unterscheidung ist nicht akademisch: Ein 400-Code muss sofort an den Aufrufer zurückgegeben werden, da der Code schuld ist, während ein failed-Status nach mehreren Minuten Wartezeit auftritt und im Kontext des Jobs, nicht in der HTTP-Anfrage, die ihn ausgelöst hat, behandelt werden muss.
Intelligent wiederholen
Die gemeinsame Basis ist exponentieller Backoff mit etwas Jitter. Das Verdoppeln der Verzögerung gibt einem vorübergehenden Vorfall Zeit zur Lösung, und Jitter verhindert, dass alle Ihre Prozesse nach einem Anstieg gleichzeitig wiederholen – ein Phänomen, das einen Mikro-Ausfall in einen dauerhaften Fehler verwandelt.
import asyncio
import random
async def call_with_retry(func, max_retries=3, base_delay=2):
"""Führt eine Funktion mit Retry und exponentiellem Backoff aus."""
for attempt in range(max_retries + 1):
try:
return await func()
except Exception as e:
if attempt == max_retries:
raise
# Exponentieller Backoff mit Jitter
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Versuch {attempt + 1} fehlgeschlagen: {e}. Wiederholung in {delay:.1f}s")
await asyncio.sleep(delay)
Dieses generische Schema reicht jedoch nicht aus, da nicht alle Fehler dieselbe Geduld verdienen. Eine Kontingentüberschreitung wird gelöst, indem man eine volle Minute wartet; eine Moderationsablehnung wird niemals gelöst, und ein Wiederholen entspricht dem mehrfachen Bezahlen für denselben Fehler. Die folgende Funktion unterscheidet die Fälle.
import asyncio
from datetime import timedelta
import grpc
from xai_sdk.video import VideoGenerationError
# Fehlercodes, die ein Retry nicht beheben kann
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}
async def generate_with_retry(client, params, max_retries=3):
"""Video-Generierung mit gezieltem Retry (client: xai_sdk.AsyncClient)."""
for attempt in range(max_retries + 1):
is_last = attempt == max_retries
try:
return await client.video.generate(**params)
except VideoGenerationError as e:
if e.code.lower() in REQUIRES_FIX or is_last:
raise # Anfrage oder Inhalt abgelehnt: vor Neustart korrigieren
await asyncio.sleep(5 * (attempt + 1)) # Dienst überlastet, Vorfall
except grpc.RpcError as e:
if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
raise
await asyncio.sleep(2 ** attempt) # Rate Limit: Backoff
except TimeoutError:
if is_last:
raise
# Mehr Zeit für den nächsten Versuch erlauben
params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)
Eine Warteschlange, um den Takt zu halten
Sobald Ihr Dienst Anfragen von mehreren Nutzern empfängt, müssen Sie die Anfrageannahme von der Ausführung entkoppeln und vor allem die Konfidenz begrenzen, um unter dem Rate Limit Ihres Tarifs zu bleiben. Eine Warteschlange gepaart mit einem Semaphore erfüllt beide Bedürfnisse: Jobs stapeln sich frei, aber maximal zehn werden gleichzeitig ausgeführt.
import asyncio
from collections import deque
class VideoGenerationQueue:
def __init__(self, client, max_concurrent=10):
self.client = client
self.queue = deque()
self.semaphore = asyncio.Semaphore(max_concurrent)
self.results = {}
async def add(self, job_id, params):
"""Fügt eine Generierung der Warteschlange hinzu."""
self.queue.append((job_id, params))
async def process(self):
"""Verarbeitet alle ausstehenden Generierungen."""
tasks = []
while self.queue:
job_id, params = self.queue.popleft()
task = asyncio.create_task(
self._execute(job_id, params)
)
tasks.append(task)
await asyncio.gather(*tasks, return_exceptions=True)
async def _execute(self, job_id, params):
"""Führt eine Generierung mit Konfidenzkontrolle aus."""
async with self.semaphore:
try:
result = await generate_with_retry(
self.client, params
)
self.results[job_id] = {
"status": "done",
"url": result.url
}
except Exception as e:
self.results[job_id] = {
"status": "failed",
"error": str(e)
}
Beachten Sie, dass jeder Job sein Ergebnis in results behält, Erfolg oder Misserfolg: Eine Generierung, die spurlos verschwindet, ist ein Vorfall, den niemand diagnostizieren kann.
Die zweite architektonische Reflexion betrifft die Speicherung. Da Video-URLs temporär sind, muss das Herunterladen automatisch und sofort erfolgen, mit einer zeitgestempelten Benennung, die keine Kollision zwischen zwei gleichzeitigen Generierungen garantiert.
import httpx
from pathlib import Path
from datetime import datetime
async def save_video(video_url, output_dir="./videos"):
"""Lädt ein generiertes Video herunter und speichert es."""
Path(output_dir).mkdir(parents=True, exist_ok=True)
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
file_path = f"{output_dir}/video_{timestamp}.mp4"
async with httpx.AsyncClient() as client:
resp = await client.get(video_url)
resp.raise_for_status()
Path(file_path).write_bytes(resp.content)
return file_path
Ihren Schlüssel überprüfen, bevor Sie darauf vertrauen
Der Endpunkt GET /v1/api-key informiert Sie über den Zustand Ihres Schlüssels. Der Aufruf beim Dienst-Start vermeidet es, einen blockierten Schlüssel erst nach zwanzig fehlgeschlagenen Anfragen zu entdecken, während Ihre Nutzer warten.
resp = httpx.get(
"https://api.x.ai/v1/api-key",
headers={"Authorization": f"Bearer {api_key}"}
).json()
if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
raise RuntimeError("API-Schlüssel oder Team blockiert, oder Schlüssel deaktiviert")
Beobachten, was in der Produktion passiert
Fünf Indikatoren reichen aus, um einen Video-Generierungsdienst zu steuern. Die Erfolgsquote, also der Anteil der Generierungen, die mit done enden, misst den allgemeinen Gesundheitszustand. Die durchschnittliche Generierungszeit, gemessen zwischen Einreichung und done-Status, dient zur Kalibrierung Ihrer Timeouts und informiert Ihre Nutzer. Die Fehlerrate, aufgeteilt nach Typ – failed nach Fehlercode, Timeout, Rate Limit – zeigt, wo Sie Ihre Anstrengungen konzentrieren sollten: Ein Anstieg von Timeouts ohne Anstieg von failed signalisiert beispielsweise, dass Generierungen langsamer sind als Ihre Warte-Frist, nicht dass sie gescheitert sind. Die kumulierte Kosten, ermittelt durch die Summierung des Feldes usage.cost_in_usd_ticks aus jedem Ergebnis (ein Dollar entspricht 10 Milliarden Ticks), oder alternativ durch Multiplikation der generierten Dauern mit dem Preis des Modells pro Sekunde, muss täglich überwacht werden. Schließlich die Kontingentnutzung, in Anfragen pro Sekunde relativ zu Ihrem Tariflimit (10 im Einstiegs-Tarif für Videomodelle), antizipiert die Sättigung, bevor sie sich in 429s übersetzt.
Diese Metriken entstehen natürlich aus einem strukturierten Log, in dem jede Generierung eine Zeile hinterlässt, die von Ihrem Analyse-Tool genutzt werden kann.
import logging
import json
logger = logging.getLogger("video-generation")
def log_generation(request_id, status, duration_s, cost, time_ms):
logger.info(json.dumps({
"event": "video_generation",
"request_id": request_id,
"status": status,
"duration_seconds": duration_s,
"cost_usd": cost,
"processing_time_ms": time_ms
}))
Bevor Sie Ihren Dienst für die Öffentlichkeit öffnen, überprüfen Sie das Ganze von Anfang an. Retry mit exponentiellem Backoff und Jitter muss vorhanden sein, und die Konfidenz muss durch ein Semaphore begrenzt werden, um unter dem Rate Limit zu bleiben. Video-Downloads müssen automatisch ausgelöst werden, sobald sie bereit sind, ohne auf menschliches Handeln angewiesen zu sein. Jede Generierung muss eine Logzeile hinterlassen, die ihre request_id, ihren Status und ihre Kosten trägt, sonst bleiben die Fehlerrate und die durchschnittliche Generierungszeit unverifizierbar. Überprüfen Sie den Zustand des API-Schlüssels beim Start, nicht beim ersten Fehler. Und legen Sie ein Budget mit Warnungen bei Überschreitung fest: Bei 0,05 USD pro Sekunde verbraucht ein unbegrenzter Retry-Loop schneller, als Sie denken.
Preise am 3. November 2026 verifiziert — Preise entwickeln sich regelmäßig: Bevor Sie eine Budgetberechnung durchführen, überprüfen Sie das aktuelle Raster auf der offiziellen xAI-Modell- und Preis-Seite.
Kernaussagen
- Fehler teilen sich in synchron (Anfrage) und asynchron (Generierung)
- Nicht alle Fehler verdienen ein Retry: Moderation ist endgültig
- Verwenden Sie ein Semaphore, um gleichzeitige Generierungen zu begrenzen
- Temporäre URLs erfordern sofortiges und systematisches Herunterladen
- Verfolgen Sie Kosten-, Erfolgs- und Generierungszeit-Metriken, um Ihren Dienst zu steuern
Wissen testen
Generative Videos in der Produktion: Validieren Sie den gesamten Workflow.
1. Was sind die Besonderheiten eines Video-Prompts?
Antwort: Beschreiben Sie die Aktion und Bewegung, nicht nur die Szene: Subjekt, Verschiebung, Atmosphäre, Bildrahmen – die zeitliche Dimension ist es, was den Video-Prompt vom Bild-Prompt unterscheidet.
2. Was ermöglicht Bild-zu-Video?
Antwort: Animieren Sie ein bestehendes Bild oder bringen Sie gegebene Personen und Produkte in eine neue Szene mit Referenzbildern – und auf grok-imagine-video-1.5 können Sie die ersten, letzten oder Schlüsselschnappschüsse festlegen: Ihre visuelle Identität wird zum Ausgangspunkt, nicht zum Zufall.
3. Bearbeitung und Erweiterung: Welche Anwendungen?
Antwort: /videos/edits modifiziert ein generiertes Video, /videos/extensions verlängert es – und beide kombinieren sich, um lange Sequenzen durch Iterationen zu erstellen.
4. Warum ist der Workflow asynchron?
Antwort: Video-Generierung braucht Zeit: Sie reichen einen Job ein, fragen seinen Status ab und holen dann das Ergebnis ab – das xAI SDK automatisiert diesen Polling-Prozess.
5. Was ist für die Produktion zu planen?
Antwort: Fehlerbehandlung und fehlgeschlagene Jobs, sofortiges Herunterladen der Ausgaben und Kostenverfolgung (Auflösung, Dauer, Iterationen) – Video ist die teuerste Modalität: Es muss budgetiert werden.
Temporaler Prompt, visuelle Referenz, beherrschter Asynchron: Generative Videos werden zu einer Pipeline – nicht zum Glücksspiel.