xAI SDK i automatsko anketiranje
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju xAI dokumentacije za videozapise i koda
xai-sdkverzije 1.21.0: metode se nazivajuclient.video.generateiclient.video.extend(uređivanje koristigeneratesvideo_url), rezultat izlažeurl, kašnjenje se postavlja putemtimedelta, a zadani interval anketiranja je jedna sekunda.awaitzahtijeva asinkroni klijentAsyncClient, a iznimkaVideoGenerationErroruvozi se izxai_sdk.video. Stara verzija pozivala je metode i modul iznimki koji ne postoje. Izvori: Generiranje videa · Uređivanje videa · Proširenje videa · xai-sdk-python.
Pojednostavi anketiranje pomoću SDK-a
Prethodna lekcija tražila je da ručno napišeš petlju za anketiranje. To je korisna vježba za razumijevanje životnog ciklusa generiranja, ali također predstavlja trideset linija koda koje trebaš održavati u svakom projektu, s vlastitim rukovanjem istekom vremena, slučajevima neuspjeha i pretvorbama statusa. Službeni Python SDK tvrtke xAI (pip install xai-sdk) encapsulira sve ovo: ti pošalješ zahtjev, a on se brine za čekanje.
Jedan poziv umjesto petlje
Metoda client.video.generate grupira slanje, praćenje i dohvaćanje. Vraća kontrolu tek kada je videozapis spreman ili podiže iznimku ako nešto pođe po zlu.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Generiranje teksta u video s automatskim anketiranjem
video = client.video.generate(
prompt="Izlazak sunca iznad Alpa, ubrzani time-lapse",
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}")
Iza ovih nekoliko linija, SDK radi točno ono što si prethodno kodirao: šalje zahtjev, anketira status svake sekunde prema zadanim postavkama, a zatim vraća rezultat ili podiže iznimku ovisno o ishodu.
Jedna postavka zaslužuje tvoju pozornost odmah pri implementaciji: prema zadanim postavkama, SDK čeka do 10 minuta prije odustajanja. To je ugodno za noćnu produkcijsku skriptu, ali predugo za web zahtjev gdje korisnik čeka odgovor. Parametri timeout i interval, oba objekti timedelta, postavljaju ograničenje i ritam:
from datetime import timedelta
video = client.video.generate(
prompt="Tvoj opis",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # maks. 5 minuta
interval=timedelta(seconds=5), # jedna provjera svakih 5 sekundi
)
Ako želiš zadržati kontrolu nad čekanjem – na primjer, za prosljeđivanje napretka – client.video.start šalje zahtjev i vraća njegov request_id, koji client.video.get zatim ispituje.
Rukuj greškama u izvoru
SDK razlikuje neuspjehe, što te spašava od analiziranja nizova kako bi shvatio što se dogodilo:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Tvoj opis",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video spreman: {video.url}")
except VideoGenerationError as e:
print(f"Generiranje nije uspjelo [{e.code}]: {e.message}")
except TimeoutError:
print("Vrijeme čekanja je isteklo: povećaj timeout ili pojednostavi zahtjev")
Svaka greška zahtijeva drugačiju reakciju, a njihovo miješanje vodi do beskorisnih petlji ponovnih pokušaja ili, što je gore, naplaćenih generiranja koja ne daju rezultat.
| Greška | Uzrok | Preporučena radnja |
|---|---|---|
VideoGenerationError | Neuspjeh koji signalizira API: odbijen prompt, neispravan izvor, preopterećena usluga… (code, message) | Pročitaj kod: ispravi zahtjev ili pokušaj ponovno kasnije ako usluga nije bila dostupna |
TimeoutError | Prekoračeno vrijeme čekanja na strani klijenta | Povećaj timeout ili smanji trajanje |
RuntimeError | Odgođeni zahtjev je istekao ili je završen bez rezultata | Ponovno pokreni generiranje |
grpc.RpcError | Greška transporta SDK-a, uključujući ograničenja stope (kod RESOURCE_EXHAUSTED) i probleme s ključem | Razmakni zahtjeve s backoffom ili provjeri ključ |
SDK koristi gRPC: prekoračeno ograničenje stope ovdje se ne pojavljuje kao HTTP kod 429, već kao grpc.RpcError s kodom RESOURCE_EXHAUSTED.
Uređivanje i proširenje, ista jednostavnost
Uređivanje nema namjensku metodu: to je generate s izvornim videozapisom, proslijeđenim kao video_url (videozapis do 8,7 sekundi, isto trajanje izlaza, maks. 720p).
video = client.video.generate(
prompt="Transformiraj scenu u stil japanskog animea",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Proširenje produžuje sekvencu od 2 do 15 sekundi za segment od 2 do 10 sekundi i vraća cijeli videozapis:
video = client.video.extend(
prompt="Nastavi scenu panoramom udesno",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Imaj na umu razliku s REST API-jem: SDK prima videozapis kao parametar video_url, dok JSON tijelo očekuje objekt video sa svojim svojstvom url.
Nikada ne ostavljaj videozapis u oblaku
SDK ništa ne mijenja u privremenoj prirodi URL-ova rezultata. Ako tvoj kod samo prikazuje video.url, platio si generiranje koje će uskoro nestati. Najbolja praksa je lančano povezati generiranje i preuzimanje u istoj funkciji, tako da postane nemoguće zaboraviti taj korak.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Generira videozapis i sprema ga lokalno (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Trenutačno preuzimanje
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"Videozapis spremljen: {output_file}")
return output_file
Za pohranu bez prolaska kroz tvoj poslužitelj, parametar storage_options generiranja polaže videozapis u xAI Files API, s istekom po tvom izboru.
Generiraj više videozapisa odjednom
S asinkronim klijentom, svaki poziv je korutina, a asyncio.gather pokreće cijelu seriju paralelno. Opcija return_exceptions=True ovdje je odlučujuća: bez nje, jedan odbijen zahtjev bi propao cijelu seriju i izgubio bi rezultate koji su već dobiveni.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Generira više videozapisa paralelno."""
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"Zahtjev {i} nije uspio: {res}")
else:
print(f"Zahtjev {i} dovršen: {res.url}")
return results
Dva zaštitna mehanizma okviruju ovu paralelizaciju. Podnošenja troše tvoje ograničenje stope, koje se broji u zahtjevima u sekundi prema razini tvog tima (10 na ulaznoj razini za video modele): za veliku seriju, ograniči konkurentnost s asyncio.Semaphore. Također se sjeti što paralelizam radi, a što ne: ne ubrzava nijedno pojedinačno generiranje, već samo smanjuje ukupno vrijeme serije.
Trebaš li odustati od ručnog anketiranja?
Ne sustavno. Sljedeća usporedba pokazuje gdje svaki pristup prednjači.
| Aspekt | Ručno anketiranje | SDK |
|---|---|---|
| Složenost | Visoka | Niska |
| Rukovanje greškama | Za implementaciju | Integrirano |
| Istek vremena | Za implementaciju | Zadano 10 min, podesivo |
| Interval anketiranja | Za odabir | Zadano 1 s, podesivo |
| Fleksibilnost | Potpuna | Standardna (ili start i get) |
| Ovisnost | Nema | xAI SDK |
Ručno anketiranje zadržava svoju relevantnost u dvije situacije: kada ti treba fina kontrola, na primjer za prosljeđivanje napretka sučelju u stvarnom vremenu ili za integraciju u postojeći sustav redova čekanja, i kada tvoj kontekst implementacije zabranjuje dodavanje dodatne ovisnosti.
Ključne točke
client.video.generatešalje, čeka i vraća videozapis (url,duration,model); zadano vrijeme čekanja 10 minuta i provjera svake sekunde- Uređivanje koristi
generatesvideo_url, proširenje koristiclient.video.extend VideoGenerationError(izxai_sdk.video),TimeoutErroriRuntimeErrorrazlikuju neuspjehe; ograničenja stope dolaze kaogrpc.RpcError- Uvijek odmah preuzmi videozapis nakon generiranja (privremeni URL-ovi)
- Asinkroni klijent i
asyncio.gatherparaleliziraju seriju, unutar ograničenja stope tvoje razine