Salt la conținutul principal
Română— Alege o limbă
Meniu

SDK xAI și interogarea automată

Lecția 11 din 12 Actualizată 2 noiembrie 2026 Intermediar
Pe această pagină
  1. Simplificați interogarea cu SDK-ul
  2. O singură apelare în loc de o buclă
  3. Gestionați erorile la sursă
  4. Editare și extindere, aceeași ușurință
  5. Nu lăsați niciodată un videoclip în cloud
  6. Generați mai multe videoclipuri simultan
  7. Ar trebui să renunțați la interogarea manuală?
  8. Puncte cheie

Actualizat pe 2 noiembrie 2026 pe baza documentației video xAI și a codului xai-sdk 1.21.0: metodele se numesc client.video.generate și client.video.extend (editarea folosește generate cu video_url), rezultatul expune url, întârzierea se setează printr-un timedelta, iar intervalul implicit de interogare este de o secundă. await necesită clientul asincron AsyncClient, iar excepția VideoGenerationError se importă din xai_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.

EroareCauzăAcțiune recomandată
VideoGenerationErrorEș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
TimeoutErrorTimpul de așteptare lato sensu (client-side) a fost depășitMăriți timeout sau reduceți durata
RuntimeErrorCererea amânată a expirat sau s-a finalizat fără rezultatReporniți generarea
grpc.RpcErrorEroare de transport SDK, inclusiv limite de rată (cod RESOURCE_EXHAUSTED) și probleme cu cheiaSpaț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.

AspectInterogare manualăSDK
ComplexitateRidicatăScăzută
Gestionarea erorilorDe implementatIntegrată
TimeoutDe implementat10 min implicit, configurabil
Interval de interogareDe ales1 s implicit, configurabil
FlexibilitateTotalăStandard (sau start și get)
DependențăNiciunaSDK 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.generate trimite, așteaptă și returnează videoclipul (url, duration, model); timeout de 10 minute și verificare la fiecare secundă implicit
  • Editarea folosește generate cu video_url, extinderea folosește client.video.extend
  • VideoGenerationError (din xai_sdk.video), TimeoutError și RuntimeError disting eșecurile; limitele de rată ajung ca grpc.RpcError
  • Descărcați întotdeauna videoclipul imediat după generare (URL-uri temporare)
  • Clientul asincron și asyncio.gather paralelizează un lot, în limita ratei nivelului dumneavoastră