Munkafolyamat aszinkron módon és lekérdezés (polling)
Ezen az oldalon
Frissítve: 2026. november 2. Az xAI Video API referenciája alapján: az URL a
video.urlmezőben található (nem avideo_url-ban), egy generálásnak csak három állapota lehet (pending,done,failed, utóbbit hiba kód kíséri), a sebességkorlátok pedig a csapat szintje alapján másodpercenkénti kérésszámban vannak megadva. Források: Videógenerálás · Videók referenciája · Sebességkorlátok.
Értsd meg a videó életciklusát
Az xAI API összes videóművelete aszinkron, és ez a tulajdonság jobban meghatározza az alkalmazásod architektúráját, mint azt elsőre gondolnád. Egy csevegési hívás vagy képgenerálás azonnal eredményt ad; a videógenerálás viszont jelentős feldolgozási időt igényel, és csak egy visszaigazolást küld vissza. Rajtad múlik a nyomon követés megvalósítása: időszakosan lekérdezed a feladat állapotát, észleled a befejezést, majd letöltöd a fájlt. A teljes ciklus négy lépésből áll.
Kérés beküldése
POST kérés a generálási, szerkesztési vagy bővítési végpontra. Azonnali válasz egy request_id azonosítóval.
Állapot lekérdezése (Polling)
GET /v1/videos/{request_id} rendszeres időközönként. A progress mező 0-tól 100-ig változik.
Eredmény lekérése
Ha az állapot done (progress = 100), a videó URL elérhetővé válik.
Azonnali letöltés
A videó URL ideiglenes. A lehető leghamarabb töltsd le.
Generálási állapot ellenőrzése
A nyomon követés egy egyszerű GET kérést jelent az állapot végponton, a beküldéskor kapott azonosító felhasználásával.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
A válasz a következő hasznos információkat tartalmazza:
- status : a generálás aktuális állapota
- progress : 0 és 100 közötti egész szám, amely a folyamatot jelzi
- video.url : a videó URL-je, amely a
videoobjektumban található, amikor az állapotdone, a hosszával együtt (video.duration) - video.respect_moderation : logikai érték, amely jelzi, hogy a tartalom megfelel-e a moderációs irányelveknek
- error : hiba esetén egy kód (
invalid_argument,permission_denied,failed_precondition,service_unavailablevagyinternal_error) és egy üzenet - usage.cost_in_usd_ticks : a kérés költsége, tízmilliárdod dollárban kifejezve
A progress mező külön megjegyzést érdemel: nem ez vezérli a vezérlési logikádat, amelynek mindig a status-ra kell támaszkodnia, de aranyat ér a felhasználói felület számára. Ha „62%“-ot látsz egy statikus töltőikon helyett, az teljesen megváltoztatja a több percig is eltartható várakozás érzékelését.
Három állapot, három művelet
| Állapot | Haladás (Progress) | Jelentés |
|---|---|---|
pending | 0-99 | Generálás folyamatban |
done | 100 | Befejezve, URL elérhető |
failed | nincs | Generálás sikertelen |
Amíg az állapot pending, a generálás folytatódik: egyszerűen folytatod a lekérdezéseket rendszeres időközönként, és továbbítod a progress értéket a felületednek. Amikor az állapot done-ra vált, a videó kész, és nincs más dolgod, mint kiolvasni a video.url-t, és azonnal letölteni a fájlt – ezek az URL-ek ideiglenesek, és a dokumentáció nem határozza meg az élettartamukat, ami kizárja, hogy későbbi felhasználás céljából adatbázisban tárold őket.
Végül a failed állapot gyártási hibát jelez, és az error mező megmondja, melyiket. A megkülönböztetés fontos a továbbiak szempontjából: a service_unavailable (a szolgáltatás ideiglenesen túlterhelt) vagy az internal_error indokolttá teszi a későbbi újrapróbálkozást, míg az invalid_argument vagy a permission_denied – elutasított prompt, érvénytelen forráskép vagy videó – először a kérés kijavítását igényli. A Python SDK egyébként hibával jelzi azt az elhalasztott kérést is, amely lejárt, mielőtt lekérték volna.
Polling megvalósítása
A szinkron verzió egyetlen függvénybe fér el. Addig ciklizik, amíg az időtúllépés be nem következik, hiba esetén a hibakód dobásával lép ki, és amint a videó kész, visszaadja az URL-t.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Wait for video generation completion."""
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")
Egy egyszerre több kérést kezelő szolgáltatásban ez a blokkoló verzió szűk keresztmetszetté válik: minden várakozás percekre lefoglal egy szálat. Az aszinkron változat felszabadítja az eseményhurkot a lekérdezések között, és lehetővé teszi tucatnyi generálás párhuzamos nyomon követését.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asynchronous version of polling."""
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")
A lekérdezési időköz beállítása
Az időköz megválasztása egyensúlyt teremt a reagálóképesség és a felesleges kérések között. Öt másodperc a legtöbb esetben jó kompromisszum. Hosszú generálásoknál – tíz-tizenöt másodperces videók – a tíz-tizenöt másodperces lekérdezési időköz is elegendő, és csökkenti a forgalmat. Ezzel szemben egy interaktív alkalmazásnál, ahol a felhasználó egy folyamatjelző sávot figyel, indokolt lehet két-három másodpercre csökkenteni az időt. Egy másodperc alatt azonban semmit sem gyorsítasz fel: a generálás a saját tempójában halad, és csak feleslegesen szorzod meg a kérések számát.
Főbb megállapítások
- Minden videóművelet aszinkron: POST a beküldéshez, GET a lekéréshez
- Három lehetséges állapot: pending, done, failed (hibakóddal)
- A
progressmező (0-100) lehetővé teszi a haladás nyomon követését - Implementálj időtúllépést és az esetedhez igazított lekérdezési időközt
- A videó URL-ek ideiglenesek: töltsd le őket azonnal