Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Foutafhandeling en productie-implementatie

Les 12 van 12 Bijgewerkt op 3 november 2026 Gemiddeld
Op deze pagina
  1. Bereid uw applicatie voor op productie
  2. Twee families fouten, twee momenten
  3. Slim opnieuw proberen
  4. Een wachtrij om het tempo bij te houden
  5. Verifieer uw sleutel voordat u ervan afhankelijk bent
  6. Zie wat er gebeurt in productie
  7. Belangrijkste punten
  8. Test uw kennis

Bijgewerkt op 2 november 2026 op basis van de xAI-videodocumentatie en xai-sdk 1.21.0-code: client.video.generate (niet client.videos), resultaat in url, fouten gerapporteerd door VideoGenerationError met een code (invalid_argument, service_unavailable…), rate limit ontvangen als grpc.RpcError met code RESOURCE_EXHAUSTED — de klasse RateLimitError en status expired bestaan niet. Aanvulling 3 november 2026: rate limit telt aanvragen per seconde (10 bij het instaptarief), niet “60 RPM”, en de werkelijke kosten per generatie worden gelezen uit usage.cost_in_usd_ticks. Bronnen: Videogeneratie · Rate limits.

Bereid uw applicatie voor op productie

Een script dat op uw machine een video genereert en een service die dagelijks honderden video’s produceert voor echte gebruikers, hebben bijna niets met elkaar gemeen. Laatstgenoemde moet weigeringen door moderatie, overschrijdingen van quota, serverincidenten en verlopen URL’s afhandelen zonder ooit een gefactureerde generatie stilzwijgend te verliezen. Deze les behandelt de mechanismen die het verschil maken: foutclassificatie, retry-strategie, wachtrij-architectuur en observeerbaarheid.

Twee families fouten, twee momenten

De eerste familie verschijnt onmiddellijk, op het moment van de POST-aanroep. Dit zijn strikte verzoekfouten; de HTTP-code volstaat om te beslissen wat er moet gebeuren.

HTTP-codeOorzaakOplossing
400Ongeldige parameters (bijvoorbeeld een onbekende stem in reference_audios)Herstel het verzoek
401Ongeldige of verlopen API-sleutelVerifieer authenticatie
429Rate limit overschreden (aanvragen per seconde, afhankelijk van tier)Implementeer backoff
500ServerfoutOpnieuw proberen met exponentiële backoff

De tweede familie manifesteert zich veel later, tijdens het polleren, nadat het verzoek is geaccepteerd en de generatie is gestart.

StatusWaarschijnlijke oorzaakActie
failed + invalid_argument of permission_deniedVerzoek of inhoud geweigerdPas de prompt of bron aan
failed + service_unavailable of internal_errorService overbelast, incidentProbeer het later opnieuw

Dit onderscheid is niet academisch: een 400 moet onmiddellijk naar de aanroeper worden teruggestuurd omdat de code foutief is, terwijl een failed-status pas na enkele minuten wachten optreedt en in de job-context moet worden afgehandeld, niet in het HTTP-verzoek dat het heeft geactiveerd.

Slim opnieuw proberen

De gemeenschappelijke basis is exponentiële backoff met enige jitter. Het verdubbelen van de vertraging geeft een tijdelijk incident de tijd om op te lossen, en jitter voorkomt dat al uw processen op hetzelfde moment opnieuw proberen na een piek — een fenomeen dat een micro-uitval verandert in een aanhoudende storing.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Voert een functie uit met retry en exponentiële backoff."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Exponentiële backoff met jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Poging {attempt + 1} mislukt: {e}. Opnieuw proberen over {delay:.1f}s")
            await asyncio.sleep(delay)

Dit algemene schema is echter niet voldoende, omdat niet alle fouten hetzelfde geduld verdienen. Een overschrijding van het quota lost op door een volledige minuut te wachten; een weigering door moderatie zal nooit oplossen, en opnieuw proberen komt neer op meerdere keren betalen voor dezelfde mislukking. De volgende functie maakt onderscheid tussen de gevallen.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Foutcodes die een retry niet zal oplossen
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Videogeneratie met gerichte retry (client: xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # verzoek of inhoud geweigerd: eerst herstellen voordat opnieuw gestart wordt
            await asyncio.sleep(5 * (attempt + 1))  # service overbelast, incident
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # rate limit: backoff
        except TimeoutError:
            if is_last:
                raise
            # Meer tijd toestaan voor de volgende poging
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Een wachtrij om het tempo bij te houden

Zodra uw service aanvragen van meerdere gebruikers ontvangt, moet u de ontvangst van aanvragen ontkoppelen van de uitvoering, en bovenal de concurrentie begrenzen om onder de rate limit van uw tier te blijven. Een wachtrij gecombineerd met een semaphore voldoet aan beide behoeften: jobs stapelen zich vrij op, maar er worden maximaal tien tegelijk uitgevoerd.

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Voegt een generatie toe aan de wachtrij."""
        self.queue.append((job_id, params))

    async def process(self):
        """Verwerkt alle wachtende generaties."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Voert een generatie uit met concurrentiebeheersing."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

Merk op dat elke job zijn uitkomst bewaart in results, succes of falen: een generatie die spoorloos verdwijnt, is een incident dat niemand kan diagnosticeren.

De tweede reflex voor de architectuur betreft opslag. Omdat video-URL’s tijdelijk zijn, moet downloaden automatisch en onmiddellijk gebeuren, met een tijdstempel in de bestandsnaam die garandeert dat er geen botsing optreedt tussen twee gelijktijdige generaties.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Downloadt en slaat een gegenereerde video op."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Verifieer uw sleutel voordat u ervan afhankelijk bent

Het eindpunt GET /v1/api-key informeert u over de status van uw sleutel. Door dit bij het opstarten van de service aan te roepen, voorkomt u dat u pas na twintig mislukte aanvragen ontdekt dat de sleutel geblokkeerd is, terwijl uw gebruikers wachten.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("API-sleutel of team geblokkeerd, of sleutel uitgeschakeld")

Zie wat er gebeurt in productie

Vijf indicatoren volstaan om een videogeneratieservice te sturen. Het slagingspercentage, oftewel het aandeel generaties dat eindigt in done, meet de algehele gezondheid. De gemiddelde generatietijd, gemeten tussen indiening en de status done, dient om uw time-outs te kalibreren en uw gebruikers te informeren. Het foutenpercentage uitgesplitst per type — failed per foutcode, time-out, rate limit — vertelt u waar u effort moet steken: een stijging van time-outs zonder stijging van failed signaleert bijvoorbeeld generaties die langzamer zijn dan uw wachtdrempel, geen mislukkingen. De cumulatieve kosten, verkregen door het veld usage.cost_in_usd_ticks van elk resultaat op te tellen (één dollar is gelijk aan 10 miljard ticks), of alternativ door gegenereerde duur te vermenigvuldigen met de prijs per seconde van het model, moet dagelijks worden bewaakt. Tot slot anticipeert het quotagebruik, in aanvragen per seconde ten opzichte van uw tier-limiet (10 bij het instaptarief voor videomodellen), op verzadiging voordat dit zich vertaalt in 429-fouten.

Deze metrieken bouwen zich natuurlijk op vanuit een gestructureerd logboek, waarbij elke generatie een regel achterlaat die bruikbaar is voor uw analysetool.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

Voordat u uw service opent voor het publiek, bekijkt u het geheel nogmaals vanaf het begin. Retry met exponentiële backoff en jitter moet aanwezig zijn, en concurrentie moet worden begrensd door een semaphore om onder de rate limit te blijven. Videodownloads moeten automatisch worden geactiveerd zodra ze klaar zijn, zonder afhankelijk te zijn van menselijk handelen. Elke generatie moet een logregel achterlaten met de request_id, status en kosten; anders blijven het foutenpercentage en de gemiddelde generatietijd onverifieerbaar. Controleer de status van de API-sleutel bij het opstarten in plaats van bij de eerste mislukking. En stel een budget in met waarschuwingen bij overschrijding: bij $0,05 per seconde verbruikt een onbegrensde retry-lus sneller dan u denkt.

Prijzen geverifieerd op 3 november 2026 — prijzen evolueren regelmatig: controleer voor elke budgetberekening het huidige tarief op de officiële xAI-modellen en prijzenpagina.

Belangrijkste punten

  • Fouten splitsen zich in synchrone (verzoek) en asynchrone (generatie)
  • Niet alle fouten verdienen een retry: moderatie is definitief
  • Gebruik een semaphore om gelijktijdige generaties te beperken
  • Tijdelijke URL’s vereisen onmiddellijk en systematisch downloaden
  • Volg kosten-, succes- en generatietijdmetrieken om uw service te sturen

Test uw kennis

Generatieve video in productie: valideer de volledige workflow.

1. Wat zijn de bijzonderheden van een videoprompt?

Antwoord: Beschrijf de actie en beweging, niet alleen de scène: onderwerp, verplaatsing, sfeer, kadrering — de temporele dimensie is wat de videoprompt onderscheidt van de image-prompt.

2. Wat maakt image-to-video mogelijk?

Antwoord: Een bestaande afbeelding animeren, of gegeven personen en producten in een nieuwe scène brengen met referentieafbeeldingen — en, op grok-imagine-video-1.5, de eerste, laatste of sleutelafbeeldingen vastpinnen: uw visuele identiteit wordt een startpunt, geen toevalstreffer.

3. Bewerken en verlengen: welke toepassingen?

Antwoord: /videos/edits wijzigt een gegenereerde video, /videos/extensions verlengt deze — en beide combineren om lange sequenties op te bouwen door iteraties.

4. Waarom is de workflow asynchroon?

Antwoord: Videogeneratie kost tijd: u dient een job in, pollt de status en haalt vervolgens het resultaat op — de xAI SDK automatiseert dit polleren.

5. Wat moet u plannen voor productie?

Antwoord: Foutafhandeling en mislukte jobs, onmiddellijk downloaden van outputs en kostentracking (resolutie, duur, iteraties) — video is de duurste modaliteit: deze moet gebudgetteerd worden.

Temporele prompt, visuele referentie, beheerste async: generatieve video wordt een pijplijn — geen loterij.