Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Upravljanje greškama i deploy u produkciju

Lekcija 12 od 12 Ažurirano 3. studenoga 2026. Srednja razina
Na ovoj stranici
  1. Pripremi svoju aplikaciju za produkciju
  2. Dvije obitelji grešaka, dva trenutka
  3. Pametno ponavljaj pokušaje
  4. Red čekanja za održavanje tempa
  5. Provjeri svoj ključ prije oslanjanja na njega
  6. Vidjeti što se događa u produkciji
  7. Ključne točke
  8. Provjeri svoje znanje

Ažurirano 2. studenoga 2026. na temelju xAI video dokumentacije i koda xai-sdk 1.21.0: client.video.generate (ne client.videos), rezultat u url, neuspjesi prijavljeni putem VideoGenerationError s kodom (invalid_argument, service_unavailable…), ograničenje brzine primljeno kao grpc.RpcError s kodom RESOURCE_EXHAUSTED — klasa RateLimitError i status expired ne 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 iz usage.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 kodUzrokRješenje
400Neispravni parametri (npr. nepoznat glas u reference_audios)Ispravi zahtjev
401Neispravan ili istekao API ključProvjeri autentifikaciju
429Prekoračeno ograničenje brzine (zahtjevi po sekundi, ovisno o razini)Implementiraj povlačenje (backoff)
500Greška poslužiteljaPonovi s eksponencijalnim povlačenjem

Druga obitelj manifestira se znatno kasnije, tijekom anketiranja (polling), nakon što je zahtjev prihvaćen i generacija započela.

StatusVjerojatan uzrokRadnja
failed + invalid_argument ili permission_deniedZahtjev ili sadržaj odbijenIzmijeni prompt ili izvor
failed + service_unavailable ili internal_errorPreopterećenost servisa, incidentPonovi 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.