Upravljanje greškama i deploy u produkciju
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju xAI video dokumentacije i koda
xai-sdk1.21.0:client.video.generate(neclient.videos), rezultat uurl, neuspjesi prijavljeni putemVideoGenerationErrors kodom (invalid_argument,service_unavailable…), ograničenje brzine primljeno kaogrpc.RpcErrors kodomRESOURCE_EXHAUSTED— klasaRateLimitErrori statusexpiredne postoje. Dodatak 3. studenoga 2026.: ograničenje brzine broji zahtjeve po sekundi (10 na ulaznoj razini), a ne “60 RPM”, a stvarni trošak po generaciji očituje se izusage.cost_in_usd_ticks. Izvori: Video Generation · Rate limits.
Pripremi svoju aplikaciju za produkciju
Skripta koja generira video na tvojem računalu i servis koji proizvodi stotine videa dnevno za stvarne korisnike nemaju gotovo ništa zajedničko. Potonji mora rukovati odbijanjima moderacije, premašenjima kvota, incidentima na poslužitelju i istjecanjem URL-ova, a da pritom nikada tiho ne izgubi naplaćenu generaciju. Ova lekcija pokriva mehanizme koji čine razliku: klasifikacija grešaka, strategija ponovnih pokušaja, arhitektura reda čekanja i opservabilnost.
Dvije obitelji grešaka, dva trenutka
Prva obitelj pojavljuje se odmah, u trenutku POST poziva. To su stroge greške zahtjeva, a HTTP kod dovoljan je za odluku što učiniti.
| HTTP kod | Uzrok | Rješenje |
|---|---|---|
| 400 | Neispravni parametri (npr. nepoznat glas u reference_audios) | Ispravi zahtjev |
| 401 | Neispravan ili istekao API ključ | Provjeri autentifikaciju |
| 429 | Prekoračeno ograničenje brzine (zahtjevi po sekundi, ovisno o razini) | Implementiraj povlačenje (backoff) |
| 500 | Greška poslužitelja | Ponovi s eksponencijalnim povlačenjem |
Druga obitelj manifestira se znatno kasnije, tijekom anketiranja (polling), nakon što je zahtjev prihvaćen i generacija započela.
| Status | Vjerojatan uzrok | Radnja |
|---|---|---|
failed + invalid_argument ili permission_denied | Zahtjev ili sadržaj odbijen | Izmijeni prompt ili izvor |
failed + service_unavailable ili internal_error | Preopterećenost servisa, incident | Ponovi kasnije |
Ova razlika nije akademska: 400 mora trenutno vratiti pozivatelju jer je greška u kodu, dok se status failed događa nakon nekoliko minuta čekanja i mora se obraditi u kontekstu zadatka, a ne u HTTP zahtjevu koji ga je pokrenuo.
Pametno ponavljaj pokušaje
Zajednička baza je eksponencijalno povlačenje (exponential backoff) s određenim nasumičnim kašnjenjem (jitter). Udvostručenje kašnjenja daje prolaznom incidentu vremena da se riješi, a nasumičnost sprječava da svi tvoji procesi ponove pokušaj u istom trenutku nakon skoka — fenomen koji mikro-prekid pretvara u trajni kvar.
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)
Ova opća shema ipak nije dovoljna jer ne zaslužuju sve greške istu razinu strpljenja. Prekoračenje kvote rješava se čekanjem pune minute; odbijanje moderacije nikada se neće riješiti, a ponavljanje pokušaja znači plaćanje više puta za isti neuspjeh. Sljedeća funkcija razlikuje slučajeve.
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)
Red čekanja za održavanje tempa
Čim tvoj servis počne primati zahtjeve od više korisnika, moraš odvojiti prihvat zahtjeva od izvršenja i, prije svega, ograničiti konkurentnost kako bi ostao unutar ograničenja brzine svoje razine. Red čekanja uparen sa semaforom zadovoljava obje potrebe: zadaci se slobodno gomilaju, ali najviše deset ih se izvršava istovremeno.
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)
}
Imaj na umu da svaki zadatak čuva svoj ishod u results, bilo uspjeh ili neuspjeh: generacija koja nestane bez traga incident je koji nitko ne može dijagnosticirati.
Drugi refleks arhitekture tiče se pohrane. Budući da su video URL-ovi privremeni, preuzimanje mora biti automatsko i trenutno, s imenovanjem označenim vremenskom oznakom koje jamči da neće doći do sudara između dviju istovremenih generacija.
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
Provjeri svoj ključ prije oslanjanja na njega
Krajnja točka GET /v1/api-key informira te o stanju tvog ključa. Pozivanjem ove točke pri pokretanju servisa izbjegavaš otkrivanje blokiranog ključa nakon dvadeset neuspjelih zahtjeva, dok tvoji korisnici čekaju.
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")
Vidjeti što se događa u produkciji
Pet indikatora dovoljno je za vođenje servisa za generiranje videa. Stopa uspješnosti, odnosno udio generacija koje završe s done, mjeri opće zdravlje sustava. Prosječno vrijeme generiranja, mjereno između podnošenja i statusa done, služi za kalibraciju vremenskih ograničenja i informiranje korisnika. Stopa grešaka raščlanjena po vrsti — failed po kodu greške, istek vremena, ograničenje brzine — govori ti gdje usmjeriti napore: porast isteka vremena bez porasta failed signalizira generacije sporije od tvog roka čekanja, na primjer, a ne neuspjehe. Kumulativni trošak, dobiven zbrajanjem polja usage.cost_in_usd_ticks iz svakog rezultata (jedan dolar jednak je 10 milijardi tickova), ili alternativno množenjem generiranih trajanja s cijenom modela po sekundi, mora se pratiti svakodnevno. Konačno, korištenje kvote, u zahtjevima po sekundi u odnosu na ograničenje tvoje razine (10 na ulaznoj razini za video modele), anticipira zasićenje prije nego što se ono pretvori u 429 greške.
Ove se metrike prirodno grade iz strukturiranog zapisa (loga), gdje svaka generacija ostavlja redak upotrebljiv za tvoj alat za analizu.
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
}))
Prije nego što otvoriš svoj servis za javnost, pregledaj cijeli proces od početka. Ponovni pokušaji s eksponencijalnim povlačenjem i nasumičnim kašnjenjem moraju biti na mjestu, a konkurentnost ograničena semaforom kako bi se ostalo unutar ograničenja brzine. Preuzimanja videa moraju se okinuti automatski čim budu spremna, bez oslanjanja na ljudsku akciju. Svaka generacija mora ostaviti redak zapisa koji nosi svoj request_id, status i trošak; u suprotnom, stopa grešaka i prosječno vrijeme generiranja ostat će neprovjerljivi. Provjeri stanje API ključa pri pokretanju, a ne tek pri prvom neuspjehu. I postavi proračun s upozorenjima o prekoračenju: pri 0,05 USD po sekundi, neograničena petlja ponovnih pokušaja troši brže nego što misliš.
Cijene verificirane 3. studenoga 2026. — cijene se redovito mijenjaju: prije bilo kakvog izračuna proračuna, provjeri trenutnu tarifu na službenoj stranici xAI modela i cijena.
Ključne točke
- Greške se dijele na sinkrone (zahtjev) i asinkrone (generacija)
- Ne zaslužuju sve greške ponovni pokušaj: moderacija je konačna
- Koristi semafor za ograničavanje istovremenih generacija
- Privremeni URL-ovi zahtijevaju trenutno i sustavno preuzimanje
- Prati metrike troška, uspješnosti i vremena generiranja za vođenje svog servisa
Provjeri svoje znanje
Generativni video u produkciji: validiraj cijeli radni tijek.
1. Koje su posebnosti video prompta?
Odgovor: Opiši radnju i pokret, a ne samo scenu: subjekt, pomicanje, atmosfera, kadrovanje — vremenska dimenzija je ono što razlikuje video prompt od prompta za sliku.
2. Što omogućuje image-to-video?
Odgovor: Animiranje postojeće slike ili unošenje određenih ljudi i proizvoda u novu scenu koristeći referentne slike — te, na grok-imagine-video-1.5, fiksiranje prve, zadnje ili ključnih slika: tvoj vizualni identitet postaje polazište, a ne slučajnost.
3. Uređivanje i proširenje: koje uporabe?
Odgovor: /videos/edits modificira generirani video, /videos/extensions ga produžuje — a oboje se kombinira za izgradnju dugih sekvencija iteracijama.
4. Zašto je radni tijek asinkron?
Odgovor: Generiranje videa traje: podnosiš zadatak, anketiraš njegov status, zatim dohvaćaš rezultat — xAI SDK automatizira ovo anketiranje.
5. Što planirati za produkciju?
Odgovor: Rukovanje greškama i neuspjelim zadacima, trenutno preuzimanje izlaza i praćenje troškova (rezolucija, trajanje, iteracije) — video je najskuplji modalitet: mora se budžetirati.
Vremenski prompt, vizualna referenca, savladan asinkroni tijek: generativni video postaje cjevovod — a ne lutrija.