Fluss tax-Xogħol Asinkronu u Polling
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026. Ibbażat fuq ir-referenza tal-API tal-Video ta’ xAI: l-URL tinsab f’
video.url(mhuxvideo_url), ġenerazzjoni għandha biss tliet stati (pending,done,failed, li l-aħħar wieħed ikun akkumpanjat minn kodiċi ta’ żball), u l-limiti tar-rata huma espressi f’talbiet kull sekonda bbażati fuq il-livell tat-tim. Sorsi: Ġenerazzjoni tal-Video · Referenza tal-Videos · Limiti tar-rata.
Ifhem iċ-ċiklu tal-ħajja tal-video
L-operazzjonijiet kollha tal-video fl-API ta’ xAI huma asinkroni, u din il-karatteristika tifforma l-arkitettura tal-applikazzjoni tiegħek aktar milli tista’ timmaġina fil-bidu. Sejħa ta’ chat jew ġenerazzjoni ta’ stampa tirritorna riżultat immedjatament; il-ġenerazzjoni tal-video, madankollu, teħtieġ ħin ta’ pproċessar sinifikanti u tirritorna biss konferma. Huwa f’idejk li timplimenta t-traċċar: staqsi perjodikament l-istat tal-kompitu, skopri t-tlestija, u rkupra l-fajl. Iċ-ċiklu sħiħ jikkonsisti f’erba’ passi.
Ibgħat it-talba
POST lejn l-endpoint tal-ġenerazzjoni, l-editjar jew l-estensjoni. Rispons immedjat b'request_id.
Iċċekkja l-istatus (Polling)
GET /v1/videos/{request_id} f'intervalli regolari. Il-qasam progress minn 0 sa 100.
Irkupra r-riżultat
Meta l-istatus ikun done (progress = 100), l-URL tal-video tkun disponibbli.
Niżżel immedjatament
L-URL tal-video hija temporanja. Niżżilha malajr kemm jista' jkun.
Iċċekkja l-istatus tal-ġenerazzjoni
It-traċċar jinvolvi talba GET sempliċi lejn l-endpoint tal-istatus, bl-użu tal-identifikatur li rċevejt meta bgħatt it-talba.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Ir-rispons jikxef l-informazzjoni utli li ġejja:
- status : l-istat attwali tal-ġenerazzjoni
- progress : numru sħiħ minn 0 sa 100 li jindika l-progress
- video.url : l-URL tal-video, ġewwa l-oġġett
videopreżenti meta l-istatus ikundone, bid-durata tiegħu (video.duration) - video.respect_moderation : boolean li jindika jekk il-kontenut jikkonformax mal-politika ta’ moderazzjoni
- error : fil-każ ta’ falliment, kodiċi (
invalid_argument,permission_denied,failed_precondition,service_unavailable, jewinternal_error) u messaġġ - usage.cost_in_usd_ticks : l-ispiża tat-talba, f’għaxar biljun parti ta’ dollaru
Il-qasam progress jistħoqqilu nota: dan ma jmexxix il-loġika tal-kontroll tiegħek, li għandha dejjem tiddependi fuq status, iżda huwa deheb għal interface tal-utent. Li turi “62%” minflok spinner statiku jbiddel kompletament il-perċezzjoni ta’ stennija li tista’ ddum diversi minuti.
Tliet stati, tliet azzjonijiet
| Status | Progress | Tifsira |
|---|---|---|
pending | 0-99 | Ġenerazzjoni għaddejja |
done | 100 | Lesta, URL disponibbli |
failed | nieqes | Il-ġenerazzjoni falliet |
Sakemm l-istatus ikun pending, il-ġenerazzjoni tkompli: inti sempliċement tkompli tistaqsi f’intervalli regolari, u tgħaddi l-progress lill-interface tiegħek. Meta jinbidel għal done, il-video tkun lesta, u l-unika ħaġa li trid tagħmel hija taqra video.url u tniżżel il-fajl immedjatament—dawn l-URLs huma temporanji u d-dokumentazzjoni ma tispeċifikax it-tul tal-ħajja tagħhom, li jipprojbixxi l-ħżin tagħhom f’database għal użu futur.
Fl-aħħar nett, l-istatus failed jindika falliment fil-produzzjoni, u l-qasam error jgħidlek liema wieħed. Id-distinzjoni hija importanti għal dak li jmiss: service_unavailable (servizz temporanjament mgħobbi żejjed) jew internal_error jiġġustifikaw li tipprova mill-ġdid aktar tard, filwaqt li invalid_argument jew permission_denied—prompt miċħud, stampa jew video sors mhux validu—jeħtieġu li tikkoreġi t-talba l-ewwel. L-SDK tal-Python, min-naħa tiegħu, jissinjala wkoll permezz ta’ żball talba differita li skadiet qabel ma ġiet irkuprata.
Implimenta l-polling
Il-verżjoni sinkrona tidħol f’funzjoni waħda. Tagħmel loop sakemm jintemm il-ħin (timeout), toħroġ kmieni fil-każ ta’ falliment billi tgħolli l-kodiċi tiegħu, u tirritorna l-URL hekk kif il-video tkun lesta.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Stenna t-tlestija tal-ġenerazzjoni tal-video."""
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")
F’servizz li jittratta talbiet multipli fl-istess ħin, din il-verżjoni li timblokka ssir collo di bottiglia: kull stenna timmobilizza thread għal minuti. It-traspożizzjoni asinkrona tħalli l-event loop ħieles bejn il-mistoqsijiet u tippermettilek issegwi għexieren ta’ ġenerazzjonijiet paralleli.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Verżjoni asinkrona tal-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")
Iddetermina l-intervall tal-polling
L-għażla tal-intervall tibbilanċja r-reattività kontra t-talbiet moħlija. Ħames sekondi huwa kompromess tajjeb fil-biċċa l-kbira tal-każijiet. Għal ġenerazzjonijiet twal—għaxar sa ħmistax-il sekonda ta’ video—għaxar sa ħmistax-il sekonda bejn kull polling huma biżżejjed u jnaqqsu t-traffiku. Bil-kontra, applikazzjoni interattiva fejn l-utent iħares lejn barra tal-progress tiġġustifika li tonqos għal tnejn jew tliet sekondi. Madankollu, taħt sekonda waħda, ma tħaffef xejn: il-ġenerazzjoni timxi bir-ritmu tagħha, u inti biss timmultiplika t-talbiet għalxejn.
Punti Ewlenin
- L-operazzjonijiet kollha tal-video huma asinkroni: POST biex tibgħat, GET biex tirkupra
- Tliet stati possibbli: pending, done, failed (b’kodiċi ta’ żball)
- Il-qasam
progress(0-100) jippermettilek issegħi l-avvanz - Implimenta timeout u intervall ta’ polling adattat għall-każ ta’ użu tiegħek
- L-URLs tal-video huma temporanji: niżżel immedjatament