Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Fluss tax-Xogħol Asinkronu u Polling

Lezzjoni 10 / 12 Aġġornat 2 ta’ Novembru 2026 Livell Medju
F'din il-paġna
  1. Ifhem iċ-ċiklu tal-ħajja tal-video
  2. Iċċekkja l-istatus tal-ġenerazzjoni
  3. Tliet stati, tliet azzjonijiet
  4. Implimenta l-polling
  5. Iddetermina l-intervall tal-polling
  6. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru, 2026. Ibbażat fuq ir-referenza tal-API tal-Video ta’ xAI: l-URL tinsab f’video.url (mhux video_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.

1

Ibgħat it-talba

POST lejn l-endpoint tal-ġenerazzjoni, l-editjar jew l-estensjoni. Rispons immedjat b'request_id.

2

Iċċekkja l-istatus (Polling)

GET /v1/videos/{request_id} f'intervalli regolari. Il-qasam progress minn 0 sa 100.

3

Irkupra r-riżultat

Meta l-istatus ikun done (progress = 100), l-URL tal-video tkun disponibbli.

4

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 video preżenti meta l-istatus ikun done, 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, jew internal_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

StatusProgressTifsira
pending0-99Ġenerazzjoni għaddejja
done100Lesta, URL disponibbli
failednieqesIl-ġ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