Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

xAI SDK in samodejno anketiranje

Lekcija 11 od 12 Posodobljeno 2. november 2026 Srednje napredni
Na tej strani
  1. Poenostavi anketiranje s SDK-jem
  2. En klic namesto zanke
  3. Obravnava napak pri viru
  4. Urejanje in razširjanje z enako lahkoto
  5. Nikoli ne puščaj videoposnetka v oblaku
  6. Sočasno ustvarjanje več videoposnetkov
  7. Naj opustiš ročno anketiranje?
  8. Ključne ugotovitve

Posodobljeno 2. novembra 2026 na podlagi dokumentacije za videoposnetke xAI in kode xai-sdk 1.21.0: metodi se imenujeta client.video.generate in client.video.extend (urejanje uporablja generate s parametrom video_url), rezultat razkriva url, zamik se nastavi prek timedelta, privzeti interval anketiranja pa je ena sekunda. await zahteva asinhroni odjemalec AsyncClient, izjema VideoGenerationError pa se uvozi iz xai_sdk.video. Stara različica je klicala metode in modul izjem, ki ne obstajata. Viri: Ustvarjanje videoposnetkov · Urejanje videoposnetkov · Razširjanje videoposnetkov · xai-sdk-python.

Poenostavi anketiranje s SDK-jem

V prejšnji lekciji si moral ročno napisati zanko za anketiranje. To je koristna vaja za razumevanje življenjskega cikla ustvarjanja, a hkrati pomeni trideset vrstic kode, ki jih moraš vzdrževati v vsakem projektu, z lastnim upravljanjem časovnih omejitev, primeri napak in pretvorbami stanj. Uradni Python SDK za xAI (pip install xai-sdk) vse to encapsulira: zahtevo oddaš, on pa poskrbi za čakanje.

En klic namesto zanke

Metoda client.video.generate združuje oddajo, sledenje in pridobivanje. Nadzor vrne šele, ko je videoposnetek pripravljen, ali pa sproži izjemo, če je šlo kaj narobe.

import os

import xai_sdk

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

# Ustvarjanje besedilo-videoposnetek s samodejnim anketiranjem
video = client.video.generate(
    prompt="Sončni vzhod nad Alpami, pospešeni časovni zamik",
    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}")

Za temi nekaj vrsticami SDK stori točno tisto, kar si prej kodiral sam: odda zahtevo, vsako sekundo (privzeto) preveri stanje in nato vrne rezultat ali sproži izjemo, odvisno od izida.

Ena nastavitev si zasluži tvojo pozornost takoj ob uvajanju: privzeto SDK čaka do 10 minut, preden odneha. To je udobno za nočno produkcijsko skripto, a predolgo za spletni zahtevek, kjer uporabnik čaka na odgovor. Parametra timeout in interval, oba objekta timedelta, določata časovno omejitev in ritem:

from datetime import timedelta

video = client.video.generate(
    prompt="Tvoj opis",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # največ 5 minut
    interval=timedelta(seconds=5),  # en preverjanje vsakih 5 sekund
)

Če želiš obdržati nadzor nad čakanjem – na primer za posredovanje napredka – client.video.start odda zahtevo in vrne njen request_id, ki ga nato poizveduje client.video.get.

Obravnava napak pri viru

SDK razlikuje med napakami, kar te reši analiziranja nizov, da bi ugotovil, kaj se je zgodilo:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Tvoj opis",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Videoposnetek pripravljen: {video.url}")
except VideoGenerationError as e:
    print(f"Ustvarjanje ni uspelo [{e.code}]: {e.message}")
except TimeoutError:
    print("Časovna omejitev presežena: povečaj timeout ali poenostavi zahtevo")

Vsaka napaka zahteva drugačen odziv; njihovo mešanje vodi v neuporabne zanke za ponovne poskuse ali, kar je še huje, v zaračunana ustvarjanja, ki ne obrodijo sadov.

NapakaVzrokPriporočeno dejanje
VideoGenerationErrorNapaka, ki jo signalizira API: zavrnjen poziv, neveljaven vir, preobremenjena storitev … (code, message)Preberi kodo: popravi zahtevo ali poskusi znova kasneje, če storitev ni bila na voljo
TimeoutErrorNa strani odjemalca je potekel čas čakanjaPovečaj timeout ali skrajšaj trajanje
RuntimeErrorOdložena zahteva je potekla ali zaključena brez rezultataPonovno zaženi ustvarjanje
grpc.RpcErrorNapaka prenosa v SDK, vključno z omejitvami hitrosti (koda RESOURCE_EXHAUSTED) in težavami s ključemRazporedi zahteve z zamikom (backoff) ali preveri ključ

SDK uporablja gRPC: presežena omejitev hitrosti se tu ne pojavi kot koda HTTP 429, temveč kot grpc.RpcError s kodo RESOURCE_EXHAUSTED.

Urejanje in razširjanje z enako lahkoto

Urejanje nima posebne metode: gre za generate z izvornim videoposnetkom, podanim kot video_url (videoposnetek do 8,7 sekunde, izhod istega trajanja, največ 720p).

video = client.video.generate(
    prompt="Preoblikuj prizor v stil japonske anime",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Razširjanje podaljša zaporedje od 2 do 15 sekund za segment od 2 do 10 sekund in vrne celoten videoposnetek:

video = client.video.extend(
    prompt="Nadaljuj prizor s premikom kamere v desno",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Opazi razliko glede na REST API: SDK sprejme videoposnetek kot parameter video_url, medtem ko telo JSON pričakuje objekt video z lastnostjo url.

Nikoli ne puščaj videoposnetka v oblaku

SDK ne spremeni ničesar glede začasne narave URL-jev rezultatov. Če tvoja koda le prikaže video.url, si plačal ustvarjanje, ki bo kmalu izginilo. Najboljša praksa je povezati ustvarjanje in prenos v isto funkcijo, tako da postane nemogoče pozabiti ta korak.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Ustvari videoposnetek in ga shrani lokalno (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Takojšen prenos
    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"Videoposnetek shranjen: {output_file}")
    return output_file

Za shranjevanje brez prenosa skozi tvoj strežnik parameter storage_options pri ustvarjanju odloži videoposnetek v xAI Files API z iztekom po tvoji izbiri.

Sočasno ustvarjanje več videoposnetkov

Z asinhronim odjemalcem je vsak klic korutina, asyncio.gather pa sproži celoten paket vzporedno. Tu je odločilna možnost return_exceptions=True: brez nje bi ena sama zavrnjena zahteva spodletela celotnemu paketu in izgubil bi že pridobljene rezultate.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Vzporedno ustvari več videoposnetkov."""
    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"Zahteva {i} ni uspela: {res}")
        else:
            print(f"Zahteva {i} zaključena: {res.url}")

    return results

Dva varnostna mehanizma okvirjata to vzporednost. Oddaje porabijo tvojo omejitev hitrosti, ki se šteje v zahtevah na sekundo glede na raven tvoje ekipe (10 na vstopni ravni za video modele): za velik paket omeji sočasnost z asyncio.Semaphore. Spomni se tudi, kaj vzporednost počne in česa ne: ne pospeši posameznega ustvarjanja, le skrajša skupni čas paketa.

Naj opustiš ročno anketiranje?

Ne nujno. Naslednja primerjava kaže, kje vsak pristop prevlada.

VidikRočno anketiranjeSDK
ZahtevnostVisokaNizka
Obravnava napakZa implementacijoIntegrirana
Časovna omejitevZa implementacijoPrivzeto 10 min, nastavljivo
Interval anketiranjaIzbiraPrivzeto 1 s, nastavljivo
FleksibilnostPopolnaStandardna (ali start in get)
OdvisnostNobenaxAI SDK

Ročno anketiranje ohranja smisel v dveh situacijah: ko potrebuješ natančen nadzor, na primer za posredovanje napredka v vmesnik v realnem času ali za integracijo v obstoječi sistem čakalnih vrst, in ko tvoj kontekst uvajanja prepoveduje dodajanje dodatne odvisnosti.

Ključne ugotovitve

  • client.video.generate odda, počaka in vrne videoposnetek (url, duration, model); privzeta časovna omejitev je 10 minut, preverjanje vsako sekundo
  • Urejanje uporablja generate z video_url, razširjanje pa client.video.extend
  • VideoGenerationError (iz xai_sdk.video), TimeoutError in RuntimeError razlikujejo napake; omejitve hitrosti prispejo kot grpc.RpcError
  • Videoposnetek vedno takoj prenesi po ustvarjanju (začasni URL-ji)
  • Asinhroni odjemalec in asyncio.gather vzporedita paket znotraj omejitve hitrosti tvoje ravni