xAI SDK en automatische polling
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van de xAI-videodocumentatie en de code van
xai-sdk1.21.0: de methoden hetenclient.video.generateenclient.video.extend(bewerken gebruiktgeneratemetvideo_url), het resultaat exposeerturl, de vertraging wordt ingesteld via eentimedeltaen het standaard polling-interval is één seconde.awaitvereist de asynchrone clientAsyncClienten de uitzonderingVideoGenerationErrorwordt geïmporteerd vanuitxai_sdk.video. De oude versie riep methoden en een uitzonderingsmodule aan die niet bestaan. Bronnen: Video Generation · Video Editing · Video Extension · xai-sdk-python.
Vereenvoudig polling met de SDK
In de vorige les schreef u handmatig een polling-lus. Het is een nuttige oefening om de levenscyclus van generatie te begrijpen, maar het zijn ook dertig regels code die u in elk project moet onderhouden, met eigen time-outbehandeling, foutgevallen en statusconversies. De officiële Python-SDK van xAI (pip install xai-sdk) kapselt dit allemaal in: u dient het verzoek in en de SDK regelt het wachten.
Eén aanroep in plaats van een lus
De methode client.video.generate groepeert indiening, tracking en ophalen. Deze geeft de controle pas terug wanneer de video klaar is, of werpt een uitzondering als er iets mis is gegaan.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Tekst-naar-video generatie met automatische polling
video = client.video.generate(
prompt="Een zonsopgang boven de Alpen, versnelde time-lapse",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Duur: {video.duration} s, model: {video.model}")
Achter deze paar regels doet de SDK precies wat u eerder codeerde: het verzoek indienen, standaard elke seconde de status controleren, en vervolgens het resultaat retourneren of een uitzondering genereren afhankelijk van de uitkomst.
Eén instelling verdient direct bij implementatie uw aandacht: standaard wacht de SDK maximaal 10 minuten voordat deze het opgeeft. Dat is comfortabel voor een nachtelijk productiescript, maar veel te lang voor een webverzoek waarbij een gebruiker wacht op een antwoord. De parameters timeout en interval, beide timedelta-objecten, stellen de limiet en het ritme in:
from datetime import timedelta
video = client.video.generate(
prompt="Uw beschrijving",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # Maximaal 5 minuten
interval=timedelta(seconds=5), # Eén check elke 5 seconden
)
Als u de controle over het wachten wilt behouden – om bijvoorbeeld voortgang door te geven – dan dient client.video.start het verzoek in en retourneert het de request_id, die vervolgens door client.video.get wordt bevraagd.
Fouten bij de bron afhandelen
De SDK maakt onderscheid tussen fouten, waardoor u geen strings hoeft te analyseren om uit te zoeken wat er is gebeurd:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Uw beschrijving",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video klaar: {video.url}")
except VideoGenerationError as e:
print(f"Generatie mislukt [{e.code}]: {e.message}")
except TimeoutError:
print("Time-out overschreden: verhoog de time-out of vereenvoudig het verzoek")
Elke fout vraagt om een andere reactie; ze door elkaar halen leidt tot nutteloze retry-lussen of, erger nog, gefactureerde generaties die niets opleveren.
| Fout | Oorzaak | Aanbevolen actie |
|---|---|---|
VideoGenerationError | Fout gemeld door de API: prompt geweigerd, ongeldige bron, service overbelast… (code, message) | Lees de code: corrigeer het verzoek of probeer het later opnieuw als de service niet beschikbaar was |
TimeoutError | Wachttijd aan clientzijde overschreden | Verhoog de timeout of verkort de duur |
RuntimeError | Uitgesteld verzoek verlopen, of voltooid zonder resultaat | Start de generatie opnieuw |
grpc.RpcError | SDK-transportfout, inclusief tarieflimieten (code RESOURCE_EXHAUSTED) en sleutelproblemen | Spreid verzoeken uit met backoff, of controleer de sleutel |
De SDK gebruikt gRPC: een overschreden tarieflimiet verschijnt hier niet als een HTTP 429-code, maar als een grpc.RpcError met code RESOURCE_EXHAUSTED.
Bewerken en uitbreiden, even eenvoudig
Bewerken heeft geen speciale methode: het is generate met een bronvideo, doorgegeven als video_url (video tot 8,7 seconden, dezelfde uitvoerduur, maximaal 720p).
video = client.video.generate(
prompt="Transformeer de scène naar Japanse anime-stijl",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Uitbreiding verlengt een sequentie van 2 tot 15 seconden met een segment van 2 tot 10 seconden en retourneert de volledige video:
video = client.video.extend(
prompt="Zet de scène voort met een pan naar rechts",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Let op het verschil met de REST-API: de SDK neemt de video aan als parameter video_url, terwijl de JSON-body een video-object verwacht met de eigenschap url.
Laat nooit een video in de cloud achter
De SDK verandert niets aan het tijdelijke karakter van resultaat-URL’s. Als uw code alleen video.url weergeeft, heeft u betaald voor een generatie die binnenkort verdwenen is. De beste praktijk is om generatie en download in dezelfde functie te koppelen, zodat het onmogelijk wordt deze stap te vergeten.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Genereert een video en slaat deze lokaal op (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Directe 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 opgeslagen: {output_file}")
return output_file
Voor opslag zonder doorgifte via uw server, plaatst de parameter storage_options van de generatie de video in de xAI Files API, met een vervaldatum naar keuze.
Meerdere video’s tegelijk genereren
Met de asynchrone client is elke aanroep een coroutine en lanceert asyncio.gather een volledige batch parallel. De optie return_exceptions=True is hier doorslaggevend: zonder deze optie zou één geweigerd verzoek de hele batch doen falen en zou u de reeds verkregen resultaten verliezen.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Genereert meerdere video's 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"Verzoek {i} mislukt: {res}")
else:
print(f"Verzoek {i} voltooid: {res.url}")
return results
Twee veiligheidsmechanismen kaderen deze parallelisatie in. Indieningen verbruiken uw tarieflimiet, geteld in verzoeken per seconde volgens het niveau van uw team (10 op het instapniveau voor videomodellen): voor een grote batch begrenst u de concurrentie met een asyncio.Semaphore. Onthoud ook wat parallelisme wel en niet doet: het versnelt geen individuele generatie, het verkort alleen de totale batchtijd.
Moet u handmatige polling opgeven?
Niet systematisch. De volgende vergelijking toont waar elke aanpak de bovenhand heeft.
| Aspect | Handmatige polling | SDK |
|---|---|---|
| Complexiteit | Hoog | Laag |
| Foutafhandeling | Zelf implementeren | Geïntegreerd |
| Time-out | Zelf implementeren | Standaard 10 min, configureerbaar |
| Polling-interval | Zelf kiezen | Standaard 1 s, configureerbaar |
| Flexibiliteit | Totaal | Standaard (of start en get) |
| Afhankelijkheid | Geen | xAI SDK |
Handmatige polling blijft relevant in twee situaties: wanneer u fijne controle nodig heeft, bijvoorbeeld om voortgang door te geven aan een real-time interface of om te integreren in een bestaand wachtrijsysteem, en wanneer uw implementatiecontext het toevoegen van een extra afhankelijkheid verbiedt.
Belangrijkste punten
client.video.generatedient in, wacht en retourneert de video (url,duration,model); standaard 10 minuten time-out en controle elke seconde- Bewerken gebruikt
generatemetvideo_url, uitbreiden gebruiktclient.video.extend VideoGenerationError(vanuitxai_sdk.video),TimeoutErrorenRuntimeErrormaken onderscheid tussen fouten; tarieflimieten komen binnen alsgrpc.RpcError- Download de video altijd direct na generatie (tijdelijke URL’s)
- De asynchrone client en
asyncio.gatherparalleliseren een batch, binnen de tarieflimiet van uw niveau