Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

xAI SDK a automatické dotazovanie

Lekcia 11 z 12 Aktualizované 2. novembra 2026 Mierne pokročilý
Na tejto strane
  1. Zjednodušenie dotazovania pomocou SDK
  2. Jedno volanie namiesto slučky
  3. Spracovanie chýb priamo u zdroja
  4. Úpravy a rozširovanie s rovnakou ľahkosťou
  5. Nikdy nenechávaj video v cloude
  6. Generovanie viacerých videí naraz
  7. Máš sa vzdať ručného dotazovania?
  8. Kľúčové poznatky

Aktualizované 2. novembra 2026 na základe dokumentácie k videám xAI a kódu xai-sdk 1.21.0: metódy sa nazývajú client.video.generate a client.video.extend (úpravy používajú generate s parametrom video_url), výsledok poskytuje url, oneskorenie sa nastavuje cez timedelta a predvolený interval dotazovania je jedna sekunda. Kľúčové slovo await vyžaduje asynchrónneho klienta AsyncClient a výnimka VideoGenerationError sa importuje z xai_sdk.video. Stará verzia volala metódy a odkazovala na modul výnimiek, ktoré neexistujú. Zdroje: Generovanie videa · Úprava videa · Rozšírenie videa · xai-sdk-python.

Zjednodušenie dotazovania pomocou SDK

V predchádzajúcej lekcii si písal slučku na dotazovanie ručne. Je to užitočné cvičenie na pochopenie životného cyklu generovania, ale zároveň je to tridsať riadkov kódu, ktoré musíš udržiavať v každom projekte, vrátane vlastného spracovania časových limitov, prípadov zlyhania a konverzie stavov. Oficiálny Python SDK od xAI (pip install xai-sdk) zapuzdruje všetko toto: odošleš požiadavku a ono sa postará o čakanie.

Jedno volanie namiesto slučky

Metóda client.video.generate spája odoslanie, sledovanie a získanie výsledku. Kontrolu ti vráti až vtedy, keď je video pripravené, alebo vyhodí výnimku, ak sa niečo pokazilo.

import os

import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Generovanie text-na-video s automatickým dotazovaním
video = client.video.generate(
    prompt="Východ slnka nad Alpami, zrýchlený časozberný záber",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Dĺžka: {video.duration} s, model: {video.model}")

Za týmito niekoľkými riadkami SDK robí presne to, čo si kódovale predtým: odošle požiadavku, každú sekundu (predvolene) zisťuje stav a následne vráti výsledok alebo vyhodí výnimku podľa toho, ako to dopadlo.

Jedno nastavenie si zaslúži tvoju pozornosť hneď pri nasadení: predvolene SDK čaká až 10 minút, kým to vzdá. To je pohodlné pre nočný produkčný skript, ale pre webovú požiadavku, kde používateľ čaká na odpoveď, je to príliš dlho. Parametre timeout a interval, oba ako objekty timedelta, nastavujú limit a rytmus:

from datetime import timedelta

video = client.video.generate(
    prompt="Tvoj popis",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # max 5 minút
    interval=timedelta(seconds=5),  # jedna kontrola každých 5 sekúnd
)

Ak chceš mať nad čakaním kontrolu – napríklad na prenos progresu –, client.video.start odošle požiadavku a vráti jej request_id, ktorý následne dopytuješ cez client.video.get.

Spracovanie chýb priamo u zdroja

SDK rozlišuje typy zlyhaní, čo ťa zbavuje potreby analyzovať reťazce, aby si zistil, čo sa stalo:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Tvoj popis",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video pripravené: {video.url}")
except VideoGenerationError as e:
    print(f"Generovanie zlyhalo [{e.code}]: {e.message}")
except TimeoutError:
    print("Časový limit prekročený: zvýš timeout alebo zjednoduš požiadavku")

Každá chyba si vyžaduje inú reakciu a ich zamieňanie vedie k zbytočným cyklom opakovania alebo, čo je horšie, k fakturovaným generovaniam, ktoré neprinesú žiadny výsledok.

ChybaPríčinaOdporúčaný postup
VideoGenerationErrorZlyhanie signalizované API: odmietnutý prompt, neplatný zdroj, preťažená služba… (code, message)Prečítaj si kód: oprav požiadavku, alebo skús znova neskôr, ak bola služba nedostupná
TimeoutErrorNa strane klienta bol prekročený čas čakaniaZvýš timeout alebo skráť dĺžku videa
RuntimeErrorOdložená požiadavka vypršala alebo sa dokončila bez výsledkuReštartuj generovanie
grpc.RpcErrorChyba transportu SDK, vrátane limitov rýchlosti (kód RESOURCE_EXHAUSTED) a problémov s kľúčomRozlož požiadavky s exponenciálnym oneskorením (backoff) alebo skontroluj kľúč

SDK používa gRPC: prekročený limit rýchlosti sa tu neobjaví ako HTTP kód 429, ale ako grpc.RpcError s kódom RESOURCE_EXHAUSTED.

Úpravy a rozširovanie s rovnakou ľahkosťou

Úprava nemá vyhradenú metódu: používa sa generate so zdrojovým videom, ktoré sa odovzdá ako video_url (video do 8,7 sekundy, rovnaká výstupná dĺžka, max 720p).

video = client.video.generate(
    prompt="Transformuj scénu do štýlu japonského anime",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Rozšírenie predlžuje sekvenciu dlhú 2 až 15 sekúnd o segment dlhý 2 až 10 sekúnd a vráti celé video:

video = client.video.extend(
    prompt="Pokračuj v scéne pohybom kamery doprava",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Všimni si rozdiel oproti REST API: SDK prijíma video ako parameter video_url, zatiaľ čo telo JSON očakáva objekt video s vlastnosťou url.

Nikdy nenechávaj video v cloude

SDK nič nemení na dočasnej povahe URL adries výsledkov. Ak tvoj kód len zobrazí video.url, zaplatil si za generovanie, ktoré čoskoro zmizne. Najlepšou praxou je zreťaziť generovanie a sťahovanie v tej istej funkcii, aby bolo nemožné na tento krok zabudnúť.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Vygeneruje video a uloží ho lokálne (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Okamžité stiahnutie
    async with httpx.AsyncClient() as http:
        response = await http.get(video.url)
        response.raise_for_status()
        Path(output_file).write_bytes(response.content)

    print(f"Video uložené: {output_file}")
    return output_file

Pre ukladanie bez prenosu cez tvoj server parameter storage_options pri generovaní uloží video do xAI Files API s exspiráciou podľa tvojho výberu.

Generovanie viacerých videí naraz

S asynchrónnym klientom je každé volanie korutínou a asyncio.gather spustí celú dávku paralelne. Voľba return_exceptions=True je tu rozhodujúca: bez nej by jedna odmietnutá požiadavka zlyhala celú dávku a prišiel by si o už získané výsledky.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generuje viacero videí paralelne."""
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
    tasks = [
        client.video.generate(
            prompt=req["prompt"],
            model="grok-imagine-video-1.5",
            duration=req.get("duration", 5),
            aspect_ratio=req.get("aspect_ratio", "16:9"),
        )
        for req in requests
    ]

    results = await asyncio.gather(*tasks, return_exceptions=True)

    for i, res in enumerate(results, 1):
        if isinstance(res, Exception):
            print(f"Požiadavka {i} zlyhala: {res}")
        else:
            print(f"Požiadavka {i} dokončená: {res.url}")

    return results

Túto paralelizáciu rámujú dve ochranné opatrenia. Odoslania spotrebúvajú tvoj limit rýchlosti, ktorý sa počíta ako požiadavky za sekundu podľa úrovne tvojho tímu (10 pri vstupnej úrovni pre video modely): pre veľkú dávku obmedz súbežnosť pomocou asyncio.Semaphore. Pamätaj tiež na to, čo paralelizmus robí a čo nerobí: nezrýchli žiadne jednotlivé generovanie, iba skracuje celkový čas dávky.

Máš sa vzdať ručného dotazovania?

Nie systematicky. Nasledujúce porovnanie ukazuje, kde ktorý prístup vedie.

AspektRučné dotazovanieSDK
ZložitosťVysokáNízka
Spracovanie chýbTreba implementovaťIntegrované
Časový limitTreba implementovaťPredvolené 10 min, konfigurovateľné
Interval dotazovaniaTreba zvoliťPredvolené 1 s, konfigurovateľné
FlexibilitaÚplnáŠtandardná (alebo start a get)
ZávislosťŽiadnaxAI SDK

Ručné dotazovanie si zachováva význam v dvoch situáciách: keď potrebuješ jemnú kontrolu, napríklad na prenos progresu do rozhrania v reálnom čase alebo na integráciu do existujúceho systém frontu, a keď tvoj kontext nasadenia zakazuje pridávať ďalšiu závislosť.

Kľúčové poznatky

  • client.video.generate odošle, počká a vráti video (url, duration, model); predvolený časový limit 10 minút a kontrola každú sekundu
  • Úpravy používajú generate s video_url, rozšírenie používa client.video.extend
  • VideoGenerationError (z xai_sdk.video), TimeoutError a RuntimeError rozlišujú zlyhania; limity rýchlosti prichádzajú ako grpc.RpcError
  • Video vždy okamžite stiahni po generovaní (dočasné URL adresy)
  • Asynchrónny klient a asyncio.gather paralelizujú dávku v rámci limitu rýchlosti tvojej úrovne