Foutafhandeling en productie-implementatie
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van de xAI-videodocumentatie en
xai-sdk1.21.0-code:client.video.generate(nietclient.videos), resultaat inurl, fouten gerapporteerd doorVideoGenerationErrormet een code (invalid_argument,service_unavailable…), rate limit ontvangen alsgrpc.RpcErrormet codeRESOURCE_EXHAUSTED— de klasseRateLimitErroren statusexpiredbestaan 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 uitusage.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-code | Oorzaak | Oplossing |
|---|---|---|
| 400 | Ongeldige parameters (bijvoorbeeld een onbekende stem in reference_audios) | Herstel het verzoek |
| 401 | Ongeldige of verlopen API-sleutel | Verifieer authenticatie |
| 429 | Rate limit overschreden (aanvragen per seconde, afhankelijk van tier) | Implementeer backoff |
| 500 | Serverfout | Opnieuw 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.
| Status | Waarschijnlijke oorzaak | Actie |
|---|---|---|
failed + invalid_argument of permission_denied | Verzoek of inhoud geweigerd | Pas de prompt of bron aan |
failed + service_unavailable of internal_error | Service overbelast, incident | Probeer 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.