Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pracovný postup asynchrónneho spracovania a zisťovania stavu

Lekcia 10 z 12 Aktualizované 2. novembra 2026 Mierne pokročilý
Na tejto strane
  1. Pochopte životný cyklus videa
  2. Kontrola stavu generovania
  3. Tri stavy, tri akcie
  4. Implementácia zisťovania stavu (Polling)
  5. Nastavenie intervalu zisťovania stavu
  6. Kľúčové poznatky

Aktualizované 2. novembra 2026. Na základe referencie xAI Video API: URL adresa sa nachádza v video.url (nie video_url), generovanie má iba tri stavy (pending, done, failed, pričom posledný je sprevádzaný chybovým kódom) a obmedzenia rýchlosti sú vyjadrené v požiadavkách za sekundu na základe úrovne tímu. Zdroje: Video Generation · Videos Reference · Rate limits.

Pochopte životný cyklus videa

Všetky operácie s videom v xAI API sú asynchrónne a táto vlastnosť formuje architektúru vašej aplikácie viac, než by ste na prvý pohľad čakali. Volanie chatu alebo generovanie obrázka vráti výsledok okamžite; generovanie videa si však vyžaduje značný čas spracovania a vráti iba potvrdenie. Je na vás, aby ste implementovali sledovanie: pravidelne zisťujte stav úlohy, detegujte dokončenie a získajte súbor. Celý cyklus pozostáva zo štyroch krokov.

1

Odoslanie požiadavky

POST na koncový bod generovania, úprav alebo rozšírenia. Okamžitá odpoveď s request_id.

2

Zisťovanie stavu (Polling)

GET /v1/videos/{request_id} v pravidelných intervaloch. Pole progress od 0 do 100.

3

Získanie výsledku

Keď je stav done (progress = 100), URL adresa videa je k dispozícii.

4

Okamžité stiahnutie

URL adresa videa je dočasná. Stiahnite ju čo najskôr.

Kontrola stavu generovania

Sledovanie zahŕňa jednoduchú požiadavku GET na koncový bod stavu s použitím identifikátora prijatého pri odoslaní.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Odpoveď poskytuje nasledujúce užitočné informácie:

  • status : aktuálny stav generovania
  • progress : celé číslo od 0 do 100 označujúce priebeh
  • video.url : URL adresa videa, ktorá sa nachádza vo vnútri objektu video prítomného, keď je stav done, spolu s jeho dĺžkou (video.duration)
  • video.respect_moderation : booleovská hodnota označujúca, či obsah spĺňa pravidlá moderovania
  • error : v prípade zlyhania kód (invalid_argument, permission_denied, failed_precondition, service_unavailable alebo internal_error) a správa
  • usage.cost_in_usd_ticks : cena požiadavky v desatinásobných miliardtinách dolára

Pole progress si zaslúži poznámku: neriadi vašu riadiacu logiku, ktorá by sa mala vždy spoliehať na status, ale je zlatým baníkom pre používateľské rozhranie. Zobrazenie „62 %“ namiesto statického indikátora načítania úplne mení vnímanie čakania, ktoré môže trvať niekoľko minút.

Tri stavy, tri akcie

StatusProgressVýznam
pending0-99Generovanie prebieha
done100Dokončené, URL k dispozícii
failedchýbaGenerovanie zlyhalo

Pokiaľ je stav pending, generovanie pokračuje: jednoducho pokračujete v dotazovaní v pravidelných intervaloch a odovzdávate progress do vášho rozhrania. Keď sa prepne na done, video je pripravené a jediné, čo musíte urobiť, je prečítať video.url a súbor okamžite stiahnuť – tieto URL adresy sú dočasné a dokumentácia nešpecifikuje ich životnosť, čo zakazuje ich ukladanie do databázy na neskoršie použitie.

Nakoniec stav failed označuje zlyhanie produkcie a pole error vám povie, o aké zlyhanie ide. Rozdiel je dôležitý pre ďalší postup: service_unavailable (služba dočasne preťažená) alebo internal_error odôvodňujú neskorší opakovaný pokus, zatiaľ čo invalid_argument alebo permission_denied – zamietnutý prompt, neplatný zdrojový obrázok alebo video – si vyžadujú najprv opravu požiadavky. Python SDK navyše signalizuje chybou aj oneskorenú požiadavku, ktorá vypršala skôr, než bola získaná.

Implementácia zisťovania stavu (Polling)

Synchronná verzia sa zmestí do jednej funkcie. Cyklí až do vypršania časového limitu, predčasne ukončí pri zlyhaní vyvolaním jeho kódu a vráti URL adresu, hneď ako je video pripravené.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Čakanie na dokončenie generovania videa."""
    headers = {"Authorization": f"Bearer {api_key}"}
    debut = time.time()

    while time.time() - debut < timeout:
        resp = httpx.get(
            f"https://api.x.ai/v1/videos/{request_id}",
            headers=headers
        ).json()

        status = resp.get("status")
        progress = resp.get("progress", 0)

        if status == "done":
            return resp["video"]["url"]
        elif status == "failed":
            erreur = resp.get("error", {})
            raise RuntimeError(f"Generation failed [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"In progress... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Timeout after {timeout} seconds")

V službe spracovávajúcej viacero požiadaviek naraz sa táto blokujúca verzia stáva úzkym hrdlom: každé čakanie imobilizuje vlákno na minúty. Asynchrónny prepis uvoľňuje slučku udalostí medzi dotazmi a umožňuje vám sledovať desiatky generovaní paralelne.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchrónna verzia zisťovania stavu."""
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        debut = asyncio.get_event_loop().time()

        while asyncio.get_event_loop().time() - debut < timeout:
            resp = await client.get(
                f"https://api.x.ai/v1/videos/{request_id}",
                headers=headers
            )
            data = resp.json()

            if data["status"] == "done":
                return data["video"]["url"]
            elif data["status"] == "failed":
                raise RuntimeError(f"Generation failed : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Timeout")

Nastavenie intervalu zisťovania stavu

Výber intervalu predstavuje vyváženie medzi odozvou a plytvaním požiadavkami. Päť sekúnd je vo väčšine prípadov dobrým kompromisom. Pri dlhých generovaniach – desať až pätnásť sekúnd videa – stačí desať až pätnásť sekúnd medzi jednotlivými dotazmi, čo znižuje premávku. Naopak, interaktívna aplikácia, kde používateľ sleduje indikátor priebehu, odôvodňuje zníženie na dve alebo tri sekundy. Pod jednu sekundu však nič nezrýchlite: generovanie postupuje vlastným tempom a vy len zbytočne znásobujete požiadavky.

Kľúčové poznatky

  • Všetky operácie s videom sú asynchrónne: POST na odoslanie, GET na získanie
  • Tri možné stavy: pending, done, failed (s chybovým kódom)
  • Pole progress (0-100) vám umožňuje sledovať postup
  • Implementujte časový limit a interval zisťovania stavu prispôsobený vášmu prípadu použitia
  • URL adresy videí sú dočasné: stiahnite ich okamžite