Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

xAI SDK és automatikus lekérdezés

11. lecke 12 közül Frissítve 2026. november 2. Középhaladó
Ezen az oldalon
  1. Egyszerűsítsd a lekérdezést az SDK-val
  2. Egyetlen hívás ciklus helyett
  3. Kezeld a hibákat a forrásnál
  4. Szerkesztés és bővítés, ugyanolyan egyszerűen
  5. Soha ne hagyd a videót a felhőben
  6. Több videó egyszerre történő generálása
  7. El kellene hagynod a kézi lekérdezést?
  8. Főbb megállapítások

Frissítve: 2026. november 2. az xAI videós dokumentációja és az xai-sdk 1.21.0 verziójú kódja alapján: a metódusok neve client.video.generate és client.video.extend (a szerkesztés a generate használata video_url paraméterrel), az eredmény tartalmazza az url attribútumot, a késleltetést egy timedelta objektummal állítod be, az alapértelmezett lekérdezési időköz pedig egy másodperc. Az await kulcsszó használatához az aszinkron kliensre (AsyncClient) van szükség, a VideoGenerationError kivételt pedig az xai_sdk.video modulból importálod. A régi verzió olyan metódusokat és kivételmodult említett, amelyek nem léteznek. Források: Videógenerálás · Videószerkesztés · Videóbővítés · xai-sdk-python.

Egyszerűsítsd a lekérdezést az SDK-val

Az előző leckében saját kézzel írtál egy lekérdezési ciklust. Ez hasznos gyakorlat a generálási életciklus megértéséhez, de minden projektben karbantartandó harminc sor kódot jelent, saját időtúllépés-kezeléssel, hibaesetekkel és állapotkonverziókkal. Az xAI hivatalos Python SDK-ja (pip install xai-sdk) mindezt kapszulázza: te elküldöd a kérést, az SDK pedig kezeli a várakozást.

Egyetlen hívás ciklus helyett

A client.video.generate metódus egyesíti a beküldést, a nyomon követést és az adatlekérést. Csak akkor adja vissza az irányítást, ha a videó elkészült, vagy kivételt dob, ha valami hiba történt.

import os

import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Szöveg-videó generálás automatikus lekérdezéssel
video = client.video.generate(
    prompt="Napfelkelte az Alpok felett, gyorsított időzített felvétel",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Időtartam: {video.duration} s, modell: {video.model}")

E néhány sor kód mögött az SDK pontosan azt csinálja, amit korábban te kódoltál: elküldi a kérést, alapértelmezetten másodpercenként lekérdezi az állapotot, majd az eredménytől függően visszaadja az eredményt vagy kivételt dob.

Egy beállításra már a telepítéskor figyelned kell: alapértelmezetten az SDK legfeljebb 10 percig vár, mielőtt feladná. Ez kényelmes egy éjszakai gyártási szkriptnél, de sokkal túl hosszú egy webes kérésnél, ahol a felhasználó a válaszra vár. A timeout és az interval paraméterek, amelyek mindketten timedelta objektumok, állítják be a határidőt és az ütemezést:

from datetime import timedelta

video = client.video.generate(
    prompt="A te leírásod",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # max. 5 perc
    interval=timedelta(seconds=5),  # ellenőrzés 5 másodpercenként
)

Ha meg szeretnéd tartani a kontrollt a várakozás felett – például a haladás továbbításához –, a client.video.start beküldi a kérést és visszaadja a request_id azonosítót, amelyet aztán a client.video.get lekérdez.

Kezeld a hibákat a forrásnál

Az SDK megkülönbözteti a hibákat, így megspórolod neked a szövegek elemzését annak kiderítésére, mi történt:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="A te leírásod",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Videó kész: {video.url}")
except VideoGenerationError as e:
    print(f"Generálás sikertelen [{e.code}]: {e.message}")
except TimeoutError:
    print("Időtúllépés: növeld a timeout értéket vagy egyszerűsítsd a kérést")

Minden hiba eltérő reakciót igényel, és ezek összekeverése felesleges újrapróbálkozási ciklusokhoz vezet, vagy ami rosszabb, számlázott generálásokhoz, amelyek semmit sem eredményeznek.

HibaOkJavasolt intézkedés
VideoGenerationErrorAz API által jelzett hiba: elutasított prompt, érvénytelen forrás, túlterhelt szolgáltatás… (code, message)Olvasd el a kódot: javítsd a kérést, vagy próbáld újra később, ha a szolgáltatás nem volt elérhető
TimeoutErrorA kliens oldali várakozási idő túllépéseNöveld a timeout értékét vagy csökkentsd az időtartamot
RuntimeErrorA késleltetett kérés lejárt, vagy eredmény nélkül fejeződött beIndítsd újra a generálást
grpc.RpcErrorAz SDK transzport hibája, beleértve a sebességkorlátokat (RESOURCE_EXHAUSTED kód) és kulcsproblémákatTarts szünetet a kérések között backoff stratégiával, vagy ellenőrizd a kulcsot

Az SDK gRPC-t használ: a túllépett sebességkorlát itt nem HTTP 429-es kódként jelenik meg, hanem grpc.RpcError kivételként RESOURCE_EXHAUSTED kóddal.

Szerkesztés és bővítés, ugyanolyan egyszerűen

A szerkesztésnek nincs dedikált metódusa: ez a generate használata egy forrásvideóval, amelyet video_url paraméterként adsz meg (legfeljebb 8,7 másodperces videó, ugyanolyan időtartamú kimenet, max. 720p felbontás).

video = client.video.generate(
    prompt="Alakítsd át a jelenetet japán anime stílusra",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

A bővítés meghosszabbít egy 2 és 15 másodperc közötti szekvenciát egy 2 és 10 másodperc közötti szakasszal, és visszaadja a teljes videót:

video = client.video.extend(
    prompt="Folytasd a jelenetet egy jobbra panorámázással",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Figyeld meg a különbséget a REST API-hoz képest: az SDK a videót video_url paraméterként fogadja, míg a JSON törzs egy video objektumot vár url tulajdonsággal.

Soha ne hagyd a videót a felhőben

Az SDK semmit sem változtat az eredmény URL-ek ideiglenes jellegén. Ha a kódod csak kiírja a video.url értékét, akkor egy olyan generálásért fizettél, amely hamarosan eltűnik. A legjobb gyakorlat a generálás és a letöltés láncolása ugyanabban a függvényben, így lehetetlenné válik e lépés elfelejtése.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Generál egy videót és helyben elmenti (kliens: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Azonnali letöltés
    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"Videó elmentve: {output_file}")
    return output_file

Ha tárhelyre szeretnéd menteni a videót anélkül, hogy az áthaladna a szervereden, a generálás storage_options paramétere az xAI Files API-ba helyezi a videót, az általad választott lejárati idővel.

Több videó egyszerre történő generálása

Az aszinkron klienssel minden hívás egy korutin, és az asyncio.gather egyszerre indít el egy teljes köteget. A return_exceptions=True opció itt döntő fontosságú: nélküle egyetlen elutasított kérés meghiúsítaná az egész köteget, és elveszítenéd a már megszerzett eredményeket.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Több videó párhuzamos generálása."""
    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"{i}. kérés sikertelen: {res}")
        else:
            print(f"{i}. kérés kész: {res.url}")

    return results

Két védőkorlát keretezi ezt a párhuzamosítást. A beküldések消耗ják a sebességkorlátozásodat (rate limit), amelyet a csapatod szintje szerint másodpercenkénti kérésekben mérnek (a videómodelleknél a belépő szinten 10): nagy köteg esetén korlátozd a konkurenciát egy asyncio.Semaphore segítségével. Emlékezz arra is, mit csinál és mit nem csinál a párhuzamosítás: nem gyorsítja fel az egyes generálásokat, csak a teljes köteg idejét csökkenti.

El kellene hagynod a kézi lekérdezést?

Nem feltétlenül. Az alábbi összehasonlítás bemutatja, melyik megközelítés mikor előnyös.

SzempontKézi lekérdezésSDK
KomplexitásMagasAlacsony
HibakezelésImplementálandóBeépített
Időtúllépés (Timeout)Implementálandó10 perc alapértelmezetten, konfigurálható
Lekérdezési időközVálasztandó1 mp alapértelmezetten, konfigurálható
RugalmasságTeljesStandard (vagy start és get)
FüggőségNincsxAI SDK

A kézi lekérdezés két helyzetben őrzi meg a relevanciáját: amikor finomhangolt kontrollra van szükséged – például a haladás valós idejű interfészre történő továbbításához vagy egy meglévő sorkezelő rendszerbe való integráláshoz –, és amikor a telepítési kontextusod megtiltja további függőségek hozzáadását.

Főbb megállapítások

  • A client.video.generate beküldi a kérést, vár, majd visszaadja a videót (url, duration, model); alapértelmezetten 10 perces időtúllépés és másodpercenkénti ellenőrzés
  • A szerkesztés a generate használatát jelenti video_url paraméterrel, a bővítéshez a client.video.extend szolgál
  • A VideoGenerationError (az xai_sdk.video modulból), a TimeoutError és a RuntimeError megkülönböztetik a hibákat; a sebességkorlátok grpc.RpcErrorként érkeznek
  • Mindig töltsd le a videót azonnal a generálás után (ideiglenes URL-ek)
  • Az aszinkron kliens és az asyncio.gather párhuzamosítja a kötegeket a szinted sebességkorlátain belül