xAI SDK ja automaatne päringute tegemine
Sellel lehel
Uuendatud 2. novembril 2026 vastavalt xAI video dokumentatsioonile ja
xai-sdk1.21.0 koodile: meetodid onclient.video.generatejaclient.video.extend(redigeerimine kasutabgeneratekoosvideo_url-ga), tulemus avaldaburl, viivise määrabtimedeltaja vaikimisi päringute vaheline intervall on üks sekund.awaiteeldab asünkroonset klientiAsyncClientja erindVideoGenerationErrorimporditakse moodulistxai_sdk.video. Vana versioon kasutas meetodeid ja erindimooduleid, mida tegelikult ei eksisteeri. Allikad: Video Generation · Video Editing · Video Extension · xai-sdk-python.
Lihtsusta päringute tegemist SDK-ga
Eelmises õppetükis pidid kirjutama päringutsükli käsitsi. See on kasulik harjutus genereerimise elutsükli mõistmiseks, kuid samas tähendab see iga projekti jaoks hooldatavat kolmekümne realist koodi koos oma ajaülemiku halduse, tõrkejuhtumite ja olekute teisendustega. xAI ametlik Pythoni SDK (pip install xai-sdk) kapseldab kogu selle: saadad päringu ja see haldab ootamist sinu eest.
Üks väljakutse tsükli asemel
Meetod client.video.generate ühendab päringu esitamise, jälgimise ja tulemuse hankimise. See annab kontrolli tagasi alles siis, kui video on valmis, või viskab erindi, kui midagi läks valesti.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Tekstist videoks genereerimine automaatse päringutega
video = client.video.generate(
prompt="Päikesetõus Alpides, kiirendatud ajakaader",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Kestus: {video.duration} s, mudel: {video.model}")
Nende paari rea taga teeb SDK täpselt seda, mida sa varem ise kodeerisid: saadab päringu, kontrollib olekut vaikimisi iga sekundi tagant ja tagastab tulemuse või viskab erindi sõltuvalt tulemusest.
Üks seadistus väärib tähelepanu kohe kasutuselevõtul: vaikimisi ootab SDK kuni 10 minutit, enne kui loobub. See sobib öiseks tootmisskriptiks, kuid on veebipäringu jaoks, kus kasutaja ootab vastust, palju liiga pikk. Parameetrid timeout ja interval, mõlemad timedelta objektid, määravad piirangu ja rütmi:
from datetime import timedelta
video = client.video.generate(
prompt="Sinu kirjeldus",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # maksimaalselt 5 minutit
interval=timedelta(seconds=5), # üks kontroll iga 5 sekundi järel
)
Kui soovid ooteaja üle kontrolli säilitada – näiteks edenemise edastamiseks –, siis client.video.start saadab päringu ja tagastab selle request_id, mida client.video.get seejärel päringuga kontrollib.
Käitle vead allikal
SDK eristab tõrkeid, säästes sind stringide analüüsimisest, et aru saada, mis juhtus:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Sinu kirjeldus",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video valmis: {video.url}")
except VideoGenerationError as e:
print(f"Genereerimine ebaõnnestus [{e.code}]: {e.message}")
except TimeoutError:
print("Ajaülemik ületatud: suurenda aegaülemikut või lihtsusta päringut")
Iga viga nõuab erinevat reaktsiooni ja nende segiajamine viib kasutute korduskatsete tsükliteni või, mis veel hullem, arvestatud genereerimisteni, mis ei too mingit tulemust.
| Viga | Põhjus | Soovitatav tegevus |
|---|---|---|
VideoGenerationError | API poolt signaliseeritud tõrge: vihje tagasilükkamine, vigane allikas, teenuse ülekoormus… (code, message) | Loe koodi: paranda päringut või proovi hiljem uuesti, kui teenus oli kättesaamatu |
TimeoutError | Kliendi poolne ooteaeg ületatud | Suurenda timeout väärtust või vähenda kestust |
RuntimeError | Edasilükatud päring aegus või lõpetati ilma tulemuseta | Taaskäivita genereerimine |
grpc.RpcError | SDK transpordiviga, sh kiirusepiirangud (kood RESOURCE_EXHAUSTED) ja võtmeprobleemid | Hajuta päringuid tagasilöögiga või kontrolli võtit |
SDK kasutab gRPC-i: ületatud kiirusepiirang ei ilmu siin HTTP 429 koodina, vaid kui grpc.RpcError koodiga RESOURCE_EXHAUSTED.
Redigeerimine ja pikendamine sama lihtsusega
Redigeerimisel puudub eraldi meetod: see on generate koos lähtevideoga, mis antakse parameetrina video_url (video kuni 8,7 sekundit, sama pikkusega väljund, maksimaalselt 720p).
video = client.video.generate(
prompt="Teisenda stseen Jaapani anime stiili",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Pikendamine pikendab 2–15 sekundi pikkust järjestust 2–10 sekundi lõiguga ja tagastab kogu video:
video = client.video.extend(
prompt="Jätka stseeni paremale panoraamimisega",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Pane tähele erinevust REST API-ga: SDK võtab video vastu parameetrina video_url, samas kui JSON-i keha eeldab objekti video koos selle omadusega url.
Ära jäta videot kunagi pilve
SDK ei muuda midagi tulemuse URL-ide ajutises olemuses. Kui su kood lihtsalt kuvab video.url, siis maksid genereerimise eest, mis varsti kaob. Parim tava on aheldada genereerimine ja allalaadimine samas funktsioonis, nii et selle sammu unustamine muutub võimatuks.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Genereerib video ja salvestab selle lokaalselt (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Kohene allalaadimine
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 salvestatud: {output_file}")
return output_file
Salvestamiseks ilma serveri kaudu edastamiseta deponeerib genereerimise parameeter storage_options video xAI Files API-sse sinu valitud aegumistähtajaga.
Genereeri mitu videot korraga
Asünkroonse kliendi puhul on iga väljakutse korutiin ja asyncio.gather käivitab terve partii paralleelselt. Siin on otsustava tähtsusega valik return_exceptions=True: ilma selleta nurjuks üksik tagasilükatud päringu tõttu kogu partii ja kaotaksid juba saadud tulemused.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Genereerib mitu videot paralleelselt."""
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"Päring {i} ebaõnnestus: {res}")
else:
print(f"Päring {i} lõpetatud: {res.url}")
return results
Seda paralleelsust raamivad kaks kaitsepiiret. Päringute esitamine tarbib sinu kiirusepiirangut, mida loendatakse päringutes sekundis vastavalt sinu meeskonna tasemele (videomudelite puhul on algtasemel 10): suure partii puhul piira samaaegsust asyncio.Semaphore-iga. Pea meeles ka seda, mida paralleelsus teeb ja mida mitte: see ei kiirenda ühtegi üksikut genereerimist, vaid vähendab ainult kogu partii koguaega.
Kas peaksid käsitsi päringute tegemisest loobuma?
Mitte süstemaatiliselt. Järgnev võrdlus näitab, kus kumb lähenemine juhtpositsiooni haarab.
| Aspekt | Käsitsi päringud | SDK |
|---|---|---|
| Komplekssus | Kõrge | Madal |
| Vigade käitlemine | Tuleb ise realiseerida | Integreeritud |
| Ajaülemik | Tuleb ise realiseerida | Vaikimisi 10 min, konfigureeritav |
| Päringute intervall | Tuleb valida | Vaikimisi 1 s, konfigureeritav |
| Paindlikkus | Täielik | Standardne (või start ja get) |
| Sõltuvus | Puudub | xAI SDK |
Käsitsi päringud säilitavad oma asjakohasuse kahes olukorras: kui vajad peent kontrolli, näiteks edenemise edastamiseks reaalajas liidesesse või integreerimiseks olemasolevasse järjekorrasüsteemi, ja kui sinu kasutuselevõtu kontekst keelab täiendava sõltuvuse lisamise.
Peamised punktid
client.video.generateesitab päringu, ootab ja tagastab video (url,duration,model); vaikimisi 10-minutiline aegaülemik ja ühesekundiline kontroll- Redigeerimine kasutab
generatekoosvideo_url-ga, pikendamine kasutabclient.video.extend VideoGenerationError(moodulistxai_sdk.video),TimeoutErrorjaRuntimeErroreristavad tõrkeid; kiirusepiirangud saabuvad kuigrpc.RpcError- Laadi video alati kohe pärast genereerimist alla (ajutised URL-id)
- Asünkroonne klient ja
asyncio.gatherparalleelivad partiid, jäädes sinu taseme kiirusepiirangu piiresse