Hantering av fel och distribution i produktion
På denna sida
Uppdaterad 2 november 2026 baserat på xAIs videodokumentation och kod för
xai-sdk1.21.0:client.video.generate(inteclient.videos), resultatet finns iurl, fel rapporteras viaVideoGenerationErrormed en kod (invalid_argument,service_unavailable…), hastighetsbegränsningar returneras somgrpc.RpcErrormed kodenRESOURCE_EXHAUSTED— klassenRateLimitErroroch statusenexpiredexisterar inte. Tillägg 3 november 2026: hastighetsbegränsningen räknar förfrågningar per sekund (10 på ingångsnivån), inte “60 RPM”, och den faktiska kostnaden per generering läses frånusage.cost_in_usd_ticks. Källor: Videogenerering · Hastighetsbegränsningar.
Förbered din applikation för produktion
Ett skript som genererar en video på din dator och en tjänst som producerar hundratals videor per dag för riktiga användare har nästan inget gemensamt. Den senare måste hantera vägran från modereringssystem, överskridna kvoter, serverincidenter och URL:er som löper ut, utan att någonsin tyst förlora en fakturerad generering. Denna lektion täcker de mekanismer som gör skillnaden: felklassificering, strategi för återförsök, köarkitektur och observerbarhet.
Två familjer av fel, två tidpunkter
Den första familjen dyker upp omedelbart, vid själva POST-anropet. Detta är strikta fel i förfrågan, och HTTP-koden räcker för att avgöra vad som ska göras.
| HTTP-kod | Orsak | Lösning |
|---|---|---|
| 400 | Ogiltiga parametrar (t.ex. en okänd röst i reference_audios) | Korrigera förfrågan |
| 401 | Ogiltig eller utgången API-nyckel | Verifiera autentiseringen |
| 429 | Hastighetsbegränsning överskriden (förfrågningar per sekund, beroende på nivå) | Implementera backoff |
| 500 | Serverfel | Försök igen med exponentiell backoff |
Den andra familjen manifesterar sig mycket senare, under polling, efter att förfrågan har accepterats och genereringen har startat.
| Status | Sannolik orsak | Åtgärd |
|---|---|---|
failed + invalid_argument eller permission_denied | Förfrågan eller innehåll nekat | Ändra prompten eller källan |
failed + service_unavailable eller internal_error | Tjänsten överbelastad, incident | Försök igen senare |
Denna åtskillnad är inte akademisk: ett 400-fel måste returneras omedelbart till anroparen eftersom felet ligger i koden, medan en status failed inträffar efter flera minuters väntan och måste hanteras i jobbkontexten, inte i den HTTP-förfrågan som utlöste den.
Försök igen intelligent
Den gemensamma grunden är exponentiell backoff med viss slumpmässig variation (jitter). Att fördubbla fördröjningen ger en övergående incident tid att lösas, och jitter förhindrar att alla dina processer försöker igen vid exakt samma ögonblick efter en topp – ett fenomen som kan förvandla ett mikrobortfall till ett bestående fel.
import asyncio
import random
async def call_with_retry(func, max_retries=3, base_delay=2):
"""Kör en funktion med återförsök och exponentiell backoff."""
for attempt in range(max_retries + 1):
try:
return await func()
except Exception as e:
if attempt == max_retries:
raise
# Exponentiell backoff med jitter
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Försök {attempt + 1} misslyckades: {e}. Försöker igen om {delay:.1f}s")
await asyncio.sleep(delay)
Detta generella schema räcker dock inte, eftersom inte alla fel förtjänar samma tålamod. En överskriden kvot löses genom att vänta en hel minut; en vägran från modereringen kommer aldrig att lösa sig, och att försöka igen innebär bara att du betalar flera gånger för samma misslyckande. Följande funktion skiljer på fallen.
import asyncio
from datetime import timedelta
import grpc
from xai_sdk.video import VideoGenerationError
# Felkoder som ett återförsök inte kommer att lösa
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}
async def generate_with_retry(client, params, max_retries=3):
"""Videogenerering med målinriktade återförsök (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 # förfrågan eller innehåll nekat: åtgärda innan omstart
await asyncio.sleep(5 * (attempt + 1)) # tjänsten överbelastad, incident
except grpc.RpcError as e:
if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
raise
await asyncio.sleep(2 ** attempt) # hastighetsbegränsning: backoff
except TimeoutError:
if is_last:
raise
# Ge mer tid för nästa försök
params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)
En kö för att hålla takten
Så snart din tjänst tar emot förfrågningar från flera användare måste du koppla bort mottagandet av förfrågningar från själva utförandet, och framför allt begränsa samtidigheten för att hålla dig under din nivåns hastighetsbegränsning. En kö kombinerad med en semafor tillgodoser båda behoven: jobb staplas fritt, men maximalt tio exekverar samtidigt.
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):
"""Lägger till en generering i kön."""
self.queue.append((job_id, params))
async def process(self):
"""Behandlar alla väntande genereringar."""
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):
"""Kör en generering med kontroll av samtidighet."""
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)
}
Observera att varje jobb sparar sitt resultat i results, oavsett om det lyckades eller misslyckades: en generering som försvinner utan spår är en incident som ingen kan diagnostisera.
Den andra reflexen gällande arkitektur handlar om lagring. Eftersom video-URL:er är tillfälliga måste nedladdningen ske automatiskt och omedelbart, med tidsstämplad namngivning som garanterar att inga kollisioner uppstår mellan två samtidiga genereringar.
import httpx
from pathlib import Path
from datetime import datetime
async def save_video(video_url, output_dir="./videos"):
"""Laddar ner och sparar en genererad 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
Verifiera din nyckel innan du förlitar dig på den
Slutpunkten GET /v1/api-key informerar dig om din nyckels status. Att anropa den vid tjänstens start undviker att du upptäcker en blockerad nyckel efter tjugo misslyckade förfrågningar, medan dina användare väntar.
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-nyckel eller team blockerat, eller nyckel inaktiverad")
Se vad som händer i produktion
Fem indikatorer räcker för att styra en tjänst för videogenerering. Framgångsfrekvensen, det vill säga andelen genereringar som slutar med done, mäter den övergripande hälsan. Den genomsnittliga genereringstiden, uppmätt mellan inlämning och status done, används för att kalibrera dina time-outs och informera dina användare. Felprocenten uppdelad efter typ – failed efter felkod, time-out, hastighetsbegränsning – berättar var du bör fokusera dina ansträngningar: en ökning av time-outs utan en ökning av failed signalerar till exempel att genereringarna är långsammare än din väntegräns, inte att de misslyckas. Den ackumulerade kostnaden, erhållen genom att summera fältet usage.cost_in_usd_ticks från varje resultat (en dollar motsvarar 10 miljarder ticks), eller alternativt genom att multiplicera genererade längder med modellens pris per sekund, måste övervakas dagligen. Slutligen förutser användningen av kvoten, i förfrågningar per sekund relativt din nivågräns (10 på ingångsnivån för videomodeller), mättnad innan den resulterar i 429-fel.
Dessa mått byggs naturligt från en strukturerad logg, där varje generering lämnar en rad som kan användas av ditt analysverktyg.
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
}))
Innan du öppnar din tjänst för allmänheten bör du granska hela processen från början. Återförsök med exponentiell backoff och jitter måste vara på plats, och samtidigheten måste begränsas av en semafor för att hålla sig under hastighetsbegränsningen. Nedladdning av videor måste utlösas automatiskt så snart de är redo, utan att bero på mänsklig inblandning. Varje generering måste lämna en loggrad som innehåller sitt request_id, status och kostnad, annars kommer felprocenten och den genomsnittliga genereringstiden att förbli overifierbara. Kontrollera API-nyckelns status vid start snarare än vid det första felet. Och sätt en budget med varningar vid överskridande: vid 0,05 USD per sekund konsumerar en obegränsad loop för återförsök snabbare än du tror.
Priser verifierade 3 november 2026 – priserna utvecklas regelbundet: innan någon budgetberäkning, verifiera den aktuella prislistan på xAIs officiella sida för modeller och prissättning.
Viktiga punkter
- Fel delas upp i synkrona (förfrågan) och asynkrona (generering)
- Inte alla fel förtjänar ett återförsök: moderering är definitiv
- Använd en semafor för att begränsa samtidiga genereringar
- Tillfälliga URL:er kräver omedelbar och systematisk nedladdning
- Spåra mått för kostnad, framgång och genereringstid för att styra din tjänst
Testa dina kunskaper
Generativ video i produktion: validera hela arbetsflödet.
1. Vad är särskilt med en videoprompt?
Svar: Beskriv handlingen och rörelsen, inte bara scenen: subjekt, förflyttning, stämning, bildutsnitt – den tidsmässiga dimensionen är det som skiljer videoprompten från bildprompten.
2. Vad möjliggör image-to-video?
Svar: Animera en befintlig bild, eller placera givna personer och produkter i en ny scen med hjälp av referensbilder – och på grok-imagine-video-1.5, fästa den första, sista eller nyckelbilder: din visuella identitet blir en utgångspunkt, inte en slump.
3. Redigering och förlängning: vilka användningsområden?
Svar: /videos/edits modifierar en genererad video, /videos/extensions förlänger den – och båda kombineras för att bygga långa sekvenser genom iterationer.
4. Varför är arbetsflödet asynkront?
Svar: Videogenerering tar tid: du skickar in ett jobb, pollar dess status och hämtar sedan resultatet – xAI SDK automatiserar denna polling.
5. Vad måste planeras för produktion?
Svar: Felhantering och misslyckade jobb, omedelbar nedladdning av utdata och kostnadsspårning (upplösning, längd, iterationer) – video är den dyraste modaliteten: den måste budgeteras.
Tidsmässig prompt, visuell referens, behärskad asynkronitet: generativ video blir en pipeline – inte ett lotteri.