xAI SDK a automatické dotazovanie
Na tejto strane
Aktualizované 2. novembra 2026 na základe dokumentácie k videám xAI a kódu
xai-sdk1.21.0: metódy sa nazývajúclient.video.generateaclient.video.extend(úpravy používajúgenerates parametromvideo_url), výsledok poskytujeurl, oneskorenie sa nastavuje ceztimedeltaa predvolený interval dotazovania je jedna sekunda. Kľúčové slovoawaitvyžaduje asynchrónneho klientaAsyncClienta výnimkaVideoGenerationErrorsa importuje zxai_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.
| Chyba | Príčina | Odporúčaný postup |
|---|---|---|
VideoGenerationError | Zlyhanie 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á |
TimeoutError | Na strane klienta bol prekročený čas čakania | Zvýš timeout alebo skráť dĺžku videa |
RuntimeError | Odložená požiadavka vypršala alebo sa dokončila bez výsledku | Reštartuj generovanie |
grpc.RpcError | Chyba transportu SDK, vrátane limitov rýchlosti (kód RESOURCE_EXHAUSTED) a problémov s kľúčom | Rozlož 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.
| Aspekt | Ručné dotazovanie | SDK |
|---|---|---|
| Zložitosť | Vysoká | Nízka |
| Spracovanie chýb | Treba implementovať | Integrované |
| Časový limit | Treba implementovať | Predvolené 10 min, konfigurovateľné |
| Interval dotazovania | Treba zvoliť | Predvolené 1 s, konfigurovateľné |
| Flexibilita | Úplná | Štandardná (alebo start a get) |
| Závislosť | Žiadna | xAI 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.generateodošle, počká a vráti video (url,duration,model); predvolený časový limit 10 minút a kontrola každú sekundu- Úpravy používajú
generatesvideo_url, rozšírenie používaclient.video.extend VideoGenerationError(zxai_sdk.video),TimeoutErroraRuntimeErrorrozlišujú zlyhania; limity rýchlosti prichádzajú akogrpc.RpcError- Video vždy okamžite stiahni po generovaní (dočasné URL adresy)
- Asynchrónny klient a
asyncio.gatherparalelizujú dávku v rámci limitu rýchlosti tvojej úrovne