SDK xAI și interogarea automată
Pe această pagină
Actualizat pe 2 noiembrie 2026 pe baza documentației video xAI și a codului
xai-sdk1.21.0: metodele se numescclient.video.generateșiclient.video.extend(editarea foloseștegeneratecuvideo_url), rezultatul expuneurl, întârzierea se setează printr-untimedelta, iar intervalul implicit de interogare este de o secundă.awaitnecesită clientul asincronAsyncClient, iar excepțiaVideoGenerationErrorse importă dinxai_sdk.video. Versiunea veche apela metode și un modul de excepții care nu există. Surse: Generare video · Editare video · Extindere video · xai-sdk-python.
Simplificați interogarea cu SDK-ul
Lecția anterioară v-a cerut să scrieți manual o buclă de interogare. Este un exercițiu util pentru a înțelege ciclul de viață al generării, dar reprezintă și treizeci de linii de cod de întreținut în fiecare proiect, cu propria sa gestionare a timpului de așteptare, a cazurilor de eșec și a conversiilor de stare. SDK-ul oficial Python al xAI (pip install xai-sdk) încapsulează toate acestea: dumneavoastră trimiteți cererea, iar el se ocupă de așteptare.
O singură apelare în loc de o buclă
Metoda client.video.generate grupează trimiterea, urmărirea și preluarea. Aceasta returnează controlul doar atunci când videoclipul este gata sau ridică o excepție dacă ceva nu a funcționat.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Generare text-to-video cu interogare automată
video = client.video.generate(
prompt="Un răsărit peste Alpi, time-lapse accelerat",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Durată: {video.duration} s, model: {video.model}")
În spatele acestor câteva linii, SDK-ul face exact ceea ce ați codificat anterior: trimite cererea, interoghează starea la fiecare secundă (implicit), apoi returnează rezultatul sau ridică o excepție în funcție de rezultat.
O setare merită atenția dumneavoastră chiar de la început: implicit, SDK-ul așteaptă până la 10 minute înainte de a renunța. Acest lucru este confortabil pentru un script de producție nocturn, dar mult prea lung pentru o cerere web în care un utilizator așteaptă un răspuns. Parametrii timeout și interval, ambele obiecte timedelta, setează limita și ritmul:
from datetime import timedelta
video = client.video.generate(
prompt="Descrierea dumneavoastră",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # maxim 5 minute
interval=timedelta(seconds=5), # o verificare la fiecare 5 secunde
)
Dacă doriți să păstrați controlul asupra așteptării – pentru a relata progresul, de exemplu – client.video.start trimite cererea și returnează request_id-ul acesteia, pe care client.video.get îl interoghează ulterior.
Gestionați erorile la sursă
SDK-ul distinge eșecurile, scutindu-vă de analiza șirurilor de caractere pentru a afla ce s-a întâmplat:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Descrierea dumneavoastră",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video gata: {video.url}")
except VideoGenerationError as e:
print(f"Generare eșuată [{e.code}]: {e.message}")
except TimeoutError:
print("Timp de așteptare depășit: măriți timeout-ul sau simplificați cererea")
Fiecare eroare necesită o reacție diferită, iar confundarea lor duce la bucle de reîncercare inutile sau, mai rău, la generări facturate care nu yieldă nimic.
| Eroare | Cauză | Acțiune recomandată |
|---|---|---|
VideoGenerationError | Eșec semnalat de API: prompt refuzat, sursă invalidă, serviciu supraîncărcat… (code, message) | Citiți codul: corectați cererea sau reîncercați mai târziu dacă serviciul nu a fost disponibil |
TimeoutError | Timpul de așteptare lato sensu (client-side) a fost depășit | Măriți timeout sau reduceți durata |
RuntimeError | Cererea amânată a expirat sau s-a finalizat fără rezultat | Reporniți generarea |
grpc.RpcError | Eroare de transport SDK, inclusiv limite de rată (cod RESOURCE_EXHAUSTED) și probleme cu cheia | Spațiați cererile cu backoff sau verificați cheia |
SDK-ul folosește gRPC: o limită de rată depășită nu apare aici ca un cod HTTP 429, ci ca un grpc.RpcError cu codul RESOURCE_EXHAUSTED.
Editare și extindere, aceeași ușurință
Editarea nu are o metodă dedicată: este generate cu un video sursă, transmis ca video_url (video de până la 8,7 secunde, aceeași durată de ieșire, maxim 720p).
video = client.video.generate(
prompt="Transformă scena în stil anime japonez",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Extinderea prelungește o secvență de 2 până la 15 secunde cu un segment de 2 până la 10 secunde și returnează videoclipul complet:
video = client.video.extend(
prompt="Continuă scena cu o mișcare de panoramare spre dreapta",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Rețineți diferența față de API-ul REST: SDK-ul primește videoclipul ca parametru video_url, în timp ce corpul JSON se așteaptă la un obiect video cu proprietatea sa url.
Nu lăsați niciodată un videoclip în cloud
SDK-ul nu schimbă nimic în ceea ce privește natura temporară a URL-urilor rezultate. Dacă codul dumneavoastră afișează doar video.url, ați plătit pentru o generare care va dispărea în curând. Cea mai bună practică este înlănțuirea generării și descărcării în aceeași funcție, astfel încât devine imposibil să uitați acest pas.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Generează un videoclip și îl salvează local (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Descărcare imediată
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 salvat: {output_file}")
return output_file
Pentru stocare fără tranzit prin serverul dumneavoastră, parametrul storage_options al generării depune videoclipul în API-ul xAI Files, cu o expirare la alegerea dumneavoastră.
Generați mai multe videoclipuri simultan
Cu clientul asincron, fiecare apel este o corutină, iar asyncio.gather lansează întregul lot în paralel. Opțiunea return_exceptions=True este decisivă aici: fără ea, o singură cerere refuzată ar eșua întregul lot și ați pierde rezultatele deja obținute.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Generează mai multe videoclipuri în paralel."""
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"Cererea {i} a eșuat: {res}")
else:
print(f"Cererea {i} completată: {res.url}")
return results
Două garduri de siguranță încadrează această paralelizare. Trimiterile consumă limita dumneavoastră de rată, calculată în cereri pe secundă conform nivelului echipei dumneavoastră (10 la nivelul de intrare pentru modelele video): pentru un lot mare, limitați concurența cu un asyncio.Semaphore. Amintiți-vă, de asemenea, ce face și ce nu face paralelismul: nu accelerează nicio generare individuală, ci doar reduce timpul total al lotului.
Ar trebui să renunțați la interogarea manuală?
Nu sistematic. Următoarea comparație arată unde fiecare abordare preia conducerea.
| Aspect | Interogare manuală | SDK |
|---|---|---|
| Complexitate | Ridicată | Scăzută |
| Gestionarea erorilor | De implementat | Integrată |
| Timeout | De implementat | 10 min implicit, configurabil |
| Interval de interogare | De ales | 1 s implicit, configurabil |
| Flexibilitate | Totală | Standard (sau start și get) |
| Dependență | Niciuna | SDK xAI |
Interogarea manuală își păstrează relevanța în două situații: când aveți nevoie de un control fin, de exemplu pentru a relata progresul către o interfață în timp real sau pentru a o integra într-un sistem de coadă existent, și când contextul de implementare interzice adăugarea unei dependențe suplimentare.
Puncte cheie
client.video.generatetrimite, așteaptă și returnează videoclipul (url,duration,model); timeout de 10 minute și verificare la fiecare secundă implicit- Editarea folosește
generatecuvideo_url, extinderea foloseșteclient.video.extend VideoGenerationError(dinxai_sdk.video),TimeoutErrorșiRuntimeErrordisting eșecurile; limitele de rată ajung cagrpc.RpcError- Descărcați întotdeauna videoclipul imediat după generare (URL-uri temporare)
- Clientul asincron și
asyncio.gatherparalelizează un lot, în limita ratei nivelului dumneavoastră