Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Asünkroonne töövoog ja päringute tegemine

Õppetund 10 / 12 Värskendatud 2. november 2026 Kesktase
Sellel lehel
  1. Mõista video elutsüklit
  2. Kontrolli genereerimise olekut
  3. Kolm olekut, kolm tegevust
  4. Rakenda päringute tegemine (polling)
  5. Määra päringute intervall
  6. Peamised punktid

Uuendatud 2. novembril 2026. Lähtudes xAI Video API dokumentatsioonist: URL asub väljal video.url (mitte video_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.

1

Saada päring

POST-päring genereerimise, redigeerimise või pikendamise lõpppunkti. Kohene vastus koos request_id-ga.

2

Küsi olekut

GET /v1/videos/{request_id} regulaarsete ajavahemike järel. Väli progress muutub 0-lt 100-le.

3

Hangi tulemus

Kui olek on done (progress = 100), on video URL kättesaadav.

4

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 on done, 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_unavailable või internal_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

OlekProgressTähendus
pending0-99Genereerimine pooleli
done100Lõpetatud, URL kättesaadav
failedpuudubGenereerimine 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