Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Fehlerbehandlung und Produktionsbereitstellung

Lektion 12 von 12 Aktualisiert am 3. November 2026 Mittelstufe
Auf dieser Seite
  1. Ihre Anwendung auf die Produktion vorbereiten
  2. Zwei Familien von Fehlern, zwei Zeitpunkte
  3. Intelligent wiederholen
  4. Eine Warteschlange, um den Takt zu halten
  5. Ihren Schlüssel überprüfen, bevor Sie darauf vertrauen
  6. Beobachten, was in der Produktion passiert
  7. Kernaussagen
  8. Wissen testen

Aktualisiert am 2. November 2026 basierend auf der xAI-Video-Dokumentation und dem xai-sdk 1.21.0-Code: client.video.generate (nicht client.videos), Ergebnis in url, Fehler werden durch VideoGenerationError gemeldet mit einem Code (invalid_argument, service_unavailable…), Rate Limits werden als grpc.RpcError mit dem Code RESOURCE_EXHAUSTED empfangen — die Klassen RateLimitError und der Status expired existieren 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 aus usage.cost_in_usd_ticks gelesen. 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-CodeUrsacheLösung
400Ungültige Parameter (z. B. eine unbekannte Stimme in reference_audios)Anforderung korrigieren
401Ungültiger oder abgelaufener API-SchlüsselAuthentifizierung überprüfen
429Rate Limit überschritten (Anfragen pro Sekunde, abhängig vom Tarif)Backoff implementieren
500ServerfehlerMit 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.

StatusWahrscheinliche UrsacheAktion
failed + invalid_argument oder permission_deniedAnfrage oder Inhalt abgelehntPrompt oder Quelle ändern
failed + service_unavailable oder internal_errorDienst überlastet, VorfallSpä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.