Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Munkafolyamat aszinkron módon és lekérdezés (polling)

10. lecke 12 közül Frissítve 2026. november 2. Középhaladó
Ezen az oldalon
  1. Értsd meg a videó életciklusát
  2. Generálási állapot ellenőrzése
  3. Három állapot, három művelet
  4. Polling megvalósítása
  5. A lekérdezési időköz beállítása
  6. Főbb megállapítások

Frissítve: 2026. november 2. Az xAI Video API referenciája alapján: az URL a video.url mezőben található (nem a video_url-ban), egy generálásnak csak három állapota lehet (pending, done, failed, utóbbit hiba kód kíséri), a sebességkorlátok pedig a csapat szintje alapján másodpercenkénti kérésszámban vannak megadva. Források: Videógenerálás · Videók referenciája · Sebességkorlátok.

Értsd meg a videó életciklusát

Az xAI API összes videóművelete aszinkron, és ez a tulajdonság jobban meghatározza az alkalmazásod architektúráját, mint azt elsőre gondolnád. Egy csevegési hívás vagy képgenerálás azonnal eredményt ad; a videógenerálás viszont jelentős feldolgozási időt igényel, és csak egy visszaigazolást küld vissza. Rajtad múlik a nyomon követés megvalósítása: időszakosan lekérdezed a feladat állapotát, észleled a befejezést, majd letöltöd a fájlt. A teljes ciklus négy lépésből áll.

1

Kérés beküldése

POST kérés a generálási, szerkesztési vagy bővítési végpontra. Azonnali válasz egy request_id azonosítóval.

2

Állapot lekérdezése (Polling)

GET /v1/videos/{request_id} rendszeres időközönként. A progress mező 0-tól 100-ig változik.

3

Eredmény lekérése

Ha az állapot done (progress = 100), a videó URL elérhetővé válik.

4

Azonnali letöltés

A videó URL ideiglenes. A lehető leghamarabb töltsd le.

Generálási állapot ellenőrzése

A nyomon követés egy egyszerű GET kérést jelent az állapot végponton, a beküldéskor kapott azonosító felhasználásával.

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

A válasz a következő hasznos információkat tartalmazza:

  • status : a generálás aktuális állapota
  • progress : 0 és 100 közötti egész szám, amely a folyamatot jelzi
  • video.url : a videó URL-je, amely a video objektumban található, amikor az állapot done, a hosszával együtt (video.duration)
  • video.respect_moderation : logikai érték, amely jelzi, hogy a tartalom megfelel-e a moderációs irányelveknek
  • error : hiba esetén egy kód (invalid_argument, permission_denied, failed_precondition, service_unavailable vagy internal_error) és egy üzenet
  • usage.cost_in_usd_ticks : a kérés költsége, tízmilliárdod dollárban kifejezve

A progress mező külön megjegyzést érdemel: nem ez vezérli a vezérlési logikádat, amelynek mindig a status-ra kell támaszkodnia, de aranyat ér a felhasználói felület számára. Ha „62%“-ot látsz egy statikus töltőikon helyett, az teljesen megváltoztatja a több percig is eltartható várakozás érzékelését.

Három állapot, három művelet

ÁllapotHaladás (Progress)Jelentés
pending0-99Generálás folyamatban
done100Befejezve, URL elérhető
failednincsGenerálás sikertelen

Amíg az állapot pending, a generálás folytatódik: egyszerűen folytatod a lekérdezéseket rendszeres időközönként, és továbbítod a progress értéket a felületednek. Amikor az állapot done-ra vált, a videó kész, és nincs más dolgod, mint kiolvasni a video.url-t, és azonnal letölteni a fájlt – ezek az URL-ek ideiglenesek, és a dokumentáció nem határozza meg az élettartamukat, ami kizárja, hogy későbbi felhasználás céljából adatbázisban tárold őket.

Végül a failed állapot gyártási hibát jelez, és az error mező megmondja, melyiket. A megkülönböztetés fontos a továbbiak szempontjából: a service_unavailable (a szolgáltatás ideiglenesen túlterhelt) vagy az internal_error indokolttá teszi a későbbi újrapróbálkozást, míg az invalid_argument vagy a permission_denied – elutasított prompt, érvénytelen forráskép vagy videó – először a kérés kijavítását igényli. A Python SDK egyébként hibával jelzi azt az elhalasztott kérést is, amely lejárt, mielőtt lekérték volna.

Polling megvalósítása

A szinkron verzió egyetlen függvénybe fér el. Addig ciklizik, amíg az időtúllépés be nem következik, hiba esetén a hibakód dobásával lép ki, és amint a videó kész, visszaadja az URL-t.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Wait for video generation completion."""
    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")

Egy egyszerre több kérést kezelő szolgáltatásban ez a blokkoló verzió szűk keresztmetszetté válik: minden várakozás percekre lefoglal egy szálat. Az aszinkron változat felszabadítja az eseményhurkot a lekérdezések között, és lehetővé teszi tucatnyi generálás párhuzamos nyomon követését.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchronous version of 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")

A lekérdezési időköz beállítása

Az időköz megválasztása egyensúlyt teremt a reagálóképesség és a felesleges kérések között. Öt másodperc a legtöbb esetben jó kompromisszum. Hosszú generálásoknál – tíz-tizenöt másodperces videók – a tíz-tizenöt másodperces lekérdezési időköz is elegendő, és csökkenti a forgalmat. Ezzel szemben egy interaktív alkalmazásnál, ahol a felhasználó egy folyamatjelző sávot figyel, indokolt lehet két-három másodpercre csökkenteni az időt. Egy másodperc alatt azonban semmit sem gyorsítasz fel: a generálás a saját tempójában halad, és csak feleslegesen szorzod meg a kérések számát.

Főbb megállapítások

  • Minden videóművelet aszinkron: POST a beküldéshez, GET a lekéréshez
  • Három lehetséges állapot: pending, done, failed (hibakóddal)
  • A progress mező (0-100) lehetővé teszi a haladás nyomon követését
  • Implementálj időtúllépést és az esetedhez igazított lekérdezési időközt
  • A videó URL-ek ideiglenesek: töltsd le őket azonnal