Zpracování chyb a nasazení do produkce
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace videa od xAI a kódu
xai-sdk1.21.0:client.video.generate(nikoliclient.videos), výsledek vurl, selhání hlášena pomocíVideoGenerationErrors kódem (invalid_argument,service_unavailable…), omezení rychlosti přijato jakogrpc.RpcErrors kódemRESOURCE_EXHAUSTED— třídaRateLimitErrora stavexpiredneexistují. Doplněk z 3. listopadu 2026: omezení rychlosti počítá požadavky za sekundu (10 u vstupní úrovně), nikoli „60 RPM“, a skutečné náklady na generaci se čtou zusage.cost_in_usd_ticks. Zdroje: Generování videa · Omezení rychlosti.
Připrav svou aplikaci na produkci
Skript, který generuje video na tvém stroji, a služba, která vyrábí stovky videí denně pro skutečné uživatele, nemají téměř nic společného. Ta druhá musí zvládat odmítnutí moderací, překročení kvót, výpadky serverů a expiraci URL adres, aniž by kdy mlčky ztratila zpoplatněnou generaci. Tato lekce pokrývá mechanismy, které dělají rozdíl: klasifikace chyb, strategie opakování, architektura fronty a pozorovatelnost.
Dvě rodiny chyb, dva okamžiky
První rodina se objeví okamžitě, v momentě volání POST. Jde o striktní chyby požadavku a kód HTTP stačí k rozhodnutí, co dělat.
| Kód HTTP | Příčina | Řešení |
|---|---|---|
| 400 | Neplatné parametry (například neznámý hlas v reference_audios) | Oprav požadavek |
| 401 | Neplatný nebo expirovaný klíč API | Ověř autentizaci |
| 429 | Překročeno omezení rychlosti (požadavky za sekundu, závisí na úrovni) | Implementuj backoff |
| 500 | Chyba serveru | Opakuj s exponenciálním backoffem |
Druhá rodina se projeví mnohem později, během dotazování (polling), poté, co byl požadavek přijat a generování začalo.
| Stav | Pravděpodobná příčina | Akce |
|---|---|---|
failed + invalid_argument nebo permission_denied | Požadavek nebo obsah odmítnut | Uprav prompt nebo zdroj |
failed + service_unavailable nebo internal_error | Přetížená služba, incident | Opakuj později |
Toto rozlišení není akademické: chyba 400 se musí okamžitě vrátit volajícímu, protože chyba je v kódu, zatímco stav failed nastane po několika minutách čekání a musí být zpracován v kontextu úlohy, nikoli v HTTP požadavku, který ji spustil.
Opakuj chytře
Společným základem je exponenciální backoff s určitým jitterem. Zdvojnásobení prodlevy dá přechodnému incidentu čas na vyřešení a jitter zabrání tomu, aby všechny tvé procesy opakovaly pokus ve stejný okamžik po špičce — jev, který mění mikrovýpadek v trvalé selhání.
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)
Tento obecný schéma však nestačí, protože ne všechny chyby si zaslouží stejnou trpělivost. Překročení kvóty se vyřeší čekáním celou minutu; odmítnutí moderací se nikdy nevyřeší a opakování znamená platit mnohokrát za stejné selhání. Následující funkce rozlišuje tyto případy.
import asyncio
from datetime import timedelta
import grpc
from xai_sdk.video import VideoGenerationError
# Kódy selhání, které opakování neopraví
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)
Fronta pro udržení tempa
Jakmile tvoje služba začne přijímat požadavky od více uživatelů, musíš oddělit přijímání požadavků od jejich执行 a především omezit souběžnost, abys zůstal pod limitem rychlosti své úrovně. Fronta spárovaná se semaforem splňuje obě potřeby: úlohy se libovolně hromadí, ale najednou běží maximálně deset.
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ává svůj výsledek v results, ať už úspěch nebo selhání: generace, která zmizí bez stopy, je incident, který nikdo nedokáže diagnostikovat.
Druhým reflexem architektury je úložiště. Protože jsou URL adresy videí dočasné, stahování musí být automatické a okamžité, s pojmenováním podle časového razítka, které zaručí žádnou kolizi mezi dvěma současnými generacemi.
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
Ověř svůj klíč, než se na něj spolehneš
Koncový bod GET /v1/api-key tě informuje o stavu tvého klíče. Jeho zavolání při startu služby ti zabrání objevit zablokovaný klíč až po dvaceti neúspěšných požadavcích, zatímco tvoji uživatelé čekají.
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")
Vidět, co se děje v produkci
Pět ukazatelů stačí k řízení služby pro generování videa. Míra úspěšnosti, tedy podíl generací končících stavem done, měří celkové zdraví. Průměrná doba generování, měřená mezi odesláním a stavem done, slouží ke kalibraci tvých časových limitů a informování uživatelů. Míra chyb rozdělená podle typu — failed podle kódu chyby, časový limit, omezení rychlosti — ti říká, kam soustředit úsilí: nárůst časových limitů bez nárůstu failed signalizuje například generace pomalejší než tvůj čekací deadline, nikoli selhání. Kumulativní náklady, získané sečtením pole usage.cost_in_usd_ticks z každého výsledku (jeden dolar se rovná 10 miliardám tiků), nebo alternativně vynásobením vygenerovaných délek cenou modelu za sekundu, musí být sledovány denně. Nakonec využití kvóty, v požadavcích za sekundu vůči limitu tvé úrovně (10 u vstupní úrovně pro video modely), předvídá nasycení dříve, než se projeví jako chyby 429.
Tyto metriky přirozeně vznikají ze strukturovaného logu, kde každá generace zanechá řádek použitelný pro tvůj 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
}))
Než otevřeš svou službu veřejnosti, zkontroluj vše od začátku. Opakování s exponenciálním backoffem a jitterem musí být na místě a souběžnost omezena semaforem, aby zůstala pod limitem rychlosti. Stahování videí se musí spustit automaticky, jakmile jsou připravena, bez závislosti na lidském zásahu. Každá generace musí zanechat řádek v logu nesoucí své request_id, stav a náklady, jinak míra chyb a průměrná doba generování zůstanou neověřitelné. Zkontroluj stav klíče API při startu, nikoli až při prvním selhání. A nastav rozpočet s alerty při překročení: při 0,05 $ za sekundu spotřebuje neomezená smyčka opakování peníze rychleji, než si myslíš.
Ceny ověřeny 3. listopadu 2026 — ceny se pravidelně vyvíjejí: před jakýmkoli výpočtem rozpočtu ověř aktuální ceník na oficiální stránce modelů a cen xAI.
Klíčové poznatky
- Chyby se dělí na synchronní (požadavek) a asynchronní (generování)
- Ne všechny chyby si zaslouží opakování: moderace je definitivní
- Použij semafor k omezení souběžných generací
- Dočasné URL vyžadují okamžité a systematické stahování
- Sleduj metriky nákladů, úspěšnosti a doby generování pro řízení své služby
Ověř své znalosti
Generativní video v produkci: validuj celý pracovní postup.
1. Jaké jsou zvláštnosti video promptu?
Odpověď: Popiš akci a pohyb, nejen scénu: subjekt, přesun, atmosféra, záběr — časová dimenze je tím, co odlišuje video prompt od obrazového promptu.
2. Co umožňuje image-to-video?
Odpověď: Animovat existující obrázek nebo vložit dané lidi a produkty do nové scény pomocí referenčních obrázků — a na grok-imagine-video-1.5 připnout první, poslední nebo klíčové snímky: tvá vizuální identita se stává výchozím bodem, nikoli náhodnou událostí.
3. Úpravy a rozšíření: jaká využití?
Odpověď: /videos/edits upravuje vygenerované video, /videos/extensions jej prodlužuje — a obojí se kombinuje k budování dlouhých sekvencí iteracemi.
4. Proč je pracovní postup asynchronní?
Odpověď: Generování videa trvá čas: odešleš úlohu, dotazuješ se na její stav a poté získáš výsledek — SDK xAI toto dotazování automatizuje.
5. Co plánovat pro produkci?
Odpověď: Zpracování chyb a selhané úlohy, okamžité stažení výstupů a sledování nákladů (rozlišení, délka, iterace) — video je nejdražší modalita: musí být rozpočtováno.
Časový prompt, vizuální reference, zvládnutá asynchronita: generativní video se stává pipeline — ne loterií.