xAI SDK a automatické dotazování
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace k videím xAI a kódu
xai-sdk1.21.0: metody se nazývajíclient.video.generateaclient.video.extend(úpravy používajígeneratesvideo_url), výsledek poskytujeurl, zpoždění se nastavuje přestimedeltaa výchozí interval dotazování je jedna sekunda.awaitvyžaduje asynchronního klientaAsyncClienta výjimkaVideoGenerationErrorse importuje zxai_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ří.
| Chyba | Příčina | Doporučená akce |
|---|---|---|
VideoGenerationError | Selhá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á |
TimeoutError | Překročen čas čekání na straně klienta | Zvyš timeout nebo zkrať duration |
RuntimeError | Odložený požadavek vypršel nebo byl dokončen bez výsledku | Restartuj generování |
grpc.RpcError | Chyba transportu SDK, včetně limitů rychlosti (kód RESOURCE_EXHAUSTED) a problémů s klíčem | Rozlož 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.
| Aspekt | Ruční dotazování | SDK |
|---|---|---|
| Složitost | Vysoká | Nízká |
| Zpracování chyb | K implementaci | Integrované |
| Časový limit | K implementaci | 10 min výchozí, konfigurovatelné |
| Interval dotazování | Na výběr | 1 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.generateodešle, počká a vrátí video (url,duration,model); výchozí časový limit 10 minut a kontrola každou sekundu- Úpravy používají
generatesvideo_url, rozšíření používáclient.video.extend VideoGenerationError(zxai_sdk.video),TimeoutErroraRuntimeErrorrozlišují selhání; limity rychlosti přicházejí jakogrpc.RpcError- Vždy stáhni video okamžitě po generování (dočasné URL)
- Asynchronní klient a
asyncio.gatherparalelizují dávku v rámci limitu rychlosti tvé úrovně