Spracovanie chýb a nasadenie do produkcie
Na tejto strane
Aktualizované 2. novembra 2026 na základe dokumentácie xAI k videu a kódu
xai-sdk1.21.0:client.video.generate(nieclient.videos), výsledok vurl, zlyhania hlásené prostredníctvomVideoGenerationErrors kódom (invalid_argument,service_unavailable…), limit rýchlosti prijatý akogrpc.RpcErrors kódomRESOURCE_EXHAUSTED— triedaRateLimitErrora stavexpiredneexistujú. Doplnok z 3. novembra 2026: limit rýchlosti počíta požiadavky za sekundu (10 v základnej úrovni), nie „60 RPM“, a skutočné náklady na generovanie sa čítajú zusage.cost_in_usd_ticks. Zdroje: Generovanie videa · Limity rýchlosti.
Priprav svoju aplikáciu na produkciu
Skript, ktorý generuje video na tvojom počítači, a služba, ktorá vyrába stovky videí denne pre reálnych používateľov, nemajú takmer nič spoločné. Tá druhá musí zvládať odmietnutia moderácie, prekročenia kvót, incidenty na serveri a expiráciu URL adries bez toho, aby niekedy ticho stratila fakturované generovanie. Táto lekcia pokrýva mechanizmy, ktoré robia rozdiel: klasifikácia chýb, stratégia opakovaných pokusov, architektúra frontu a pozorovateľnosť.
Dve rodiny chýb, dva okamihy
Prvá rodina sa objaví okamžite, v momente volania POST. Ide o striktné chyby požiadavky a na rozhodnutie, čo robiť, stačí kód HTTP.
| Kód HTTP | Príčina | Riešenie |
|---|---|---|
| 400 | Neplatné parametre (napríklad neznámy hlas v reference_audios) | Oprav požiadavku |
| 401 | Neplatný alebo expirovaný API kľúč | Over overenie totožnosti |
| 429 | Prekročený limit rýchlosti (požiadavky za sekundu, závisí od úrovne) | Implementuj oneskorenie (backoff) |
| 500 | Chyba servera | Opakuj s exponenciálnym oneskorením |
Druhá rodina sa prejaví oveľa neskôr, počas dotazovania (polling), potom, čo bola požiadavka prijatá a generovanie sa začalo.
| Stav | Pravdepodobná príčina | Akcia |
|---|---|---|
failed + invalid_argument alebo permission_denied | Požiadavka alebo obsah odmietnutý | Uprav prompt alebo zdroj |
failed + service_unavailable alebo internal_error | Preťažená služba, incident | Opakuj neskôr |
Toto rozlíšenie nie je akademické: kód 400 sa musí vrátiť volajúcemu okamžite, pretože chyba je v kóde, zatiaľ čo stav failed nastane po niekoľkých minútach čakania a musí sa riešiť v kontexte úlohy, nie v HTTP požiadavke, ktorá ju spustila.
Opakuj inteligentne
Spoločným základom je exponenciálne oneskorenie s určitým rozptylom (jitter). Zdvojnásobenie oneskorenia dá prechodnému incidentu čas na vyriešenie a rozptyl zabraňuje tomu, aby všetky tvoje procesy opakovali pokus v rovnakom okamihu po špičke — jav, ktorý mení mikrovýpadok na trvalé zlyhanie.
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)
Táto všeobecná schéma však nestačí, pretože nie všetky chyby si zaslúžia rovnakú trpezlivosť. Prekročenie kvóty sa vyrieši čakáním celej minúty; odmietnutie moderácie sa nikdy nevyrieši a opakovaný pokus znamená platiť viackrát za to isté zlyhanie. Nasledujúca funkcia rozlišuje tieto prípady.
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)
Front na udržanie tempa
Akonáhle tvoja služba začne prijímať požiadavky od viacerých používateľov, musíš oddeliť prijímanie požiadaviek od ich vykonávania a predovšetkým ohraničiť súbežnosť, aby si zostal pod limitom rýchlosti svojej úrovne. Front v kombinácii so semaforom spĺňa obe potreby: úlohy sa voľne hromadia, ale naraz sa vykonáva maximálne desať.
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)
}
Všimni si, že každá úloha si uchováva svoj výsledok v results, či už ide o úspech alebo zlyhanie: generovanie, ktoré zmizne bez stopy, je incident, ktorý nikto nedokáže diagnostikovať.
Druhým reflexom architektúry je ukladanie. Keďže URL adresy videí sú dočasné, sťahovanie musí byť automatické a okamžité, s pomenovaním podľa časovej pečiatky, ktoré zaručí, že nedôjde ku kolízii medzi dvoma simultánnymi generovaniami.
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
Over si kľúč skôr, než sa naň spoľahneš
Koncový bod GET /v1/api-key ťa informuje o stave tvojho kľúča. Jeho zavolanie pri štarte služby ti zabráni objaviť zablokovaný kľúč až po dvadsiatich neúspešných požiadavkách, zatiaľ čo tvoji používatelia čakajú.
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")
Vidieť, čo sa deje v produkcii
Na riadenie služby generovania videa stačí päť ukazovateľov. Miera úspešnosti, teda podiel generovaní končiacich stavom done, meria celkové zdravie systému. Priemerný čas generovania, meraný od odoslania po stav done, slúži na kalibráciu časových limitov a informovanie používateľov. Miera chýb rozdelená podľa typu — failed podľa kódu chyby, časový limit, limit rýchlosti — ti povie, kam sústrediť úsilie: nárast časových limitov bez nárastu failed signalizuje napríklad generovania pomalšie ako tvoja lehota čakania, nie zlyhania. Kumulatívne náklady, získané sčítaním poľa usage.cost_in_usd_ticks z každého výsledku (jeden dolár sa rovná 10 miliardám tikov), alebo alternatívne vynásobením vygenerovaných dĺžok cenou modelu za sekundu, sa musia sledovať denne. Nakoniec, využitie kvóty, v požiadavkách za sekundu vzhľadom na limit tvojej úrovne (10 v základnej úrovni pre video modely), predvídá nasýtenie skôr, než sa prejaví ako chyby 429.
Tieto metriky prirodzene vznikajú zo štruktúrovaného logu, kde každé generovanie zanechá riadok použiteľný pre tvoj analytický nástroj.
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
}))
Predtým, než otvoríš svoju službu verejnosti, prejdite si celé znova od začiatku. Exponenciálne oneskorenie s rozptylom pri opakovaných pokusoch musí byť nastavené a súbežnosť ohraničená semaforom, aby sa dodržal limit rýchlosti. Sťahovanie videí sa musí spustiť automaticky hneď, ako sú pripravené, bez závislosti na ľudskom zásahu. Každé generovanie musí zanechať riadok v logu nesúci svoje request_id, stav a náklady, inak zostane miera chýb a priemerný čas generovania overiteľné. Skontroluj stav API kľúča pri štarte, nie až pri prvom zlyhaní. A nastav rozpočet s alertmi pri prekročení: pri 0,05 $ za sekundu neobmedzená slučka opakovaných pokusov spotrebuje prostriedky rýchlejšie, než si myslíš.
Ceny overené 3. novembra 2026 — ceny sa pravidelne vyvíjajú: pred akýmkoľvek výpočtom rozpočtu si over aktuálny cenník na oficiálnej stránke modelov a cien xAI.
Kľúčové poznatky
- Chyby sa delia na synchronné (požiadavka) a asynchrónne (generovanie)
- Nie všetky chyby si zaslúžia opakovaný pokus: moderácia je definitívna
- Použi semafor na obmedzenie súbežných generovaní
- Dočasné URL adresy vyžadujú okamžité a systematické sťahovanie
- Sleduj metriky nákladov, úspešnosti a času generovania na riadenie svojej služby
Otestuj si svoje vedomosti
Generatívne video v produkcii: validuj celý pracovný postup.
1. Aké sú špecifiká promptu pre video?
Odpoveď: Opíš akciu a pohyb, nielen scénu: subjekt, premiestnenie, atmosféra, záber — časový rozmer je tým, čo odlišuje video prompt od obrazového promptu.
2. Čo umožňuje obraz-na-video?
Odpoveď: Animovať existujúci obrázok alebo vniesť daných ľudí a produkty do novej scény pomocou referenčných obrázkov — a na grok-imagine-video-1.5 pripnúť prvý, posledný alebo kľúčové obrázky: tvoja vizuálna identita sa stáva východiskovým bodom, nie náhodnou udalosťou.
3. Úpravy a rozšírenie: aké využitia?
Odpoveď: /videos/edits upravuje vygenerované video, /videos/extensions ho predlžuje — a obe sa kombinujú na budovanie dlhých sekvencií iteráciami.
4. Prečo je pracovný postup asynchrónny?
Odpoveď: Generovanie videa trvá čas: odošleš úlohu, zisťuješ jej stav a potom získaš výsledok — xAI SDK automatizuje toto zisťovanie stavu.
5. Na čo myslieť pri produkcii?
Odpoveď: Spracovanie chýb a zlyhané úlohy, okamžité sťahovanie výstupov a sledovanie nákladov (rozlíšenie, dĺžka, iterácie) — video je najdrahší mód: musí byť rozpočtované.
Časový prompt, vizuálna referencia, zvládnuté async: generatívne video sa stáva pipeline — nie lotériou.