Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Tijek rada asinkronog procesa i ispitivanje stanja

Lekcija 10 od 12 Ažurirano 2. studenoga 2026. Srednja razina
Na ovoj stranici
  1. Razumijevanje životnog ciklusa videa
  2. Provjera statusa generiranja
  3. Tri stanja, tri radnje
  4. Implementacija ispitivanja stanja (Polling)
  5. Postavljanje intervala ispitivanja
  6. Ključne točke

Ažurirano 2. studenoga 2026. Na temelju referencije xAI Video API-ja: URL se nalazi u video.url (ne video_url), generiranje ima samo tri statusa (pending, done, failed, pri čemu je posljednji popraćen kodom pogreške), a ograničenja stope izražena su u zahtjevima po sekundi ovisno o razini tima. Izvori: Video Generation · Videos Reference · Rate limits.

Razumijevanje životnog ciklusa videa

Sve operacije s videom u xAI API-ju su asinkrone, a ta značajka oblikuje arhitekturu tvoje aplikacije više nego što bi mogao očekivati na prvi pogled. Poziv chata ili generiranje slike vraćaju rezultat odmah; generiranje videa, međutim, zahtijeva znatno vrijeme obrade i vraća samo potvrdu primitka. Na tebi je da implementiraš praćenje: povremeno ispituješ status zadatka, detektiraš završetak i preuzimaš datoteku. Cjelokupni ciklus sastoji se od četiri koraka.

1

Pošalji zahtjev

POST na krajnju točku za generiranje, uređivanje ili proširenje. Trenutni odgovor s request_id.

2

Ispituj status

GET /v1/videos/{request_id} u redovitim intervalima. Polje progress ide od 0 do 100.

3

Preuzmi rezultat

Kada je status done (progress = 100), URL videa je dostupan.

4

Odmah preuzmi

URL videa je privremen. Preuzmi ga što je prije moguće.

Provjera statusa generiranja

Praćenje uključuje jednostavan GET zahtjev krajnjoj točki statusa, koristeći identifikator primljen prilikom slanja.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Odgovor otkriva sljedeće korisne informacije:

  • status : trenutno stanje generiranja
  • progress : cijeli broj od 0 do 100 koji označava napredak
  • video.url : URL videa, unutar objekta video prisutnog kada je status done, zajedno s trajanjem (video.duration)
  • video.respect_moderation : boolean vrijednost koja označava odgovara li sadržaj politici moderacije
  • error : u slučaju neuspjeha, kod (invalid_argument, permission_denied, failed_precondition, service_unavailable ili internal_error) i poruka
  • usage.cost_in_usd_ticks : trošak zahtjeva, u deset-milijarditim dijelovima dolara

Polje progress zaslužuje napomenu: ono ne upravlja tvojom kontrolnom logikom, koja se uvijek treba oslanjati na status, ali je zlata vrijedno za korisničko sučelje. Prikazivanje „62%“ umjesto statičnog indikatora učitavanja potpuno mijenja percepciju čekanja koje može trajati nekoliko minuta.

Tri stanja, tri radnje

StatusNapredakZnačenje
pending0-99Generiranje u tijeku
done100Završeno, URL dostupan
failedodsutanGeneriranje nije uspjelo

Dokle god je status pending, generiranje traje: jednostavno nastavljaš s upitima u redovitim intervalima, prosljeđujući progress svom sučelju. Kada se prebaci na done, video je spreman i jedino što trebaš učiniti jest pročitati video.url i odmah preuzeti datoteku – ti su URL-ovi privremeni, a dokumentacija ne specificira njihov vijek trajanja, što zabranjuje njihovo pohranjivanje u bazu podataka za kasniju upotrebu.

Konačno, status failed ukazuje na neuspjeh proizvodnje, a polje error govori ti o kojem se radi. Razlika je bitna za ono što slijedi: service_unavailable (usluga privremeno preopterećena) ili internal_error opravdavaju ponovni pokušaj kasnije, dok invalid_argument ili permission_denied – odbijen prompt, neispravna izvorna slika ili video – zahtijevaju prvo ispravljanje zahtjeva. Python SDK, sa svoje strane, također signalizira putem pogreške odgođeni zahtjev koji je istekao prije nego što je preuzet.

Implementacija ispitivanja stanja (Polling)

Sinkrona verzija staje u jednu funkciju. Ona vrši petlju do isteka vremena, izlazi ranije u slučaju neuspjeha podižući njegov kod i vraća URL čim je video spreman.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Čekaj završetak generiranja videa."""
    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")

U servisu koji istovremeno obrađuje više zahtjeva, ova blokirajuća verzija postaje usko grlo: svako čekanje imobilizira nit na minute. Asinkrona transpozicija oslobađa petlju događaja između upita i omogućuje ti praćenje desetaka generiranja paralelno.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asinkrona verzija ispitivanja stanja."""
    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")

Postavljanje intervala ispitivanja

Odabir intervala balansira između odzivnosti i uzaludnih zahtjeva. Pet sekundi dobar je kompromis u većini slučajeva. Za duga generiranja – deset do petnaest sekundi videa – deset do petnaest sekundi između ispitivanja sasvim je dovoljno i smanjuje promet. Suprotno tome, interaktivna aplikacija u kojoj korisnik gleda traku napretka opravdava smanjenje na dvije ili tri sekunde. Ispod jedne sekunde, međutim, nećeš ništa ubrzati: generiranje napreduje vlastitim tempom, a ti samo množiš zahtjeve uzalud.

Ključne točke

  • Sve operacije s videom su asinkrone: POST za slanje, GET za dohvat
  • Tri moguća statusa: pending, done, failed (s kodom pogreške)
  • Polje progress (0-100) omogućuje praćenje napretka
  • Implementiraj vremensko ograničenje i interval ispitivanja prilagođen tvojem slučaju upotrebe
  • URL-ovi videa su privremeni: preuzmi ih odmah