Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Pracovní postup asynchronního zpracování a dotazování

Lekce 10 z 12 Aktualizováno 2. listopadu 2026 Mírně pokročilý
Na této stránce
  1. Pochopte životní cyklus videa
  2. Kontrola stavu generování
  3. Tři stavy, tři akce
  4. Implementace dotazování (Polling)
  5. Nastavení intervalu dotazování
  6. Klíčové poznatky

Aktualizováno 2. listopadu 2026. Na základě reference xAI Video API: URL adresa se nachází v video.url (nikoli video_url), generování má pouze tři stavy (pending, done, failed, přičemž poslední je doprovázen kódem chyby) a limity rychlosti jsou vyjádřeny v požadavcích za sekundu na základě úrovně týmu. Zdroje: Video Generation · Videos Reference · Rate limits.

Pochopte životní cyklus videa

Všechny operace s videem v xAI API jsou asynchronní a tato vlastnost formuje architekturu vaší aplikace více, než byste na první pohled čekali. Volání chatu nebo generování obrázku vrátí výsledek okamžitě; generování videa však vyžaduje značný čas zpracování a vrací pouze potvrzení přijetí. Je na vás, abyste implementovali sledování: pravidelně dotazujte stav úlohy, detekujte dokončení a stáhněte soubor. Celý cyklus se skládá ze čtyř kroků.

1

Odeslat požadavek

POST na koncový bod pro generování, úpravy nebo rozšíření. Okamžitá odpověď s request_id.

2

Dotazovat stav

GET /v1/videos/{request_id} v pravidelných intervalech. Pole progress od 0 do 100.

3

Získat výsledek

Když je stav done (progress = 100), je URL videa k dispozici.

4

Okamžitě stáhnout

URL videa je dočasné. Stáhněte jej co nejdříve.

Kontrola stavu generování

Sledování zahrnuje jednoduchý požadavek GET na koncový bod stavu s použitím identifikátoru přijatého při odeslání.

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

Odpověď poskytuje následující užitečné informace:

  • status : aktuální stav generování
  • progress : celé číslo od 0 do 100 udávající postup
  • video.url : URL videa, uvnitř objektu video, který je přítomen, když je stav done, spolu s jeho délkou (video.duration)
  • video.respect_moderation : boolean indikující, zda obsah splňuje zásady moderování
  • error : v případě selhání kód (invalid_argument, permission_denied, failed_precondition, service_unavailable nebo internal_error) a zpráva
  • usage.cost_in_usd_ticks : cena požadavku v desetimiliardtinách dolaru

Pole progress si zaslouží poznámku: neřídí vaši řídicí logiku, která by se měla vždy spoléhat na status, ale je zlatým dolem pro uživatelské rozhraní. Zobrazení „62 %“ místo statického indikátoru načítání zcela mění vnímání čekání, které může trvat několik minut.

Tři stavy, tři akce

StatusProgressVýznam
pending0-99Generování probíhá
done100Dokončeno, URL k dispozici
failedchybíGenerování selhalo

Dokud je stav pending, generování pokračuje: jednoduše pokračujete v dotazování v pravidelných intervalech a předáváte progress do svého rozhraní. Když přepne na done, je video připraveno a jediným úkolem je přečíst video.url a soubor okamžitě stáhnout – tyto URL adresy jsou dočasné a dokumentace nespecifikuje jejich životnost, což zakazuje jejich ukládání do databáze pro pozdější použití.

Nakonec stav failed indikuje selhání produkce a pole error vám sdělí, o jaké selhání jde. Rozlišení je důležité pro další postup: service_unavailable (služba dočasně přetížená) nebo internal_error ospravedlňují pozdější opakování, zatímco invalid_argument nebo permission_denied – zamítnutý prompt, neplatný zdrojový obrázek nebo video – vyžadují nejprve opravu požadavku. Python SDK navíc signalizuje prostřednictvím chyby odložený požadavek, který vypršel před tím, než byl získán.

Implementace dotazování (Polling)

Synchronní verze se vejde do jedné funkce. Cyklí až do vypršení časového limitu, při selhání předčasně skončí vyvoláním jeho kódu a vrátí URL adresu, jakmile je video připraveno.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Čekání na dokončení generování 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"Generování selhalo [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"Probíhá... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Časový limit vypršel po {timeout} sekundách")

Ve službě zpracovávající více požadavků najednou se tato blokující verze stává úzkým hrdlem: každé čekání imobilizuje vlákno na minuty. Asynchronní převod uvolní smyčku událostí mezi dotazy a umožní vám sledovat desítky generování paralelně.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchronní verze dotazování."""
    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"Generování selhalo : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Časový limit vypršel")

Nastavení intervalu dotazování

Volba intervalu vyvažuje odezvu proti plýtvání požadavky. Pět sekund je ve většině případů dobrým kompromisem. Pro dlouhá generování – deset až patnáct sekund videa – stačí deset až patnáct sekund mezi dotazy, což snižuje provoz. Naopak interaktivní aplikace, kde uživatel sleduje indikátor postupu, ospravedlňuje snížení na dvě až tři sekundy. Pod jednu sekundu však nic nezrychlíte: generování postupuje svým vlastním tempem a vy pouze zbytečně násobíte požadavky.

Klíčové poznatky

  • Všechny operace s videem jsou asynchronní: POST pro odeslání, GET pro získání
  • Tři možné stavy: pending, done, failed (s kódem chyby)
  • Pole progress (0–100) vám umožňuje sledovat postup
  • Implementujte časový limit a interval dotazování přizpůsobený vašemu případu použití
  • URL adresy videí jsou dočasné: stahujte je okamžitě