xAI SDK ir automatinis apklausimas
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. remiantis xAI vaizdo dokumentacija ir
xai-sdk1.21.0 kodu: metodai vadinamiclient.video.generateirclient.video.extend(redagavimui naudojamasgeneratesuvideo_url), rezultatas pateikiaurl, delsos laikas nustatomas pertimedelta, o numatytasis apklausos intervalas yra viena sekundė.awaitreikalauja asinchroninio klientoAsyncClient, o išimtisVideoGenerationErrorimportuojama išxai_sdk.video. Senoji versija naudojo metodus ir išimties modulį, kurių nėra. Šaltiniai: Vaizdo generavimas · Vaizdo redagavimas · Vaizdo pratęsimas · xai-sdk-python.
Supaprastinkite apklausą naudodami SDK
Ankstesnėje pamokoje turėjote rankiniu būdu parašyti apklausos ciklą. Tai naudinga pratimas norint suprasti generavimo gyvavimo ciklą, tačiau tai taip pat trisdešimt eilučių kodo, kurias reikia prižiūrėti kiekviename projekte, kartu su savo laiko limito valdymu, klaidų atvejais ir būsenų konvertavimu. Oficialus xAI Python SDK (pip install xai-sdk) visa tai apgaubia: jūs pateikiate užklausą, o jis pasirūpina laukimu.
Vienas kvietimas vietoj ciklo
Metodas client.video.generate sujungia pateikimą, stebėjimą ir gavimą. Jis grąžina kontrolę tik tada, kai vaizdo įrašas paruoštas, arba išmeta išimtį, jei kažkas nepavyko.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Teksto į vaizdo įrašą generavimas su automatine apklausa
video = client.video.generate(
prompt="Saulėtekis virš Alpių, pagreitintas laiko tarpų vaizdo įrašas",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Trukmė: {video.duration} s, modelis: {video.model}")
Už šių kelių eilučių slypi tai, kad SDK daro būtent tai, ką kodavote anksčiau: pateikia užklausą, kas sekundę (pagal nutylėjimą) tikrina būseną, o tada grąžina rezultatą arba, priklausomai nuo baigties, išmeta išimtį.
Vienas nustatymas nusipelno jūsų dėmesio jau diegimo metu: pagal nutylėjimą SDK laukia iki 10 minučių, prieš pasiduodamas. Tai patogu naktiniam gamybos scenarijui, tačiau per ilga web užklausai, kurioje vartotojas laukia atsakymo. Parametrai timeout ir interval, abu esantys timedelta objektai, nustato ribą ir ritmą:
from datetime import timedelta
video = client.video.generate(
prompt="Jūsų aprašymas",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # daugiausia 5 minutės
interval=timedelta(seconds=5), # vienas patikrinimas kas 5 sekundes
)
Jei norite išlaikyti kontrolę over laukimo – pavyzdžiui, norėdami perduoti eigą – client.video.start pateikia užklausą ir grąžina jos request_id, kurį vėliau užklausia client.video.get.
Tvarkykite klaidas ties šaltiniu
SDK atskiria gedimus, taip sutaupydamas jums poreikį analizuoti tekstines eilutes norint išsiaiškinti, kas nutiko:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Jūsų aprašymas",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Vaizdo įrašas paruoštas: {video.url}")
except VideoGenerationError as e:
print(f"Generavimas nepavyko [{e.code}]: {e.message}")
except TimeoutError:
print("Viršytas laiko limitas: padidinkite timeout arba supaprastinkite užklausą")
Kiekviena klaida reikalauja skirtingos reakcijos, o jų painiojimas lemia nenaudingus kartojimo ciklus arba, dar blogiau, apmokestintus generavimus, kurie neduoda jokio rezultato.
| Klaida | Priežastis | Rekomenduojamas veiksmas |
|---|---|---|
VideoGenerationError | API signalizuotas gedimas: promptas atmestas, netinkamas šaltinis, perkrauta tarnyba… (code, message) | Perskaitykite kodą: pataisykite užklausą arba bandykite vėliau, jei tarnyba buvo nepasiekiama |
TimeoutError | Viršytas kliento pusės laukimo laikas | Padidinkite timeout arba sumažinkite trukmę |
RuntimeError | Atidėta užklausa baigė galioti arba užbaigta be rezultato | Paleiskite generavimą iš naujo |
grpc.RpcError | SDK transporto klaida, įskaitant dažnio ribas (kodas RESOURCE_EXHAUSTED) ir rakto problemas | Retinkite užklausas taikydami „backoff“ strategiją arba patikrinkite raktą |
SDK naudoja gRPC: viršyta dažnio riba čia neatrodo kaip HTTP 429 kodas, o kaip grpc.RpcError su kodu RESOURCE_EXHAUSTED.
Redagavimas ir pratęsimas – tas pats paprastumas
Redagavimas neturi atskiro metodo: tai generate su šaltinio vaizdo įrašu, perduodamu kaip video_url (vaizdo įrašas iki 8,7 sekundės, tokia pati išvesties trukmė, daugiausia 720p).
video = client.video.generate(
prompt="Paverskite sceną japoniško animė stiliumi",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Pratęsimas prailgina 2–15 sekundžių sekunciją 2–10 sekundžių segmentu ir grąžina visą vaizdo įrašą:
video = client.video.extend(
prompt="Tęskite sceną panoramuojant į dešinę",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Atkreipkite dėmesį į skirtumą nuo REST API: SDK priima vaizdo įrašą kaip video_url parametrą, tuo tarpu JSON kūnas tikisi video objekto su jo url savybe.
Niekada nepalikite vaizdo įrašo debesyje
SDK nieko nekeičia rezultato URL laikinumo. Jei jūsų kodas tiesiog rodo video.url, sumokėjote už generavimą, kuris netrukus dings. Geriausia praktika – grandininėje grandinėje sujungti generavimą ir atsisiuntimą toje pačioje funkcijoje, kad taptų neįmanoma pamiršti šio žingsnio.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Generuoja vaizdo įrašą ir išsaugo jį lokaliai (klientas: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Momentinis atsisiuntimas
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"Vaizdo įrašas išsaugotas: {output_file}")
return output_file
Saugojimui be perėjimo per jūsų serverį, generavimo parametras storage_options įkelia vaizdo įrašą į xAI Files API su jūsų pasirinktu galiojimo laiku.
Generuokite kelis vaizdo įrašus vienu metu
Naudojant asinchroninį klientą, kiekvienas kvietimas yra korutina, o asyncio.gather paleidžia visą grupę lygiagrečiai. Čia lemiamas yra return_exceptions=True pasirinkimas: be jo, viena atmesta užklausa sugadintų visą grupę ir prarastumėte jau gautus rezultatus.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Generuoja kelis vaizdo įrašus lygiagrečiai."""
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"Užklausa {i} nepavyko: {res}")
else:
print(f"Užklausa {i} baigta: {res.url}")
return results
Šį lygiagretinimą rėmina dvi apsaugos priemonės. Pateikimai sunaudoja jūsų dažnio ribą, skaičiuojamą užklausomis per sekundę pagal jūsų komandos lygį (10 pradiniame lygyje vaizdo modeliams): didelėms grupėms apribokite konkurenciją naudodami asyncio.Semaphore. Taip pat prisiminkite, ką lygiagretumas daro ir ko nedaro: jis nepagreitina jokio individualaus generavimo, jis tik sumažina bendrą grupės laiką.
Ar turėtumėte atsisakyti rankinės apklausos?
Ne sistemingai. Toliau pateiktas palyginimas rodo, kur kiekvienas požiūris pirmauja.
| Aspektas | Rankinė apklausa | SDK |
|---|---|---|
| Sudėtingumas | Aukštas | Žemas |
| Klaidų valdymas | Reikia įgyvendinti | Integruota |
| Laiko limitas | Reikia įgyvendinti | 10 min. pagal nutylėjimą, konfigūruojama |
| Apklausos intervalas | Reikia pasirinkti | 1 s pagal nutylėjimą, konfigūruojama |
| Lankstumas | Visiškas | Standartinis (arba start ir get) |
| Priklausomybė | Nėra | xAI SDK |
Rankinė apklausa išlaiko savo aktualumą dviejose situacijose: kai jums reikia tikslios kontrolės, pavyzdžiui, norint perduoti eigą realiuoju laiku veikiančiai sąsajai arba integruoti į esamą eilių sistemą, ir kai jūsų diegimo kontekstas draudžia pridėti papildomą priklausomybę.
Svarbiausi punktai
client.video.generatepateikia, palaukia ir grąžina vaizdo įrašą (url,duration,model); pagal nutylėjimą 10 minučių laiko limitas ir vienos sekundės patikrinimas- Redagavimui naudojamas
generatesuvideo_url, pratęsimui –client.video.extend VideoGenerationError(išxai_sdk.video),TimeoutErrorirRuntimeErroratskiria gedimus; dažnio ribos ateina kaipgrpc.RpcError- Visada atsisiųskite vaizdo įrašą iškart po generavimo (laikini URL)
- Asinchroninis klientas ir
asyncio.gatherlygiagrečiai apdoroja grupes, laikydamiesi jūsų lygio dažnio ribos