Asünkroonne töövoog ja päringute tegemine
Sellel lehel
Uuendatud 2. novembril 2026. Lähtudes xAI Video API dokumentatsioonist: URL asub väljal
video.url(mittevideo_url), genereerimisel on ainult kolm olekut (pending,done,failed, viimasega kaasneb veakood) ja kiirusepiirangud on väljendatud päringutes sekundis sõltuvalt meeskonna tasemest. Allikad: Video Generation · Videos Reference · Rate limits.
Mõista video elutsüklit
Kõik xAI API videooperatsioonid on asünkroonsed ja see omadus mõjutab sinu rakenduse arhitektuuri rohkem, kui esmapilgul arvata oskad. Vestluskõne või pildigeneratsioon tagastab tulemuse koheselt; videogeneerimine nõuab aga märkimisväärset töötlemisaega ja tagastab vaid kinnituse. Sinu ülesandeks on rakendada jälgimine: küsida perioodiliselt ülesande olekut, tuvastada lõpetamine ja fail kätte saada. Täielik tsükkel koosneb neljast sammust.
Saada päring
POST-päring genereerimise, redigeerimise või pikendamise lõpppunkti. Kohene vastus koos request_id-ga.
Küsi olekut
GET /v1/videos/{request_id} regulaarsete ajavahemike järel. Väli progress muutub 0-lt 100-le.
Hangi tulemus
Kui olek on done (progress = 100), on video URL kättesaadav.
Laadi kohe alla
Video URL on ajutine. Laadi see alla nii kiiresti kui võimalik.
Kontrolli genereerimise olekut
Jälgimine hõlmab lihtsat GET-päringut oleku lõpppunkti, kasutades saatmisel saadud identifikaatorit.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Vastus sisaldab järgmist kasulikku teavet:
- status : praegune genereerimise olek
- progress : täisarv 0-st 100-ni, mis näitab edenemist
- video.url : video URL, asub objektis
video, mis on olemas, kui olek ondone, koos kestusega (video.duration) - video.respect_moderation : boolväärtus, mis näitab, kas sisu vastab moderatsioonipoliitikale
- error : ebaõnnestumise korral kood (
invalid_argument,permission_denied,failed_precondition,service_unavailablevõiinternal_error) ja sõnum - usage.cost_in_usd_ticks : päringu maksumus, väljendatuna dollari kümnemiljardikosades
Väli progress väärib märkimist: see ei juhi sinu juhtimisloogikat, mis peaks alati tuginema väljale status, kuid on kasutajaliidese jaoks kullaväärtusega. „62%“ kuvamine staatilise laadimisikooni asemel muudab täielikult mitu minutit kestva oote tajumist.
Kolm olekut, kolm tegevust
| Olek | Progress | Tähendus |
|---|---|---|
pending | 0-99 | Genereerimine pooleli |
done | 100 | Lõpetatud, URL kättesaadav |
failed | puudub | Genereerimine ebaõnnestus |
Seni kuni olek on pending, genereerimine jätkub: sa lihtsalt küsid seda regulaarsete ajavahemike järel, edastades progress väärtuse oma liidesesse. Kui olek muutub done-iks, on video valmis ja ainus, mida teha tuleb, on lugeda video.url ja laadida fail koheselt alla – need URL-id on ajutised ja dokumentatsioon ei täpsusta nende kehtivusaega, mis välistab nende hilisemaks kasutamiseks andmebaasi salvestamise.
Lõpuks näitab olek failed tootmisviga ja väli error ütleb, milline see on. Erinevus on oluline edasiste sammude jaoks: service_unavailable (teenus ajutiselt ülekoormatud) või internal_error õigustavad hilisemat uuesti proovimist, samas kui invalid_argument või permission_denied – tagasilükatud vihje, vigane lähtepilt või video – nõuavad esmalt päringu parandamist. Pythoni SDK annab omakorda vea kaudu märku ka edasilükatud päringust, mille aegumistähtaeg enne kättesaamist möödus.
Rakenda päringute tegemine (polling)
Sünkroonne versioon mahub ühte funktsiooni. See teeb tsükli kuni aegumiseni, väljub ebaõnnestumisel varakult, visates vastava koodi, ja tagastab URL-i niipea, kui video on valmis.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Oota video genereerimise lõpetamist."""
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")
Teenuses, mis haldab korraga mitut päringut, muutub see blokeeriv versioon pudelikaelaks: iga ootamine immobiliseerib lõime minutiteks. Asünkroonne teisendus vabastab sündmuste tsükli päringute vahel ja võimaldab jälgida kümneid genereerimisi paralleelselt.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Päringute tegemise asünkroonne versioon."""
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")
Määra päringute intervall
Intervalli valik tasakaalustab reageerimisvõimet ja raisatud päringute arvu. Viis sekundit on enamikul juhtudel hea kompromiss. Pikkade genereerimiste puhul – kümne kuni viieteistkümne sekundi pikkune video – piisab kümne kuni viieteistkümne sekundi pikkustest intervallidest, mis vähendab liiklust. Vastupidi, interaktiivses rakenduses, kus kasutaja jälgib edenemisriba, on mõistlik lühendada intervalli kahe või kolme sekundini. Alla ühe sekundi minnes aga midagi kiiremaks ei muuda: genereerimine kulgeb oma tempos ja sa ainult korrutad asjatult päringute arvu.
Peamised punktid
- Kõik videooperatsioonid on asünkroonsed: POST saatmiseks, GET tulemuse hankimiseks
- Kolm võimalikku olekut: pending, done, failed (koos veakoodiga)
- Väli
progress(0–100) võimaldab jälgida edenemist - Rakenda aegumistähtaeg ja sinu kasutusjuhtumile sobiv päringute intervall
- Video URL-id on ajutised: laadi need koheselt alla