xAI SDK und automatische Abfrage
Auf dieser Seite
Aktualisiert am 2. November 2026 basierend auf der xAI-Video-Dokumentation und dem
xai-sdk1.21.0-Code: Die Methoden heißenclient.video.generateundclient.video.extend(das Bearbeiten nutztgeneratemitvideo_url), das Ergebnis gibturlaus, die Verzögerung wird über eintimedelta-Objekt festgelegt, und das Standard-Abfrageintervall beträgt eine Sekunde.awaiterfordert den asynchronen ClientAsyncClient, und dieVideoGenerationError-Ausnahme wird ausxai_sdk.videoimportiert. 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.
| Fehler | Ursache | Empfohlene Maßnahme |
|---|---|---|
VideoGenerationError | Von 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 |
TimeoutError | Client-seitige Wartezeit überschritten | Erhöhen Sie den timeout oder reduzieren Sie die Dauer |
RuntimeError | Verzögerte Anfrage abgelaufen oder ohne Ergebnis abgeschlossen | Starten Sie die Generierung neu |
grpc.RpcError | SDK-Transportfehler, einschließlich Rate Limits (Code RESOURCE_EXHAUSTED) und Schlüsselprobleme | Verteilen 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.
| Aspekt | Manuelle Abfrage | SDK |
|---|---|---|
| Komplexität | Hoch | Niedrig |
| Fehlerbehandlung | Zu implementieren | Integriert |
| Timeout | Zu implementieren | 10 Minuten Standard, konfigurierbar |
| Abfrageintervall | Zu wählen | 1 Sekunde Standard, konfigurierbar |
| Flexibilität | Total | Standard (oder start und get) |
| Abhängigkeit | Keine | xAI 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
generatemitvideo_url, Erweiterung nutztclient.video.extend VideoGenerationError(ausxai_sdk.video),TimeoutErrorundRuntimeErrorunterscheiden Fehler; Rate Limits kommen alsgrpc.RpcError- Laden Sie das Video sofort nach der Generierung herunter (vorübergehende URLs)
- Der asynchrone Client und
asyncio.gatherparallelisieren einen Batch, innerhalb des Rate-Limits Ihres Tarifs