Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

xAI SDK und automatische Abfrage

Lektion 11 von 12 Aktualisiert am 2. November 2026 Mittelstufe
Auf dieser Seite
  1. Vereinfachung der Abfrage durch den SDK
  2. Ein einziger Aufruf statt eines Loops
  3. Fehlerbehandlung an der Quelle
  4. Bearbeiten und Erweiterung, gleiche Einfachheit
  5. Lassen Sie ein Video niemals in der Cloud
  6. Generieren Sie mehrere Videos gleichzeitig
  7. Sollten Sie manuelle Abfragen aufgeben?
  8. Kernaussagen

Aktualisiert am 2. November 2026 basierend auf der xAI-Video-Dokumentation und dem xai-sdk 1.21.0-Code: Die Methoden heißen client.video.generate und client.video.extend (das Bearbeiten nutzt generate mit video_url), das Ergebnis gibt url aus, die Verzögerung wird über ein timedelta-Objekt festgelegt, und das Standard-Abfrageintervall beträgt eine Sekunde. await erfordert den asynchronen Client AsyncClient, und die VideoGenerationError-Ausnahme wird aus xai_sdk.video importiert. Die alte Version verwendete Methoden und eine Ausnahmemodul, die nicht existieren. Quellen: Video-Generierung · Video-Bearbeitung · Video-Erweiterung · xai-sdk-python.

Vereinfachung der Abfrage durch den SDK

Die vorherige Lektion hat Sie aufgefordert, einen Abfrage-Loop manuell zu schreiben. Es ist eine nützliche Übung, um den Generierungslebenszyklus zu verstehen, aber es sind auch dreißig Zeilen Code, die in jedem Projekt gewartet werden müssen, inklusive eigener Timeout-Handling, Fehlerfälle und Statuskonvertierungen. Das offizielle Python-SDK von xAI (pip install xai-sdk) kapselt dies alles ein: Sie übermitteln die Anfrage, und das SDK übernimmt das Warten.

Ein einziger Aufruf statt eines Loops

Die Methode client.video.generate bündelt die Einreichung, das Tracking und die Abrufung. Sie gibt die Kontrolle erst zurück, sobald das Video bereit ist, oder wirft eine Ausnahme, wenn etwas schiefgeht.

import os

import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Text-zu-Video-Generierung mit automatischer Abfrage
video = client.video.generate(
    prompt="Ein Sonnenaufgang über den Alpen, beschleunigte Zeitrafferaufnahme",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Dauer: {video.duration} s, Modell: {video.model}")

Hinter diesen wenigen Zeilen tut das SDK genau das, was Sie zuvor kodiert haben: Es übermittelt die Anfrage, fragt den Status standardmäßig jede Sekunde ab und gibt dann das Ergebnis zurück oder wirft eine Ausnahme, je nach Ausgangslage.

Eine Einstellung verdient Ihre Aufmerksamkeit bereits bei der Bereitstellung: Standardmäßig wartet das SDK bis zu 10 Minuten, bevor es aufgibt. Das ist für ein nächtliches Produktions-Skript komfortabel, aber für eine Webanfrage, bei der ein Benutzer auf eine Antwort wartet, viel zu lang. Die Parameter timeout und interval, beide timedelta-Objekte, setzen die Obergrenze und den Rhythmus:

from datetime import timedelta

video = client.video.generate(
    prompt="Ihre Beschreibung",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # Maximal 5 Minuten
    interval=timedelta(seconds=5),  # Eine Prüfung alle 5 Sekunden
)

Wenn Sie die Kontrolle über das Warten behalten möchten – beispielsweise um den Fortschritt weiterzuleiten – übermittelt client.video.start die Anfrage und gibt deren request_id zurück, die client.video.get dann abfragt.

Fehlerbehandlung an der Quelle

Das SDK unterscheidet Fehler, was Sie davor bewahrt, Zeichenfolgen analysieren zu müssen, um herauszufinden, was passiert ist:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Ihre Beschreibung",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video bereit: {video.url}")
except VideoGenerationError as e:
    print(f"Generierung fehlgeschlagen [{e.code}]: {e.message}")
except TimeoutError:
    print("Timeout überschritten: Erhöhen Sie den Timeout oder vereinfachen Sie die Anfrage")

Jeder Fehler erfordert eine andere Reaktion, und Verwechslungen führen zu nutzlosen Wiederholungsloops oder, schlimmer noch, zu abgerechneten Generierungen, die nichts ergeben.

FehlerUrsacheEmpfohlene Maßnahme
VideoGenerationErrorVon der API signalisierter Fehler: Prompt abgelehnt, ungültige Quelle, Dienst überlastet… (code, message)Lesen Sie den Code: Korrigieren Sie die Anfrage oder wiederholen Sie sie später, wenn der Dienst nicht verfügbar war
TimeoutErrorClient-seitige Wartezeit überschrittenErhöhen Sie den timeout oder reduzieren Sie die Dauer
RuntimeErrorVerzögerte Anfrage abgelaufen oder ohne Ergebnis abgeschlossenStarten Sie die Generierung neu
grpc.RpcErrorSDK-Transportfehler, einschließlich Rate Limits (Code RESOURCE_EXHAUSTED) und SchlüsselproblemeVerteilen Sie Anfragen mit Backoff oder überprüfen Sie den Schlüssel

Das SDK verwendet gRPC: Ein überschrittener Rate-Limit erscheint hier nicht als HTTP-Code 429, sondern als grpc.RpcError mit dem Code RESOURCE_EXHAUSTED.

Bearbeiten und Erweiterung, gleiche Einfachheit

Das Bearbeiten verfügt über keine dedizierte Methode: Es ist generate mit einer Quell-Video, übergeben als video_url (Video bis zu 8,7 Sekunden, gleiche Dauer der Ausgabe, maximal 720p).

video = client.video.generate(
    prompt="Transformieren Sie die Szene in japanischen Anime-Stil",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Die Erweiterung verlängert eine Sequenz von 2 bis 15 Sekunden um einen Abschnitt von 2 bis 10 Sekunden und gibt das vollständige Video zurück:

video = client.video.extend(
    prompt="Setzen Sie die Szene fort mit einer Kamerafahrt nach rechts",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Beachten Sie den Unterschied zur REST-API: Das SDK nimmt das Video als Parameter video_url, wohingegen der JSON-Körper ein video-Objekt mit seiner url-Eigenschaft erwartet.

Lassen Sie ein Video niemals in der Cloud

Das SDK ändert nichts an der vorübergehenden Natur der Ergebnis-URLs. Wenn Ihr Code nur video.url anzeigt, haben Sie eine Generierung bezahlt, die bald verschwunden sein wird. Die beste Praxis ist, Generierung und Download in derselben Funktion zu verketten, sodass der Schritt unmöglich zu vergessen ist.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Generiert ein Video und speichert es lokal (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Sofortiger Download
    async with httpx.AsyncClient() as http:
        response = await http.get(video.url)
        response.raise_for_status()
        Path(output_file).write_bytes(response.content)

    print(f"Video gespeichert: {output_file}")
    return output_file

Für die Speicherung ohne Transit durch Ihren Server legt der Generierungs-Parameter storage_options das Video in der xAI Files API ab, mit einer von Ihnen wählbaren Ablaufzeit.

Generieren Sie mehrere Videos gleichzeitig

Mit dem asynchronen Client ist jeder Aufruf ein Coroutine, und asyncio.gather startet einen gesamten Batch parallel. Die Option return_exceptions=True ist hier entscheidend: Ohne sie würde eine einzelne abgelehnte Anfrage den gesamten Batch versagen lassen, und Sie würden die bereits erhaltenen Ergebnisse verlieren.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generiert mehrere Videos parallel."""
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
    tasks = [
        client.video.generate(
            prompt=req["prompt"],
            model="grok-imagine-video-1.5",
            duration=req.get("duration", 5),
            aspect_ratio=req.get("aspect_ratio", "16:9"),
        )
        for req in requests
    ]

    results = await asyncio.gather(*tasks, return_exceptions=True)

    for i, res in enumerate(results, 1):
        if isinstance(res, Exception):
            print(f"Anfrage {i} fehlgeschlagen: {res}")
        else:
            print(f"Anfrage {i} abgeschlossen: {res.url}")

    return results

Zwei Sicherheitsvorkehrungen rahmen diese Parallelisierung ein. Einreichungen verbrauchen Ihren Rate-Limit, gezählt in Anfragen pro Sekunde gemäß dem Tarif Ihres Teams (10 beim Einstiegs-Tarif für Videomodelle): Für einen großen Batch begrenzen Sie die Parallelität mit einem asyncio.Semaphore. Denken Sie auch daran, was Parallelisierung tut und was nicht: Sie beschleunigt keine einzelne Generierung, sie reduziert nur die Gesamtzeit des Batches.

Sollten Sie manuelle Abfragen aufgeben?

Nicht systematisch. Der folgende Vergleich zeigt, wo jeder Ansatz die Führung übernimmt.

AspektManuelle AbfrageSDK
KomplexitätHochNiedrig
FehlerbehandlungZu implementierenIntegriert
TimeoutZu implementieren10 Minuten Standard, konfigurierbar
AbfrageintervallZu wählen1 Sekunde Standard, konfigurierbar
FlexibilitätTotalStandard (oder start und get)
AbhängigkeitKeinexAI SDK

Manuelle Abfrage behält ihre Relevanz in zwei Situationen: Wenn Sie eine feine Kontrolle benötigen, beispielsweise um den Fortschritt an eine Echtzeit-Oberfläche weiterzuleiten oder sie in ein bestehendes Warteschlangensystem zu integrieren, und wenn Ihr Bereitstellungs-Kontext das Hinzufügen einer zusätzlichen Abhängigkeit verbietet.

Kernaussagen

  • client.video.generate übermittelt, wartet und gibt das Video zurück (url, duration, model); 10-Minuten-Timeout und eine-Sekunden-Prüfung standardmäßig
  • Bearbeiten nutzt generate mit video_url, Erweiterung nutzt client.video.extend
  • VideoGenerationError (aus xai_sdk.video), TimeoutError und RuntimeError unterscheiden Fehler; Rate Limits kommen als grpc.RpcError
  • Laden Sie das Video sofort nach der Generierung herunter (vorübergehende URLs)
  • Der asynchrone Client und asyncio.gather parallelisieren einen Batch, innerhalb des Rate-Limits Ihres Tarifs