Darbo eiga asinchroniniu režimu ir apklausa
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. Remiantis xAI vaizdo įrašų API dokumentacija: URL adresas yra lauke
video.url(nevideo_url), generavimas turi tik tris būsenas (pending,done,failed, paskutinė lydima klaidos kodo), o dažnio ribos išreiškiamos užklausomis per sekundę, priklausomai nuo komandos lygio. Šaltiniai: Vaizdo įrašų generavimas · Vaizdo įrašų nuorodos · Dažnio ribos.
Suprask vaizdo įrašo gyvavimo ciklą
Visos vaizdo įrašų operacijos xAI API veikia asinchroniniu režimu, ir ši savybė daro didesnę įtaką tavo programos architektūrai, nei gali pasirodyti iš pirmo žvilgsnio. Pokalbio užklausa arba vaizdo generavimas grąžina rezultatą iškart; tačiau vaizdo įrašo generavimui reikia daug laiko apdoroti, todėl grąžinamas tik patvirtinimas. Tau tenka įgyvendinti stebėjimą: periodiškai tikrinti užduoties būseną, nustatyti pabaigą ir atsisiųsti failą. Visas ciklas susideda iš keturių žingsnių.
Pateikti užklausą
POST užklausa generavimo, redagavimo arba pratęsimo galutiniam taškui. Momentinis atsakymas su request_id.
Tikrinti būseną
GET /v1/videos/{request_id} reguliariais intervalais. Laukas progress kinta nuo 0 iki 100.
Gauti rezultatą
Kai būsena yra done (progress = 100), vaizdo įrašo URL tampa prieinamas.
Nedelsiant atsisiųsti
Vaizdo įrašo URL yra laikinas. Atsisiųsk jį kuo greičiau.
Tikrink generavimo būseną
Stebėjimas apima paprastą GET užklausą būsenos galutiniam taškui, naudojant identifikatorių, gautą pateikiant užklausą.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Atsakyme pateikiama ši naudinga informacija:
- status : dabartinė generavimo būsena
- progress : sveikasis skaičius nuo 0 iki 100, rodantis pažangą
- video.url : vaizdo įrašo URL, esantis
videoobjekte, kai būsena yradone, kartu su jo trukme (video.duration) - video.respect_moderation : loginė reikšmė, nurodanti, ar turinys atitinka moderavimo politiką
- error : gedimo atveju – kodas (
invalid_argument,permission_denied,failed_precondition,service_unavailablearbainternal_error) ir pranešimas - usage.cost_in_usd_ticks : užklausos kaina, išreikšta dešimtimis milijardinės dolio dalies
Laukas progress nusipelno pastabos: jis nevaldo tavo kontrolės logikos, kuri visada turi remtis status, tačiau yra aukso vertės vartotojo sąsajai. Rodymas „62 %“ vietoj statinio sukimosi indikatoriaus visiškai keičia laukimo, kuris gali trukti kelias minutes, suvokimą.
Trys būsenos, trys veiksmai
| Būsena | Pažanga | Reikšmė |
|---|---|---|
pending | 0–99 | Generavimas vyksta |
done | 100 | Baigta, URL prieinamas |
failed | nėra | Generavimas nepavyko |
Kol būsena yra pending, generavimas tęsiasi: tau tiesiog reikia toliau siųsti užklausas reguliariais intervalais ir perduoti progress reikšmę į savo sąsają. Kai ji pasikeičia į done, vaizdo įrašas paruoštas, ir belieka tik nuskaityti video.url bei nedelsiant atsisiųsti failą – šie URL adresai yra laikini, o dokumentacijoje nenurodytas jų galiojimo laikas, todėl draudžiama juos saugoti duomenų bazėje vėlesniam naudojimui.
Galiausiai, būsena failed rodo gamybos gedimą, o laukas error nurodo, koks tai gedimas. Šis skirtumas svarbus tolesniems veiksmams: service_unavailable (laikinai perkrauta paslauga) arba internal_error pateisina bandymą pakartoti vėliau, tuo tarpu invalid_argument arba permission_denied – atmestas promptas, netinkamas šaltinio vaizdas ar vaizdo įrašas – reikalauja pirmiausia ištaisyti užklausą. Savo ruožtu, Python SDK taip pat signalizuoja klaida apie atidėtą užklausą, kurios galiojimas baigėsi prieš ją gaunant.
Įgyvendink apklausą
Sinchroninė versija telpa į vieną funkciją. Ji vykdo ciklą iki laiko limito, anksti išėjimo gedimo atveju, iškeliant jo kodą, ir grąžina URL, kai tik vaizdo įrašas paruoštas.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Laukti, kol baigsis vaizdo įrašo generavimas."""
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")
Paslaugoje, vienu metu apdorojančioje kelias užklausas, ši blokuojanti versija tampa „butelio kakleliu“: kiekvienas laukimas imobilizuoja giją minutėms. Asinchroninis perkėlimas atlaisvina įvykių ciklą tarp užklausų ir leidžia vienu metu stebėti dešimtis generavimų.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asinchroninė apklausos versija."""
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")
Nustatyk apklausos intervalą
Intervalo pasirinkimas subalansuoja reaktyvumą ir švaistomas užklausas. Penkios sekundės daugeliu atvejų yra geras kompromisas. Ilgiems generavimams – dešimties–penkiolikos sekundžių trukmės vaizdo įrašams – pakanka dešimties–penkiolikos sekundžių intervalo tarp apklausų, taip sumažinant srautą. Priešingai, interaktyvioje programoje, kurioje vartotojas stebi pažangos juostą, pateisinama sumažinti intervalą iki dviejų ar trijų sekundžių. Tačiau žemiau vienos sekundės nieko nepaspartinsi: generavimas vyksta savo tempu, o tu tik be reikalo padaugini užklausų skaičių.
Svarbiausi punktai
- Visos vaizdo įrašų operacijos yra asinchroninės: POST pateikimui, GET gavimui
- Trys galimos būsenos: pending, done, failed (su klaidos kodu)
- Laukas
progress(0–100) leidžia stebėti pažangą - Įgyvendink laiko limitą ir apklausos intervalą, pritaikytą tavo naudojimui
- Vaizdo įrašų URL yra laikini: atsisiųsk nedelsiant