Lähe põhisisu juurde
Eesti— Vali keel
Menüü

xAI SDK ja automaatne päringute tegemine

Õppetund 11 / 12 Värskendatud 2. november 2026 Kesktase
Sellel lehel
  1. Lihtsusta päringute tegemist SDK-ga
  2. Üks väljakutse tsükli asemel
  3. Käitle vead allikal
  4. Redigeerimine ja pikendamine sama lihtsusega
  5. Ära jäta videot kunagi pilve
  6. Genereeri mitu videot korraga
  7. Kas peaksid käsitsi päringute tegemisest loobuma?
  8. Peamised punktid

Uuendatud 2. novembril 2026 vastavalt xAI video dokumentatsioonile ja xai-sdk 1.21.0 koodile: meetodid on client.video.generate ja client.video.extend (redigeerimine kasutab generate koos video_url-ga), tulemus avaldab url, viivise määrab timedelta ja vaikimisi päringute vaheline intervall on üks sekund. await eeldab asünkroonset klienti AsyncClient ja erind VideoGenerationError imporditakse moodulist xai_sdk.video. Vana versioon kasutas meetodeid ja erindimooduleid, mida tegelikult ei eksisteeri. Allikad: Video Generation · Video Editing · Video Extension · xai-sdk-python.

Lihtsusta päringute tegemist SDK-ga

Eelmises õppetükis pidid kirjutama päringutsükli käsitsi. See on kasulik harjutus genereerimise elutsükli mõistmiseks, kuid samas tähendab see iga projekti jaoks hooldatavat kolmekümne realist koodi koos oma ajaülemiku halduse, tõrkejuhtumite ja olekute teisendustega. xAI ametlik Pythoni SDK (pip install xai-sdk) kapseldab kogu selle: saadad päringu ja see haldab ootamist sinu eest.

Üks väljakutse tsükli asemel

Meetod client.video.generate ühendab päringu esitamise, jälgimise ja tulemuse hankimise. See annab kontrolli tagasi alles siis, kui video on valmis, või viskab erindi, kui midagi läks valesti.

import os

import xai_sdk

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

# Tekstist videoks genereerimine automaatse päringutega
video = client.video.generate(
    prompt="Päikesetõus Alpides, kiirendatud ajakaader",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Kestus: {video.duration} s, mudel: {video.model}")

Nende paari rea taga teeb SDK täpselt seda, mida sa varem ise kodeerisid: saadab päringu, kontrollib olekut vaikimisi iga sekundi tagant ja tagastab tulemuse või viskab erindi sõltuvalt tulemusest.

Üks seadistus väärib tähelepanu kohe kasutuselevõtul: vaikimisi ootab SDK kuni 10 minutit, enne kui loobub. See sobib öiseks tootmisskriptiks, kuid on veebipäringu jaoks, kus kasutaja ootab vastust, palju liiga pikk. Parameetrid timeout ja interval, mõlemad timedelta objektid, määravad piirangu ja rütmi:

from datetime import timedelta

video = client.video.generate(
    prompt="Sinu kirjeldus",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # maksimaalselt 5 minutit
    interval=timedelta(seconds=5),  # üks kontroll iga 5 sekundi järel
)

Kui soovid ooteaja üle kontrolli säilitada – näiteks edenemise edastamiseks –, siis client.video.start saadab päringu ja tagastab selle request_id, mida client.video.get seejärel päringuga kontrollib.

Käitle vead allikal

SDK eristab tõrkeid, säästes sind stringide analüüsimisest, et aru saada, mis juhtus:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Sinu kirjeldus",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video valmis: {video.url}")
except VideoGenerationError as e:
    print(f"Genereerimine ebaõnnestus [{e.code}]: {e.message}")
except TimeoutError:
    print("Ajaülemik ületatud: suurenda aegaülemikut või lihtsusta päringut")

Iga viga nõuab erinevat reaktsiooni ja nende segiajamine viib kasutute korduskatsete tsükliteni või, mis veel hullem, arvestatud genereerimisteni, mis ei too mingit tulemust.

VigaPõhjusSoovitatav tegevus
VideoGenerationErrorAPI poolt signaliseeritud tõrge: vihje tagasilükkamine, vigane allikas, teenuse ülekoormus… (code, message)Loe koodi: paranda päringut või proovi hiljem uuesti, kui teenus oli kättesaamatu
TimeoutErrorKliendi poolne ooteaeg ületatudSuurenda timeout väärtust või vähenda kestust
RuntimeErrorEdasilükatud päring aegus või lõpetati ilma tulemusetaTaaskäivita genereerimine
grpc.RpcErrorSDK transpordiviga, sh kiirusepiirangud (kood RESOURCE_EXHAUSTED) ja võtmeprobleemidHajuta päringuid tagasilöögiga või kontrolli võtit

SDK kasutab gRPC-i: ületatud kiirusepiirang ei ilmu siin HTTP 429 koodina, vaid kui grpc.RpcError koodiga RESOURCE_EXHAUSTED.

Redigeerimine ja pikendamine sama lihtsusega

Redigeerimisel puudub eraldi meetod: see on generate koos lähtevideoga, mis antakse parameetrina video_url (video kuni 8,7 sekundit, sama pikkusega väljund, maksimaalselt 720p).

video = client.video.generate(
    prompt="Teisenda stseen Jaapani anime stiili",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Pikendamine pikendab 2–15 sekundi pikkust järjestust 2–10 sekundi lõiguga ja tagastab kogu video:

video = client.video.extend(
    prompt="Jätka stseeni paremale panoraamimisega",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Pane tähele erinevust REST API-ga: SDK võtab video vastu parameetrina video_url, samas kui JSON-i keha eeldab objekti video koos selle omadusega url.

Ära jäta videot kunagi pilve

SDK ei muuda midagi tulemuse URL-ide ajutises olemuses. Kui su kood lihtsalt kuvab video.url, siis maksid genereerimise eest, mis varsti kaob. Parim tava on aheldada genereerimine ja allalaadimine samas funktsioonis, nii et selle sammu unustamine muutub võimatuks.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Genereerib video ja salvestab selle lokaalselt (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Kohene allalaadimine
    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 salvestatud: {output_file}")
    return output_file

Salvestamiseks ilma serveri kaudu edastamiseta deponeerib genereerimise parameeter storage_options video xAI Files API-sse sinu valitud aegumistähtajaga.

Genereeri mitu videot korraga

Asünkroonse kliendi puhul on iga väljakutse korutiin ja asyncio.gather käivitab terve partii paralleelselt. Siin on otsustava tähtsusega valik return_exceptions=True: ilma selleta nurjuks üksik tagasilükatud päringu tõttu kogu partii ja kaotaksid juba saadud tulemused.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Genereerib mitu videot paralleelselt."""
    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"Päring {i} ebaõnnestus: {res}")
        else:
            print(f"Päring {i} lõpetatud: {res.url}")

    return results

Seda paralleelsust raamivad kaks kaitsepiiret. Päringute esitamine tarbib sinu kiirusepiirangut, mida loendatakse päringutes sekundis vastavalt sinu meeskonna tasemele (videomudelite puhul on algtasemel 10): suure partii puhul piira samaaegsust asyncio.Semaphore-iga. Pea meeles ka seda, mida paralleelsus teeb ja mida mitte: see ei kiirenda ühtegi üksikut genereerimist, vaid vähendab ainult kogu partii koguaega.

Kas peaksid käsitsi päringute tegemisest loobuma?

Mitte süstemaatiliselt. Järgnev võrdlus näitab, kus kumb lähenemine juhtpositsiooni haarab.

AspektKäsitsi päringudSDK
KomplekssusKõrgeMadal
Vigade käitlemineTuleb ise realiseeridaIntegreeritud
AjaülemikTuleb ise realiseeridaVaikimisi 10 min, konfigureeritav
Päringute intervallTuleb validaVaikimisi 1 s, konfigureeritav
PaindlikkusTäielikStandardne (või start ja get)
SõltuvusPuudubxAI SDK

Käsitsi päringud säilitavad oma asjakohasuse kahes olukorras: kui vajad peent kontrolli, näiteks edenemise edastamiseks reaalajas liidesesse või integreerimiseks olemasolevasse järjekorrasüsteemi, ja kui sinu kasutuselevõtu kontekst keelab täiendava sõltuvuse lisamise.

Peamised punktid

  • client.video.generate esitab päringu, ootab ja tagastab video (url, duration, model); vaikimisi 10-minutiline aegaülemik ja ühesekundiline kontroll
  • Redigeerimine kasutab generate koos video_url-ga, pikendamine kasutab client.video.extend
  • VideoGenerationError (moodulist xai_sdk.video), TimeoutError ja RuntimeError eristavad tõrkeid; kiirusepiirangud saabuvad kui grpc.RpcError
  • Laadi video alati kohe pärast genereerimist alla (ajutised URL-id)
  • Asünkroonne klient ja asyncio.gather paralleelivad partiid, jäädes sinu taseme kiirusepiirangu piiresse