Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

xAI SDK ir automatinis apklausimas

Paskaita 11 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Vidutinis lygis
Šiame puslapyje
  1. Supaprastinkite apklausą naudodami SDK
  2. Vienas kvietimas vietoj ciklo
  3. Tvarkykite klaidas ties šaltiniu
  4. Redagavimas ir pratęsimas – tas pats paprastumas
  5. Niekada nepalikite vaizdo įrašo debesyje
  6. Generuokite kelis vaizdo įrašus vienu metu
  7. Ar turėtumėte atsisakyti rankinės apklausos?
  8. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. remiantis xAI vaizdo dokumentacija ir xai-sdk 1.21.0 kodu: metodai vadinami client.video.generate ir client.video.extend (redagavimui naudojamas generate su video_url), rezultatas pateikia url, delsos laikas nustatomas per timedelta, o numatytasis apklausos intervalas yra viena sekundė. await reikalauja asinchroninio kliento AsyncClient, o išimtis VideoGenerationError importuojama iš xai_sdk.video. Senoji versija naudojo metodus ir išimties modulį, kurių nėra. Šaltiniai: Vaizdo generavimas · Vaizdo redagavimas · Vaizdo pratęsimas · xai-sdk-python.

Supaprastinkite apklausą naudodami SDK

Ankstesnėje pamokoje turėjote rankiniu būdu parašyti apklausos ciklą. Tai naudinga pratimas norint suprasti generavimo gyvavimo ciklą, tačiau tai taip pat trisdešimt eilučių kodo, kurias reikia prižiūrėti kiekviename projekte, kartu su savo laiko limito valdymu, klaidų atvejais ir būsenų konvertavimu. Oficialus xAI Python SDK (pip install xai-sdk) visa tai apgaubia: jūs pateikiate užklausą, o jis pasirūpina laukimu.

Vienas kvietimas vietoj ciklo

Metodas client.video.generate sujungia pateikimą, stebėjimą ir gavimą. Jis grąžina kontrolę tik tada, kai vaizdo įrašas paruoštas, arba išmeta išimtį, jei kažkas nepavyko.

import os

import xai_sdk

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

# Teksto į vaizdo įrašą generavimas su automatine apklausa
video = client.video.generate(
    prompt="Saulėtekis virš Alpių, pagreitintas laiko tarpų vaizdo įrašas",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Trukmė: {video.duration} s, modelis: {video.model}")

Už šių kelių eilučių slypi tai, kad SDK daro būtent tai, ką kodavote anksčiau: pateikia užklausą, kas sekundę (pagal nutylėjimą) tikrina būseną, o tada grąžina rezultatą arba, priklausomai nuo baigties, išmeta išimtį.

Vienas nustatymas nusipelno jūsų dėmesio jau diegimo metu: pagal nutylėjimą SDK laukia iki 10 minučių, prieš pasiduodamas. Tai patogu naktiniam gamybos scenarijui, tačiau per ilga web užklausai, kurioje vartotojas laukia atsakymo. Parametrai timeout ir interval, abu esantys timedelta objektai, nustato ribą ir ritmą:

from datetime import timedelta

video = client.video.generate(
    prompt="Jūsų aprašymas",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # daugiausia 5 minutės
    interval=timedelta(seconds=5),  # vienas patikrinimas kas 5 sekundes
)

Jei norite išlaikyti kontrolę over laukimo – pavyzdžiui, norėdami perduoti eigą – client.video.start pateikia užklausą ir grąžina jos request_id, kurį vėliau užklausia client.video.get.

Tvarkykite klaidas ties šaltiniu

SDK atskiria gedimus, taip sutaupydamas jums poreikį analizuoti tekstines eilutes norint išsiaiškinti, kas nutiko:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Jūsų aprašymas",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Vaizdo įrašas paruoštas: {video.url}")
except VideoGenerationError as e:
    print(f"Generavimas nepavyko [{e.code}]: {e.message}")
except TimeoutError:
    print("Viršytas laiko limitas: padidinkite timeout arba supaprastinkite užklausą")

Kiekviena klaida reikalauja skirtingos reakcijos, o jų painiojimas lemia nenaudingus kartojimo ciklus arba, dar blogiau, apmokestintus generavimus, kurie neduoda jokio rezultato.

KlaidaPriežastisRekomenduojamas veiksmas
VideoGenerationErrorAPI signalizuotas gedimas: promptas atmestas, netinkamas šaltinis, perkrauta tarnyba… (code, message)Perskaitykite kodą: pataisykite užklausą arba bandykite vėliau, jei tarnyba buvo nepasiekiama
TimeoutErrorViršytas kliento pusės laukimo laikasPadidinkite timeout arba sumažinkite trukmę
RuntimeErrorAtidėta užklausa baigė galioti arba užbaigta be rezultatoPaleiskite generavimą iš naujo
grpc.RpcErrorSDK transporto klaida, įskaitant dažnio ribas (kodas RESOURCE_EXHAUSTED) ir rakto problemasRetinkite užklausas taikydami „backoff“ strategiją arba patikrinkite raktą

SDK naudoja gRPC: viršyta dažnio riba čia neatrodo kaip HTTP 429 kodas, o kaip grpc.RpcError su kodu RESOURCE_EXHAUSTED.

Redagavimas ir pratęsimas – tas pats paprastumas

Redagavimas neturi atskiro metodo: tai generate su šaltinio vaizdo įrašu, perduodamu kaip video_url (vaizdo įrašas iki 8,7 sekundės, tokia pati išvesties trukmė, daugiausia 720p).

video = client.video.generate(
    prompt="Paverskite sceną japoniško animė stiliumi",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Pratęsimas prailgina 2–15 sekundžių sekunciją 2–10 sekundžių segmentu ir grąžina visą vaizdo įrašą:

video = client.video.extend(
    prompt="Tęskite sceną panoramuojant į dešinę",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Atkreipkite dėmesį į skirtumą nuo REST API: SDK priima vaizdo įrašą kaip video_url parametrą, tuo tarpu JSON kūnas tikisi video objekto su jo url savybe.

Niekada nepalikite vaizdo įrašo debesyje

SDK nieko nekeičia rezultato URL laikinumo. Jei jūsų kodas tiesiog rodo video.url, sumokėjote už generavimą, kuris netrukus dings. Geriausia praktika – grandininėje grandinėje sujungti generavimą ir atsisiuntimą toje pačioje funkcijoje, kad taptų neįmanoma pamiršti šio žingsnio.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Generuoja vaizdo įrašą ir išsaugo jį lokaliai (klientas: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Momentinis atsisiuntimas
    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"Vaizdo įrašas išsaugotas: {output_file}")
    return output_file

Saugojimui be perėjimo per jūsų serverį, generavimo parametras storage_options įkelia vaizdo įrašą į xAI Files API su jūsų pasirinktu galiojimo laiku.

Generuokite kelis vaizdo įrašus vienu metu

Naudojant asinchroninį klientą, kiekvienas kvietimas yra korutina, o asyncio.gather paleidžia visą grupę lygiagrečiai. Čia lemiamas yra return_exceptions=True pasirinkimas: be jo, viena atmesta užklausa sugadintų visą grupę ir prarastumėte jau gautus rezultatus.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generuoja kelis vaizdo įrašus lygiagrečiai."""
    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"Užklausa {i} nepavyko: {res}")
        else:
            print(f"Užklausa {i} baigta: {res.url}")

    return results

Šį lygiagretinimą rėmina dvi apsaugos priemonės. Pateikimai sunaudoja jūsų dažnio ribą, skaičiuojamą užklausomis per sekundę pagal jūsų komandos lygį (10 pradiniame lygyje vaizdo modeliams): didelėms grupėms apribokite konkurenciją naudodami asyncio.Semaphore. Taip pat prisiminkite, ką lygiagretumas daro ir ko nedaro: jis nepagreitina jokio individualaus generavimo, jis tik sumažina bendrą grupės laiką.

Ar turėtumėte atsisakyti rankinės apklausos?

Ne sistemingai. Toliau pateiktas palyginimas rodo, kur kiekvienas požiūris pirmauja.

AspektasRankinė apklausaSDK
SudėtingumasAukštasŽemas
Klaidų valdymasReikia įgyvendintiIntegruota
Laiko limitasReikia įgyvendinti10 min. pagal nutylėjimą, konfigūruojama
Apklausos intervalasReikia pasirinkti1 s pagal nutylėjimą, konfigūruojama
LankstumasVisiškasStandartinis (arba start ir get)
PriklausomybėNėraxAI SDK

Rankinė apklausa išlaiko savo aktualumą dviejose situacijose: kai jums reikia tikslios kontrolės, pavyzdžiui, norint perduoti eigą realiuoju laiku veikiančiai sąsajai arba integruoti į esamą eilių sistemą, ir kai jūsų diegimo kontekstas draudžia pridėti papildomą priklausomybę.

Svarbiausi punktai

  • client.video.generate pateikia, palaukia ir grąžina vaizdo įrašą (url, duration, model); pagal nutylėjimą 10 minučių laiko limitas ir vienos sekundės patikrinimas
  • Redagavimui naudojamas generate su video_url, pratęsimui – client.video.extend
  • VideoGenerationError (iš xai_sdk.video), TimeoutError ir RuntimeError atskiria gedimus; dažnio ribos ateina kaip grpc.RpcError
  • Visada atsisiųskite vaizdo įrašą iškart po generavimo (laikini URL)
  • Asinchroninis klientas ir asyncio.gather lygiagrečiai apdoroja grupes, laikydamiesi jūsų lygio dažnio ribos