Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

xAI SDK en automatische polling

Les 11 van 12 Bijgewerkt op 2 november 2026 Gemiddeld
Op deze pagina
  1. Vereenvoudig polling met de SDK
  2. Eén aanroep in plaats van een lus
  3. Fouten bij de bron afhandelen
  4. Bewerken en uitbreiden, even eenvoudig
  5. Laat nooit een video in de cloud achter
  6. Meerdere video’s tegelijk genereren
  7. Moet u handmatige polling opgeven?
  8. Belangrijkste punten

Bijgewerkt op 2 november 2026 op basis van de xAI-videodocumentatie en de code van xai-sdk 1.21.0: de methoden heten client.video.generate en client.video.extend (bewerken gebruikt generate met video_url), het resultaat exposeert url, de vertraging wordt ingesteld via een timedelta en het standaard polling-interval is één seconde. await vereist de asynchrone client AsyncClient en de uitzondering VideoGenerationError wordt geïmporteerd vanuit xai_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.

FoutOorzaakAanbevolen actie
VideoGenerationErrorFout 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
TimeoutErrorWachttijd aan clientzijde overschredenVerhoog de timeout of verkort de duur
RuntimeErrorUitgesteld verzoek verlopen, of voltooid zonder resultaatStart de generatie opnieuw
grpc.RpcErrorSDK-transportfout, inclusief tarieflimieten (code RESOURCE_EXHAUSTED) en sleutelproblemenSpreid 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.

AspectHandmatige pollingSDK
ComplexiteitHoogLaag
FoutafhandelingZelf implementerenGeïntegreerd
Time-outZelf implementerenStandaard 10 min, configureerbaar
Polling-intervalZelf kiezenStandaard 1 s, configureerbaar
FlexibiliteitTotaalStandaard (of start en get)
AfhankelijkheidGeenxAI 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.generate dient in, wacht en retourneert de video (url, duration, model); standaard 10 minuten time-out en controle elke seconde
  • Bewerken gebruikt generate met video_url, uitbreiden gebruikt client.video.extend
  • VideoGenerationError (vanuit xai_sdk.video), TimeoutError en RuntimeError maken onderscheid tussen fouten; tarieflimieten komen binnen als grpc.RpcError
  • Download de video altijd direct na generatie (tijdelijke URL’s)
  • De asynchrone client en asyncio.gather paralleliseren een batch, binnen de tarieflimiet van uw niveau