Håndtering af fejl og produktionssætning
På denne side
Opdateret 2. november 2026 baseret på xAIs videodokumentation og
xai-sdk1.21.0-kode:client.video.generate(ikkeclient.videos), resultatet returneres iurl, fejl rapporteres viaVideoGenerationErrormed en kode (invalid_argument,service_unavailable…), rategrænser modtages somgrpc.RpcErrormed kodenRESOURCE_EXHAUSTED— klassenRateLimitErrorog statussenexpiredeksisterer ikke. Tillæg 3. november 2026: Rategrænsen tæller forespørgsler per sekund (10 ved startniveauet), ikke “60 RPM”, og den faktiske omkostning per generering læses frausage.cost_in_usd_ticks. Kilder: Videogenerering · Rategrænser.
Forbered din applikation til produktion
Et script, der genererer en video på din maskine, og en tjeneste, der producerer hundreder om dagen for rigtige brugere, har næsten intet til fælles. Sidstnævnte skal håndtere afvisninger fra moderation, overskridelse af kvoter, serverhændelser og udløbne URLs uden nogensinde stille at miste en faktureret generering. Denne lektion dækker de mekanismer, der gør forskellen: fejlklassificering, genforsøgsstrategi, køarkitektur og observerbarhed.
To fejltyper, to tidspunkter
Den første familie optræder øjeblikkeligt ved selve POST-kaldet. Dette er strikse anmodningsfejl, hvor HTTP-koden er nok til at afgøre, hvad der skal gøres.
| HTTP-kode | Årsag | Løsning |
|---|---|---|
| 400 | Ugyldige parametre (f.eks. en ukendt stemme i reference_audios) | Ret anmodningen |
| 401 | Ugyldig eller udløbet API-nøgle | Verificér autentificering |
| 429 | Rategrænse overskredet (forespørgsler per sekund afhængigt af niveau) | Implementér backoff |
| 500 | Serverfejl | Genforsøg med eksponentiel backoff |
Den anden familie viser sig meget senere under polling, efter at anmodningen er blevet accepteret, og genereringen er startet.
| Status | Sandsynlig årsag | Handling |
|---|---|---|
failed + invalid_argument eller permission_denied | Anmodning eller indhold afvist | Ændr prompten eller kilden |
failed + service_unavailable eller internal_error | Tjenesten overbelastet, hændelse | Genforsøg senere |
Denne sondring er ikke akademisk: En 400-fejl skal straks returneres til kalderen, fordi fejlen ligger i koden, mens en failed-status opstår efter flere minutters ventetid og skal håndteres i jobkonteksten, ikke i den HTTP-anmodning, der udløste den.
Genforsøg intelligent
Grundlaget er eksponentiel backoff med lidt jitter. At fordoble forsinkelsen giver en midlertidig hændelse tid til at løse sig selv, og jitter forhindrer, at alle dine processer genforsøger på præcis samme tidspunkt efter en spidsbelastning — et fænomen, der kan vende en mikroudfald til en vedvarende fejl.
import asyncio
import random
async def call_with_retry(func, max_retries=3, base_delay=2):
"""Executes a function with retry and exponential backoff."""
for attempt in range(max_retries + 1):
try:
return await func()
except Exception as e:
if attempt == max_retries:
raise
# Exponential backoff with jitter
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Attempt {attempt + 1} failed: {e}. Retrying in {delay:.1f}s")
await asyncio.sleep(delay)
Denne generiske ordning er dog ikke nok, fordi ikke alle fejl fortjener samme tålmodighed. En overskridelse af kvoten løses ved at vente et helt minut; en afvisning fra moderation vil aldrig løse sig, og at genforsøge svarer til at betale flere gange for samme fejl. Den følgende funktion skelner mellem tilfældene.
import asyncio
from datetime import timedelta
import grpc
from xai_sdk.video import VideoGenerationError
# Failure codes that a retry will not fix
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}
async def generate_with_retry(client, params, max_retries=3):
"""Video generation with targeted 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 # request or content refused: fix before relaunching
await asyncio.sleep(5 * (attempt + 1)) # service overloaded, 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
# Allow more time for the next attempt
params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)
En kø til at holde takten
Så snart din tjeneste modtager anmodninger fra flere brugere, skal du afkoble modtagelsen af anmodninger fra selve udførelsen og frem for alt begrænse samtidigheden for at holde dig under dit niveaus rategrænse. En kø parret med en semaphore opfylder begge behov: Jobs kan ophobes frit, men maksimalt ti udføres ad gangen.
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):
"""Adds a generation to the queue."""
self.queue.append((job_id, params))
async def process(self):
"""Processes all pending generations."""
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):
"""Executes a generation with concurrency control."""
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)
}
Bemærk, at hvert job gemmer sit resultat i results, uanset om det er succes eller fiasko: En generering, der forsvinder uden spor, er en hændelse, som ingen kan diagnosticere.
Den anden arkitektoniske refleks vedrører lagring. Da video-URLs er midlertidige, skal download være automatisk og øjeblikkelig med tidsstemplede filnavne, der garanterer ingen kollision mellem to samtidige genereringer.
import httpx
from pathlib import Path
from datetime import datetime
async def save_video(video_url, output_dir="./videos"):
"""Downloads and saves a generated video."""
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
Verificér din nøgle, før du afhænger af den
Endepunktet GET /v1/api-key informerer dig om din nøgles tilstand. At kalde det ved tjenestens opstart undgår, at du opdager en blokeret nøgle efter tyve mislykkede forespørgsler, mens dine brugere venter.
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 key or team blocked, or key disabled")
Se, hvad der sker i produktionen
Fem indikatorer er nok til at styre en videogenereringstjeneste. Succesraten, altså andelen af genereringer, der ender med done, måler den overordnede sundhedstilstand. Den gennemsnitlige genereringstid, målt fra indsendelse til done-status, bruges til at kalibrere dine timeouts og informere dine brugere. Fejlraten opdelt efter type — failed efter fejlkode, timeout, rategrænse — fortæller dig, hvor du skal sætte ind: En stigning i timeouts uden en stigning i failed signalerer f.eks. genereringer, der er langsommere end din ventefrist, ikke egentlige fejl. De akkumulerede omkostninger, opnået ved at summere feltet usage.cost_in_usd_ticks fra hvert resultat (én dollar svarer til 10 milliarder ticks), eller alternativt ved at gange genererede varigheder med modellens pris per sekund, skal overvåges dagligt. Endelig forudsiger kvotebrugen, i forespørgsler per sekund i forhold til din niveaugrænse (10 ved startniveauet for videomodeller), mætning, før den manifesterer sig som 429-fejl.
Disse metrics opbygges naturligt ud fra en struktureret log, hvor hver generering efterlader en linje, som dit analyseværktøj kan bruge.
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
}))
Før du åbner din tjeneste for offentligheden, skal du gennemgå det hele fra starten. Genforsøg med eksponentiel backoff og jitter skal være på plads, og samtidigheden skal begrænses af en semaphore for at overholde rategrænsen. Videodownload skal udløses automatisk, så snart de er klar, uden at afhænge af menneskelig indgriben. Hver generering skal efterlade en loglinje med sit request_id, sin status og sine omkostninger; ellers vil fejlraten og den gennemsnitlige genereringstid forblive unverificerbare. Tjek API-nøglens tilstand ved opstart snarere end ved den første fejl. Og sæt et budget med alarmer ved overskridelse: Ved $0,05 per sekund bruger en ubegrænset genforsøgsløkke penge hurtigere, end du tror.
Priser verificeret 3. november 2026 — priser ændrer sig regelmæssigt: Før enhver budgetberegning skal du verificere den aktuelle prisliste på den officielle side for xAI-modeller og priser.
Vigtige pointer
- Fejl deles op i synkrone (anmodning) og asynkrone (generering)
- Ikke alle fejl fortjener et genforsøg: Moderation er endelig
- Brug en semaphore til at begrænse samtidige genereringer
- Midlertidige URLs kræver øjeblikkelig og systematisk download
- Spor metrics for omkostninger, succes og genereringstid for at styre din tjeneste
Test din viden
Generativ video i produktion: Valider hele workflowet.
1. Hvad er særegenhederne ved en videoprompt?
Svar: Beskriv handlingen og bevægelsen, ikke kun scenen: emne, forflytning, stemning, indramning — den tidsmæssige dimension er det, der adskiller videoprompten fra billedprompten.
2. Hvad muliggør image-to-video?
Svar: Animer et eksisterende billede, eller bring givne personer og produkter ind i en ny scene ved hjælp af referencebilleder — og på grok-imagine-video-1.5 kan du fastlåse det første, sidste eller nøglebilleder: Din visuelle identitet bliver et udgangspunkt, ikke et tilfælde.
3. Redigering og udvidelse: hvilke anvendelser?
Svar: /videos/edits modificerer en genereret video, /videos/extensions forlænger den — og begge kombineres til at bygge lange sekvenser gennem iterationer.
4. Hvorfor er workflowet asynkront?
Svar: Videogenerering tager tid: Du indsender et job, poller dets status og henter derefter resultatet — xAI SDK’et automatiserer denne polling.
5. Hvad skal planlægges til produktion?
Svar: Håndtering af fejl og mislykkede jobs, øjeblikkelig download af outputs og sporing af omkostninger (opløsning, varighed, iterationer) — video er den dyreste modalitet: Det skal budgetteres.
Tidsmæssig prompt, visuel reference, mestret asynkronitet: Generativ video bliver til en pipeline — ikke et lotteri.