Delovni tok v asinhronem načinu in periodično preverjanje stanja
Na tej strani
Posodobljeno 2. novembra 2026. Na podlagi referenčne dokumentacije za xAI Video API: URL je na voljo v polju
video.url(nevideo_url), generiranje ima le tri stanja (pending,done,failed, pri čemer je zadnje povezano s kodo napake), omejitve hitrosti pa so izražene kot število zahtev na sekundo glede na raven ekipe. Viri: Video Generation · Videos Reference · Rate limits.
Razumevanje življenjskega cikla videoposnetka
Vse operacije z videoposnetki v API-ju xAI so asinhrone, kar bistveno bolj vpliva na arhitekturo tvoje aplikacije, kot bi morda sprva pričakoval. Klic klepetalnega bota ali generiranje slike vrne rezultat takoj; generiranje videoposnetka pa zahteva znaten čas obdelave in vrne le potrdilo o prejemu. Tvoja naloga je implementirati sledenje: redno preverjaj stanje opravila, zaznaj zaključek in pridobi datoteko. Celoten cikel je sestavljen iz štirih korakov.
Pošlji zahtevo
POST na končno točko za generiranje, urejanje ali podaljšanje. Takojšen odgovor z request_id.
Preveri stanje (Polling)
GET /v1/videos/{request_id} v rednih intervalih. Polje progress se spreminja od 0 do 100.
Pridobi rezultat
Ko je status done (progress = 100), je URL videoposnetka na voljo.
Takojšnji prenos
URL videoposnetka je začasen. Prenesi ga čim prej.
Preverjanje stanja generiranja
Sledenje vključuje preprosto zahtevo GET do končne točke za stanje, pri čemer uporabiš identifikator, prejet ob oddaji.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Odgovor razkriva naslednje uporabne informacije:
- status : trenutno stanje generiranja
- progress : celo število od 0 do 100, ki označuje napredek
- video.url : URL videoposnetka, ki se nahaja znotraj objekta
video, prisotnega, ko je statusdone, skupaj s trajanjem (video.duration) - video.respect_moderation : boolova vrednost, ki označuje, ali je vsebina skladna s pravilniki o moderiranju
- error : v primeru napake koda (
invalid_argument,permission_denied,failed_precondition,service_unavailablealiinternal_error) in sporočilo - usage.cost_in_usd_ticks : strošek zahteve, izražen v desetmilijardinkah dolarja
Polje progress si zasluži opombo: ne določa tvoje nadzorne logike, ki se mora vedno zanašati na status, je pa zlato za uporabniški vmesnik. Prikaz „62 %” namesto statičnega indikatorja nalaganja popolnoma spremeni dojemanje čakanja, ki lahko traja več minut.
Tri stanja, tri dejanja
| Status | Progress | Pomen |
|---|---|---|
pending | 0-99 | Generiranje v teku |
done | 100 | Zaključeno, URL na voljo |
failed | odsotno | Generiranje ni uspelo |
Dokler je status pending, generiranje poteka: preprosto nadaljuj z rednim poizvedovanjem in posreduj vrednost progress svojemu vmesniku. Ko se status spremeni v done, je videoposnetek pripravljen in edino, kar moraš storiti, je prebrati video.url ter datoteko takoj prenesti – ti URL-ji so začasni, dokumentacija pa ne določa njihove življenjske dobe, kar prepoveduje njihovo shranjevanje v zbirko podatkov za kasnejšo uporabo.
Končno status failed označuje napako pri izdelavi, polje error pa ti pove, katera. Razlika je pomembna za nadaljnje korake: service_unavailable (storitev začasno preobremenjena) ali internal_error upravičujeta ponovni poskus kasneje, medtem ko invalid_argument ali permission_denied – zavrnjen poziv, neveljavna izvorna slika ali videoposnetek – zahtevata najprej popravek zahteve. Python SDK medtem z napako signalizira tudi odloženo zahtevo, ki je potekla, preden je bila pridobljena.
Implementacija periodičnega preverjanja (Polling)
Sinhrona različica se prilega v eno samo funkcijo. Izvaja zanko do poteka časovne omejitve, se predčasno konča ob napaki z dvigom njene kode in vrne URL, takoj ko je videoposnetek pripravljen.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Počakaj na zaključek generiranja videoposnetka."""
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"Generiranje ni uspelo [{erreur.get('code')}] : {erreur.get('message')}")
print(f"V teku... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Časovna omejitev po {timeout} sekundah")
V storitvi, ki hkrati obravnava več zahtev, ta blokirajoča različica postane ozko grlo: vsako čakanje imobilizira nit za minute. Asinhrona preslikava sprosti zanko dogodkov med poizvedbami in ti omogoča sledenje desetinam generiranj vzporedno.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asinhrona različica periodičnega preverjanja."""
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"Generiranje ni uspelo : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Časovna omejitev")
Nastavitev intervala preverjanja
Izbira intervala uravnava ravnovesje med odzivnostjo in nepotrebnimi zahtevami. Pet sekund je v večini primerov dober kompromis. Za dolga generiranja – deset do petnajst sekund videoposnetka – je deset do petnajst sekund med posameznimi preverjanji povsem dovolj in zmanjša promet. Nasprotno pa interaktivna aplikacija, kjer uporabnik opazuje vrstico napredka, upraviči zmanjšanje na dve ali tri sekunde. Pod eno sekundo pa ne boš pospešil ničesar: generiranje poteka v svojem tempu, ti pa le množiš število zahtev brez potrebe.
Ključne ugotovitve
- Vse operacije z videoposnetki so asinhrone: POST za oddajo, GET za pridobitev
- Tri možna stanja: pending, done, failed (s kodo napake)
- Polje
progress(0–100) ti omogoča sledenje napredku - Implementiraj časovno omejitev in interval preverjanja, prilagojen tvoji uporabi
- URL-ji videoposnetkov so začasni: prenosi jih takoj