xAI SDK és automatikus lekérdezés
Ezen az oldalon
Frissítve: 2026. november 2. az xAI videós dokumentációja és az
xai-sdk1.21.0 verziójú kódja alapján: a metódusok neveclient.video.generateésclient.video.extend(a szerkesztés ageneratehasználatavideo_urlparaméterrel), az eredmény tartalmazza azurlattribútumot, a késleltetést egytimedeltaobjektummal állítod be, az alapértelmezett lekérdezési időköz pedig egy másodperc. Azawaitkulcsszó használatához az aszinkron kliensre (AsyncClient) van szükség, aVideoGenerationErrorkivételt pedig azxai_sdk.videomodulból importálod. A régi verzió olyan metódusokat és kivételmodult említett, amelyek nem léteznek. Források: Videógenerálás · Videószerkesztés · Videóbővítés · xai-sdk-python.
Egyszerűsítsd a lekérdezést az SDK-val
Az előző leckében saját kézzel írtál egy lekérdezési ciklust. Ez hasznos gyakorlat a generálási életciklus megértéséhez, de minden projektben karbantartandó harminc sor kódot jelent, saját időtúllépés-kezeléssel, hibaesetekkel és állapotkonverziókkal. Az xAI hivatalos Python SDK-ja (pip install xai-sdk) mindezt kapszulázza: te elküldöd a kérést, az SDK pedig kezeli a várakozást.
Egyetlen hívás ciklus helyett
A client.video.generate metódus egyesíti a beküldést, a nyomon követést és az adatlekérést. Csak akkor adja vissza az irányítást, ha a videó elkészült, vagy kivételt dob, ha valami hiba történt.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Szöveg-videó generálás automatikus lekérdezéssel
video = client.video.generate(
prompt="Napfelkelte az Alpok felett, gyorsított időzített felvétel",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Időtartam: {video.duration} s, modell: {video.model}")
E néhány sor kód mögött az SDK pontosan azt csinálja, amit korábban te kódoltál: elküldi a kérést, alapértelmezetten másodpercenként lekérdezi az állapotot, majd az eredménytől függően visszaadja az eredményt vagy kivételt dob.
Egy beállításra már a telepítéskor figyelned kell: alapértelmezetten az SDK legfeljebb 10 percig vár, mielőtt feladná. Ez kényelmes egy éjszakai gyártási szkriptnél, de sokkal túl hosszú egy webes kérésnél, ahol a felhasználó a válaszra vár. A timeout és az interval paraméterek, amelyek mindketten timedelta objektumok, állítják be a határidőt és az ütemezést:
from datetime import timedelta
video = client.video.generate(
prompt="A te leírásod",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # max. 5 perc
interval=timedelta(seconds=5), # ellenőrzés 5 másodpercenként
)
Ha meg szeretnéd tartani a kontrollt a várakozás felett – például a haladás továbbításához –, a client.video.start beküldi a kérést és visszaadja a request_id azonosítót, amelyet aztán a client.video.get lekérdez.
Kezeld a hibákat a forrásnál
Az SDK megkülönbözteti a hibákat, így megspórolod neked a szövegek elemzését annak kiderítésére, mi történt:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="A te leírásod",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Videó kész: {video.url}")
except VideoGenerationError as e:
print(f"Generálás sikertelen [{e.code}]: {e.message}")
except TimeoutError:
print("Időtúllépés: növeld a timeout értéket vagy egyszerűsítsd a kérést")
Minden hiba eltérő reakciót igényel, és ezek összekeverése felesleges újrapróbálkozási ciklusokhoz vezet, vagy ami rosszabb, számlázott generálásokhoz, amelyek semmit sem eredményeznek.
| Hiba | Ok | Javasolt intézkedés |
|---|---|---|
VideoGenerationError | Az API által jelzett hiba: elutasított prompt, érvénytelen forrás, túlterhelt szolgáltatás… (code, message) | Olvasd el a kódot: javítsd a kérést, vagy próbáld újra később, ha a szolgáltatás nem volt elérhető |
TimeoutError | A kliens oldali várakozási idő túllépése | Növeld a timeout értékét vagy csökkentsd az időtartamot |
RuntimeError | A késleltetett kérés lejárt, vagy eredmény nélkül fejeződött be | Indítsd újra a generálást |
grpc.RpcError | Az SDK transzport hibája, beleértve a sebességkorlátokat (RESOURCE_EXHAUSTED kód) és kulcsproblémákat | Tarts szünetet a kérések között backoff stratégiával, vagy ellenőrizd a kulcsot |
Az SDK gRPC-t használ: a túllépett sebességkorlát itt nem HTTP 429-es kódként jelenik meg, hanem grpc.RpcError kivételként RESOURCE_EXHAUSTED kóddal.
Szerkesztés és bővítés, ugyanolyan egyszerűen
A szerkesztésnek nincs dedikált metódusa: ez a generate használata egy forrásvideóval, amelyet video_url paraméterként adsz meg (legfeljebb 8,7 másodperces videó, ugyanolyan időtartamú kimenet, max. 720p felbontás).
video = client.video.generate(
prompt="Alakítsd át a jelenetet japán anime stílusra",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
A bővítés meghosszabbít egy 2 és 15 másodperc közötti szekvenciát egy 2 és 10 másodperc közötti szakasszal, és visszaadja a teljes videót:
video = client.video.extend(
prompt="Folytasd a jelenetet egy jobbra panorámázással",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Figyeld meg a különbséget a REST API-hoz képest: az SDK a videót video_url paraméterként fogadja, míg a JSON törzs egy video objektumot vár url tulajdonsággal.
Soha ne hagyd a videót a felhőben
Az SDK semmit sem változtat az eredmény URL-ek ideiglenes jellegén. Ha a kódod csak kiírja a video.url értékét, akkor egy olyan generálásért fizettél, amely hamarosan eltűnik. A legjobb gyakorlat a generálás és a letöltés láncolása ugyanabban a függvényben, így lehetetlenné válik e lépés elfelejtése.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Generál egy videót és helyben elmenti (kliens: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Azonnali letöltés
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"Videó elmentve: {output_file}")
return output_file
Ha tárhelyre szeretnéd menteni a videót anélkül, hogy az áthaladna a szervereden, a generálás storage_options paramétere az xAI Files API-ba helyezi a videót, az általad választott lejárati idővel.
Több videó egyszerre történő generálása
Az aszinkron klienssel minden hívás egy korutin, és az asyncio.gather egyszerre indít el egy teljes köteget. A return_exceptions=True opció itt döntő fontosságú: nélküle egyetlen elutasított kérés meghiúsítaná az egész köteget, és elveszítenéd a már megszerzett eredményeket.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Több videó párhuzamos generálása."""
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"{i}. kérés sikertelen: {res}")
else:
print(f"{i}. kérés kész: {res.url}")
return results
Két védőkorlát keretezi ezt a párhuzamosítást. A beküldések消耗ják a sebességkorlátozásodat (rate limit), amelyet a csapatod szintje szerint másodpercenkénti kérésekben mérnek (a videómodelleknél a belépő szinten 10): nagy köteg esetén korlátozd a konkurenciát egy asyncio.Semaphore segítségével. Emlékezz arra is, mit csinál és mit nem csinál a párhuzamosítás: nem gyorsítja fel az egyes generálásokat, csak a teljes köteg idejét csökkenti.
El kellene hagynod a kézi lekérdezést?
Nem feltétlenül. Az alábbi összehasonlítás bemutatja, melyik megközelítés mikor előnyös.
| Szempont | Kézi lekérdezés | SDK |
|---|---|---|
| Komplexitás | Magas | Alacsony |
| Hibakezelés | Implementálandó | Beépített |
| Időtúllépés (Timeout) | Implementálandó | 10 perc alapértelmezetten, konfigurálható |
| Lekérdezési időköz | Választandó | 1 mp alapértelmezetten, konfigurálható |
| Rugalmasság | Teljes | Standard (vagy start és get) |
| Függőség | Nincs | xAI SDK |
A kézi lekérdezés két helyzetben őrzi meg a relevanciáját: amikor finomhangolt kontrollra van szükséged – például a haladás valós idejű interfészre történő továbbításához vagy egy meglévő sorkezelő rendszerbe való integráláshoz –, és amikor a telepítési kontextusod megtiltja további függőségek hozzáadását.
Főbb megállapítások
- A
client.video.generatebeküldi a kérést, vár, majd visszaadja a videót (url,duration,model); alapértelmezetten 10 perces időtúllépés és másodpercenkénti ellenőrzés - A szerkesztés a
generatehasználatát jelentivideo_urlparaméterrel, a bővítéshez aclient.video.extendszolgál - A
VideoGenerationError(azxai_sdk.videomodulból), aTimeoutErrorés aRuntimeErrormegkülönböztetik a hibákat; a sebességkorlátokgrpc.RpcErrorként érkeznek - Mindig töltsd le a videót azonnal a generálás után (ideiglenes URL-ek)
- Az aszinkron kliens és az
asyncio.gatherpárhuzamosítja a kötegeket a szinted sebességkorlátain belül