Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Darbo eiga asinchroniniu režimu ir apklausa

Paskaita 10 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Vidutinis lygis
Šiame puslapyje
  1. Suprask vaizdo įrašo gyvavimo ciklą
  2. Tikrink generavimo būseną
  3. Trys būsenos, trys veiksmai
  4. Įgyvendink apklausą
  5. Nustatyk apklausos intervalą
  6. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. Remiantis xAI vaizdo įrašų API dokumentacija: URL adresas yra lauke video.url (ne video_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ų.

1

Pateikti užklausą

POST užklausa generavimo, redagavimo arba pratęsimo galutiniam taškui. Momentinis atsakymas su request_id.

2

Tikrinti būseną

GET /v1/videos/{request_id} reguliariais intervalais. Laukas progress kinta nuo 0 iki 100.

3

Gauti rezultatą

Kai būsena yra done (progress = 100), vaizdo įrašo URL tampa prieinamas.

4

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 video objekte, kai būsena yra done, 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_unavailable arba internal_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ūsenaPažangaReikšmė
pending0–99Generavimas vyksta
done100Baigta, URL prieinamas
failednėraGeneravimas 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