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

xAI SDK a automatické dotazování

Lekce 11 z 12 Aktualizováno 2. listopadu 2026 Mírně pokročilý
Na této stránce
  1. Zjednodušení dotazování pomocí SDK
  2. Jediné volání místo smyčky
  3. Zpracování chyb přímo u zdroje
  4. Úpravy a rozšiřování se stejnou snadností
  5. Nikdy nenechávej video v cloudu
  6. Generování více videí najednou
  7. Měl bys opustit ruční dotazování?
  8. Klíčové poznatky

Aktualizováno 2. listopadu 2026 na základě dokumentace k videím xAI a kódu xai-sdk 1.21.0: metody se nazývají client.video.generate a client.video.extend (úpravy používají generate s video_url), výsledek poskytuje url, zpoždění se nastavuje přes timedelta a výchozí interval dotazování je jedna sekunda. await vyžaduje asynchronního klienta AsyncClient a výjimka VideoGenerationError se importuje z xai_sdk.video. Stará verze volala metody a modul výjimek, které neexistují. Zdroje: Video Generation · Video Editing · Video Extension · xai-sdk-python.

Zjednodušení dotazování pomocí SDK

V předchozí lekci jsi psal smyčku pro dotazování ručně. Je to užitečné cvičení pro pochopení životního cyklu generování, ale zároveň je to třicet řádků kódu, které musíš udržovat v každém projektu, včetně vlastní obsluhy časových limitů, případů selhání a převodů stavů. Oficiální Python SDK od xAI (pip install xai-sdk) to vše zapouzdřuje: odešleš požadavek a ono se postará o čekání.

Jediné volání místo smyčky

Metoda client.video.generate sdružuje odeslání, sledování a získání výsledku. Vrátí kontrolu až ve chvíli, kdy je video hotové, nebo vyhodí výjimku, pokud se něco pokazilo.

import os

import xai_sdk

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

# Generování text-na-video s automatickým dotazováním
video = client.video.generate(
    prompt="A sunrise over the Alps, accelerated time-lapse",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Duration: {video.duration} s, model: {video.model}")

Za těmito několika řádky SDK dělá přesně to, co jsi kódval dříve: odešle požadavek, každou sekundu (ve výchozím nastavení) zkontroluje stav a poté vrátí výsledek nebo vyhodí výjimku podle výsledku.

Jedno nastavení si zaslouží tvou pozornost hned při nasazení: ve výchozím nastavení SDK čeká až 10 minut, než to vzdá. To je pohodlné pro noční produkční skript, ale pro webový požadavek, kde uživatel čeká na odpověď, je to mnohem příliš dlouhé. Parametry timeout a interval, oba jako objekty timedelta, nastavují limit a rytmus:

from datetime import timedelta

video = client.video.generate(
    prompt="Your description",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # max 5 minut
    interval=timedelta(seconds=5),  # jedna kontrola každých 5 sekund
)

Pokud chceš mít nad čekáním kontrolu – například pro přenos průběhu –, client.video.start odešle požadavek a vrátí jeho request_id, které pak client.video.get dotazuje.

Zpracování chyb přímo u zdroje

SDK rozlišuje typy selhání, což tě zbavuje nutnosti analyzovat řetězce, abys zjistil, co se stalo:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Your description",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video ready: {video.url}")
except VideoGenerationError as e:
    print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
    print("Timeout exceeded: increase the timeout or simplify the request")

Každá chyba vyžaduje jinou reakci a jejich zaměňování vede k neužitečným cyklům opakování nebo, hůře, k fakturovaným generováním, která nic nevytvoří.

ChybaPříčinaDoporučená akce
VideoGenerationErrorSelhání signalizované API: odmítnutý prompt, neplatný zdroj, přetížená služba… (code, message)Přečti si kód: oprav požadavek, nebo to zkus znovu později, pokud byla služba nedostupná
TimeoutErrorPřekročen čas čekání na straně klientaZvyš timeout nebo zkrať duration
RuntimeErrorOdložený požadavek vypršel nebo byl dokončen bez výsledkuRestartuj generování
grpc.RpcErrorChyba transportu SDK, včetně limitů rychlosti (kód RESOURCE_EXHAUSTED) a problémů s klíčemRozlož požadavky s exponenciálním zpětným čekáním (backoff), nebo zkontroluj klíč

SDK používá gRPC: překročený limit rychlosti se zde neobjeví jako HTTP kód 429, ale jako grpc.RpcError s kódem RESOURCE_EXHAUSTED.

Úpravy a rozšiřování se stejnou snadností

Úpravy nemají vyhrazenou metodu: používá se generate se zdrojovým videem, předaným jako video_url (video až 8,7 sekundy, stejná délka výstupu, max 720p).

video = client.video.generate(
    prompt="Transform the scene into Japanese anime style",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Rozšíření prodlužuje sekvenci o délce 2 až 15 sekund o segment 2 až 10 sekund a vrací celé video:

video = client.video.extend(
    prompt="Continue the scene with a pan to the right",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Všimni si rozdílu oproti REST API: SDK přijímá video jako parametr video_url, zatímco tělo JSON očekává objekt video s jeho vlastností url.

Nikdy nenechávej video v cloudu

SDK nic nemění na dočasné povaze URL výsledků. Pokud tvůj kód pouze zobrazí video.url, zaplatil jsi za generování, které brzy zmizí. Nejlepší praxí je řetězit generování a stahování ve stejné funkci, takže není možné na tento krok zapomenout.

from pathlib import Path

import httpx


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

    # Okamžité stažení
    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 saved: {output_file}")
    return output_file

Pro ukládání bez průchodu přes tvůj server parametr storage_options při generování uloží video do xAI Files API s expirací dle tvého výběru.

Generování více videí najednou

S asynchronním klientem je každé volání korutinou a asyncio.gather spustí celou dávku paralelně. Zde je rozhodující možnost return_exceptions=True: bez ní by jediný odmítnutý požadavek selhal celou dávku a přišel bys o již získané výsledky.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generuje více videí paralelně."""
    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"Request {i} failed: {res}")
        else:
            print(f"Request {i} completed: {res.url}")

    return results

Tuto paralelizaci rámují dvě ochranná opatření. Odesílání spotřebovává tvůj limit rychlosti, počítaný v požadavcích za sekundu podle úrovně tvého týmu (10 u vstupní úrovně pro video modely): pro velkou dávku omez souběžnost pomocí asyncio.Semaphore. Pamatuj také na to, co paralelismus dělá a co nedělá: nezrychluje žádné jednotlivé generování, pouze snižuje celkový čas dávky.

Měl bys opustit ruční dotazování?

Ne systematicky. Následující srovnání ukazuje, kde má který přístup navrch.

AspektRuční dotazováníSDK
SložitostVysokáNízká
Zpracování chybK implementaciIntegrované
Časový limitK implementaci10 min výchozí, konfigurovatelné
Interval dotazováníNa výběr1 s výchozí, konfigurovatelné
FlexibilitaÚplnáStandardní (nebo start a get)
ZávislostŽádnáxAI SDK

Ruční dotazování si udržuje svou relevanci ve dvou situacích: když potřebuješ jemnou kontrolu, například pro přenos průběhu do rozhraní v reálném čase nebo pro integraci do existujícího frontového systému, a když tvůj kontext nasazení zakazuje přidávání další závislosti.

Klíčové poznatky

  • client.video.generate odešle, počká a vrátí video (url, duration, model); výchozí časový limit 10 minut a kontrola každou sekundu
  • Úpravy používají generate s video_url, rozšíření používá client.video.extend
  • VideoGenerationError (z xai_sdk.video), TimeoutError a RuntimeError rozlišují selhání; limity rychlosti přicházejí jako grpc.RpcError
  • Vždy stáhni video okamžitě po generování (dočasné URL)
  • Asynchronní klient a asyncio.gather paralelizují dávku v rámci limitu rychlosti tvé úrovně