Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Workflow asynchroon en polling

Les 10 van 12 Bijgewerkt op 2 november 2026 Gemiddeld
Op deze pagina
  1. De levenscyclus van een video begrijpen
  2. De generatiestatus controleren
  3. Drie staten, drie acties
  4. Polling implementeren
  5. Het polling-interval instellen
  6. Belangrijkste punten

Bijgewerkt op 2 november 2026. Gebaseerd op de xAI Video API-referentie: de URL vindt u in video.url (niet video_url), een generatie heeft slechts drie statussen (pending, done, failed, waarbij de laatste vergezeld gaat van een foutcode), en snelheidslimieten worden uitgedrukt in verzoeken per seconde op basis van het teamniveau. Bronnen: Video Generation · Videos Reference · Rate limits.

De levenscyclus van een video begrijpen

Alle video-operaties in de xAI API zijn asynchroon. Deze eigenschap bepaalt uw applicatie-architectuur meer dan u op het eerste gezicht zou verwachten. Een chat-oproep of het genereren van een afbeelding levert direct een resultaat op; videogeneratie vereist echter aanzienlijke verwerkingstijd en retourneert slechts een bevestiging. Het is aan u om de tracking te implementeren: vraag periodiek de taakstatus op, detecteer voltooiing en haal het bestand op. De volledige cyclus bestaat uit vier stappen.

1

Verzoek indienen

POST naar het eindpunt voor generatie, bewerking of uitbreiding. Direct antwoord met een request_id.

2

Status controleren (Polling)

GET /v1/videos/{request_id} met regelmatige tussenpozen. Het veld progress loopt van 0 tot 100.

3

Resultaat ophalen

Wanneer de status done is (progress = 100), is de video-URL beschikbaar.

4

Direct downloaden

De video-URL is tijdelijk. Download deze zo snel mogelijk.

De generatiestatus controleren

Tracking vereist een eenvoudig GET-verzoek naar het status-eindpunt, waarbij u de identifier gebruikt die u bij het indienen hebt ontvangen.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Het antwoord bevat de volgende nuttige informatie:

  • status : de huidige generatiestaat
  • progress : een geheel getal van 0 tot 100 dat de voortgang aangeeft
  • video.url : de video-URL, binnen het video-object dat aanwezig is wanneer de status done is, inclusief de duur (video.duration)
  • video.respect_moderation : een boolean die aangeeft of de inhoud voldoet aan het moderatiebeleid
  • error : bij mislukking een code (invalid_argument, permission_denied, failed_precondition, service_unavailable of internal_error) en een bericht
  • usage.cost_in_usd_ticks : de kosten van het verzoek, in tien-miljardste delen van een dollar

Het veld progress verdient een opmerking: het stuurt niet uw contrologica, die altijd op status moet vertrouwen, maar het is goud waard voor een gebruikersinterface. Het weergeven van “62%” in plaats van een statische laadspinner verandert de perceptie van een wachttijd die enkele minuten kan duren volledig.

Drie staten, drie acties

StatusProgressBetekenis
pending0-99Generatie bezig
done100Voltooid, URL beschikbaar
failedafwezigGeneratie mislukt

Zolang de status pending is, gaat de generatie door: u blijft eenvoudigweg met regelmatige tussenpozen query’s uitvoeren en geeft progress door aan uw interface. Wanneer deze overschakelt naar done, is de video klaar en hoeft u alleen nog maar video.url uit te lezen en het bestand direct te downloaden. Deze URL’s zijn tijdelijk en de documentatie specificeert hun levensduur niet, wat opslaan in een database voor later gebruik uitsluit.

Tot slot geeft de status failed een productiefout aan, en het veld error vertelt u welke. Het onderscheid is belangrijk voor wat volgt: service_unavailable (dienst tijdelijk overbelast) of internal_error rechtvaardigen een latere nieuwe poging, terwijl invalid_argument of permission_denied—afgewezen prompt, ongeldige bronafbeelding of video—vereisen dat u eerst het verzoek corrigeert. De Python SDK signaleert overigens ook via een fout een uitgesteld verzoek dat is verlopen voordat het werd opgehaald.

Polling implementeren

De synchrone versie past in één functie. Deze loopt in een lus tot de time-out, stopt voortijdig bij mislukking door de foutcode te raise-en, en retourneert de URL zodra de video klaar is.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Wachten tot videogeneratie is voltooid."""
    headers = {"Authorization": f"Bearer {api_key}"}
    debut = time.time()

    while time.time() - debut < timeout:
        resp = httpx.get(
            f"https://api.x.ai/v1/videos/{request_id}",
            headers=headers
        ).json()

        status = resp.get("status")
        progress = resp.get("progress", 0)

        if status == "done":
            return resp["video"]["url"]
        elif status == "failed":
            erreur = resp.get("error", {})
            raise RuntimeError(f"Generation failed [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"In progress... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Timeout after {timeout} seconds")

In een service die meerdere verzoeken tegelijk afhandelt, wordt deze blokkerende versie een flessenhals: elke wachttijd immobiliseert een thread gedurende minuten. De asynchrone variant maakt de event loop vrij tussen query’s door en stelt u in staat tientallen generaties parallel te volgen.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchrone versie van polling."""
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        debut = asyncio.get_event_loop().time()

        while asyncio.get_event_loop().time() - debut < timeout:
            resp = await client.get(
                f"https://api.x.ai/v1/videos/{request_id}",
                headers=headers
            )
            data = resp.json()

            if data["status"] == "done":
                return data["video"]["url"]
            elif data["status"] == "failed":
                raise RuntimeError(f"Generation failed : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Timeout")

Het polling-interval instellen

Het kiezen van het interval is een afweging tussen responsiviteit en verspilde verzoeken. Vijf seconden is in de meeste gevallen een goed compromis. Voor lange generaties—tien tot vijftien seconden video—is tien tot vijftien seconden tussen de polls meer dan genoeg en vermindert het dataverkeer. Omgekeerd rechtvaardigt een interactieve applicatie waarbij de gebruiker een voortgangsbalk bekijkt het verlagen naar twee of drie seconden. Onder de één seconde versnelt u echter niets: de generatie verloopt in zijn eigen tempo en u vermenigvuldigt alleen maar nodeloos verzoeken.

Belangrijkste punten

  • Alle video-operaties zijn asynchroon: POST om in te dienen, GET om op te halen
  • Drie mogelijke statussen: pending, done, failed (met een foutcode)
  • Het veld progress (0-100) stelt u in staat de voortgang te volgen
  • Implementeer een time-out en een polling-interval dat bij uw gebruiksscenario past
  • Video-URL’s zijn tijdelijk: download ze direct