xAI SDK in samodejno anketiranje
Na tej strani
Posodobljeno 2. novembra 2026 na podlagi dokumentacije za videoposnetke xAI in kode
xai-sdk1.21.0: metodi se imenujetaclient.video.generateinclient.video.extend(urejanje uporabljagenerates parametromvideo_url), rezultat razkrivaurl, zamik se nastavi prektimedelta, privzeti interval anketiranja pa je ena sekunda.awaitzahteva asinhroni odjemalecAsyncClient, izjemaVideoGenerationErrorpa se uvozi izxai_sdk.video. Stara različica je klicala metode in modul izjem, ki ne obstajata. Viri: Ustvarjanje videoposnetkov · Urejanje videoposnetkov · Razširjanje videoposnetkov · xai-sdk-python.
Poenostavi anketiranje s SDK-jem
V prejšnji lekciji si moral ročno napisati zanko za anketiranje. To je koristna vaja za razumevanje življenjskega cikla ustvarjanja, a hkrati pomeni trideset vrstic kode, ki jih moraš vzdrževati v vsakem projektu, z lastnim upravljanjem časovnih omejitev, primeri napak in pretvorbami stanj. Uradni Python SDK za xAI (pip install xai-sdk) vse to encapsulira: zahtevo oddaš, on pa poskrbi za čakanje.
En klic namesto zanke
Metoda client.video.generate združuje oddajo, sledenje in pridobivanje. Nadzor vrne šele, ko je videoposnetek pripravljen, ali pa sproži izjemo, če je šlo kaj narobe.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Ustvarjanje besedilo-videoposnetek s samodejnim anketiranjem
video = client.video.generate(
prompt="Sončni vzhod nad Alpami, pospešeni časovni zamik",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Trajanje: {video.duration} s, model: {video.model}")
Za temi nekaj vrsticami SDK stori točno tisto, kar si prej kodiral sam: odda zahtevo, vsako sekundo (privzeto) preveri stanje in nato vrne rezultat ali sproži izjemo, odvisno od izida.
Ena nastavitev si zasluži tvojo pozornost takoj ob uvajanju: privzeto SDK čaka do 10 minut, preden odneha. To je udobno za nočno produkcijsko skripto, a predolgo za spletni zahtevek, kjer uporabnik čaka na odgovor. Parametra timeout in interval, oba objekta timedelta, določata časovno omejitev in ritem:
from datetime import timedelta
video = client.video.generate(
prompt="Tvoj opis",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # največ 5 minut
interval=timedelta(seconds=5), # en preverjanje vsakih 5 sekund
)
Če želiš obdržati nadzor nad čakanjem – na primer za posredovanje napredka – client.video.start odda zahtevo in vrne njen request_id, ki ga nato poizveduje client.video.get.
Obravnava napak pri viru
SDK razlikuje med napakami, kar te reši analiziranja nizov, da bi ugotovil, kaj se je zgodilo:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Tvoj opis",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Videoposnetek pripravljen: {video.url}")
except VideoGenerationError as e:
print(f"Ustvarjanje ni uspelo [{e.code}]: {e.message}")
except TimeoutError:
print("Časovna omejitev presežena: povečaj timeout ali poenostavi zahtevo")
Vsaka napaka zahteva drugačen odziv; njihovo mešanje vodi v neuporabne zanke za ponovne poskuse ali, kar je še huje, v zaračunana ustvarjanja, ki ne obrodijo sadov.
| Napaka | Vzrok | Priporočeno dejanje |
|---|---|---|
VideoGenerationError | Napaka, ki jo signalizira API: zavrnjen poziv, neveljaven vir, preobremenjena storitev … (code, message) | Preberi kodo: popravi zahtevo ali poskusi znova kasneje, če storitev ni bila na voljo |
TimeoutError | Na strani odjemalca je potekel čas čakanja | Povečaj timeout ali skrajšaj trajanje |
RuntimeError | Odložena zahteva je potekla ali zaključena brez rezultata | Ponovno zaženi ustvarjanje |
grpc.RpcError | Napaka prenosa v SDK, vključno z omejitvami hitrosti (koda RESOURCE_EXHAUSTED) in težavami s ključem | Razporedi zahteve z zamikom (backoff) ali preveri ključ |
SDK uporablja gRPC: presežena omejitev hitrosti se tu ne pojavi kot koda HTTP 429, temveč kot grpc.RpcError s kodo RESOURCE_EXHAUSTED.
Urejanje in razširjanje z enako lahkoto
Urejanje nima posebne metode: gre za generate z izvornim videoposnetkom, podanim kot video_url (videoposnetek do 8,7 sekunde, izhod istega trajanja, največ 720p).
video = client.video.generate(
prompt="Preoblikuj prizor v stil japonske anime",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Razširjanje podaljša zaporedje od 2 do 15 sekund za segment od 2 do 10 sekund in vrne celoten videoposnetek:
video = client.video.extend(
prompt="Nadaljuj prizor s premikom kamere v desno",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Opazi razliko glede na REST API: SDK sprejme videoposnetek kot parameter video_url, medtem ko telo JSON pričakuje objekt video z lastnostjo url.
Nikoli ne puščaj videoposnetka v oblaku
SDK ne spremeni ničesar glede začasne narave URL-jev rezultatov. Če tvoja koda le prikaže video.url, si plačal ustvarjanje, ki bo kmalu izginilo. Najboljša praksa je povezati ustvarjanje in prenos v isto funkcijo, tako da postane nemogoče pozabiti ta korak.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Ustvari videoposnetek in ga shrani lokalno (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Takojšen prenos
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"Videoposnetek shranjen: {output_file}")
return output_file
Za shranjevanje brez prenosa skozi tvoj strežnik parameter storage_options pri ustvarjanju odloži videoposnetek v xAI Files API z iztekom po tvoji izbiri.
Sočasno ustvarjanje več videoposnetkov
Z asinhronim odjemalcem je vsak klic korutina, asyncio.gather pa sproži celoten paket vzporedno. Tu je odločilna možnost return_exceptions=True: brez nje bi ena sama zavrnjena zahteva spodletela celotnemu paketu in izgubil bi že pridobljene rezultate.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Vzporedno ustvari več videoposnetkov."""
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"Zahteva {i} ni uspela: {res}")
else:
print(f"Zahteva {i} zaključena: {res.url}")
return results
Dva varnostna mehanizma okvirjata to vzporednost. Oddaje porabijo tvojo omejitev hitrosti, ki se šteje v zahtevah na sekundo glede na raven tvoje ekipe (10 na vstopni ravni za video modele): za velik paket omeji sočasnost z asyncio.Semaphore. Spomni se tudi, kaj vzporednost počne in česa ne: ne pospeši posameznega ustvarjanja, le skrajša skupni čas paketa.
Naj opustiš ročno anketiranje?
Ne nujno. Naslednja primerjava kaže, kje vsak pristop prevlada.
| Vidik | Ročno anketiranje | SDK |
|---|---|---|
| Zahtevnost | Visoka | Nizka |
| Obravnava napak | Za implementacijo | Integrirana |
| Časovna omejitev | Za implementacijo | Privzeto 10 min, nastavljivo |
| Interval anketiranja | Izbira | Privzeto 1 s, nastavljivo |
| Fleksibilnost | Popolna | Standardna (ali start in get) |
| Odvisnost | Nobena | xAI SDK |
Ročno anketiranje ohranja smisel v dveh situacijah: ko potrebuješ natančen nadzor, na primer za posredovanje napredka v vmesnik v realnem času ali za integracijo v obstoječi sistem čakalnih vrst, in ko tvoj kontekst uvajanja prepoveduje dodajanje dodatne odvisnosti.
Ključne ugotovitve
client.video.generateodda, počaka in vrne videoposnetek (url,duration,model); privzeta časovna omejitev je 10 minut, preverjanje vsako sekundo- Urejanje uporablja
generatezvideo_url, razširjanje paclient.video.extend VideoGenerationError(izxai_sdk.video),TimeoutErrorinRuntimeErrorrazlikujejo napake; omejitve hitrosti prispejo kotgrpc.RpcError- Videoposnetek vedno takoj prenesi po ustvarjanju (začasni URL-ji)
- Asinhroni odjemalec in
asyncio.gathervzporedita paket znotraj omejitve hitrosti tvoje ravni