Pracovný postup asynchrónneho spracovania a zisťovania stavu
Na tejto strane
Aktualizované 2. novembra 2026. Na základe referencie xAI Video API: URL adresa sa nachádza v
video.url(nievideo_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.
Odoslanie požiadavky
POST na koncový bod generovania, úprav alebo rozšírenia. Okamžitá odpoveď s request_id.
Zisťovanie stavu (Polling)
GET /v1/videos/{request_id} v pravidelných intervaloch. Pole progress od 0 do 100.
Získanie výsledku
Keď je stav done (progress = 100), URL adresa videa je k dispozícii.
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
videoprítomného, keď je stavdone, 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_unavailablealebointernal_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
| Status | Progress | Význam |
|---|---|---|
pending | 0-99 | Generovanie prebieha |
done | 100 | Dokončené, URL k dispozícii |
failed | chýba | Generovanie 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