Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

xAI SDK ja automaattinen kysely

Oppitunti 11 / 12 Päivitetty 2. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Yksinkertaista kyselyä SDK:n avulla
  2. Yksi kutsu silmukan sijaan
  3. Käsittele virheet lähteellä
  4. Muokkaus ja jatkaminen, sama helppous
  5. Älä koskaan jätä videota pilveen
  6. Generoi useita videoita kerralla
  7. Kannattaako manuaalisesta kyselystä luopua?
  8. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 xAI:n videodokumentaation ja xai-sdk 1.21.0 -koodin perusteella: metodit ovat client.video.generate ja client.video.extend (muokkaus käyttää generate-metodia parametrilla video_url), tulos paljastaa url-osoitteen, viive asetetaan timedelta-objektilla ja oletuskyselyväli on yksi sekunti. await vaatii asynkronisen asiakkaan AsyncClient, ja poikkeusluokka VideoGenerationError tuodaan moduulista xai_sdk.video. Vanha versio käytti metodeja ja poikkeusmoduulia, joita ei ole olemassa. Lähteet: Videogenerointi · Videon muokkaus · Videon jatkaminen · xai-sdk-python.

Yksinkertaista kyselyä SDK:n avulla

Edellisessä oppitunnissa kirjoitit kyselysilmukan käsin. Se on hyödyllinen harjoitus generointielinkaaren ymmärtämiseksi, mutta se tarkoittaa myös kolmeakymmentä koodiriviä, jotka on ylläpidettävä jokaisessa projektissa omine aikakatkaisukäsittelyineen, virhetilanteineen ja tilamuunnoksineen. xAI:n virallinen Python-SDK (pip install xai-sdk) kapseloi kaiken tämän: lähetät pyynnön, ja se hoitaa odotuksen puolestasi.

Yksi kutsu silmukan sijaan

Metodi client.video.generate yhdistää lähetyksen, seurannan ja haun. Se palauttaa kontrollin vasta, kun video on valmis, tai nostaa poikkeuksen, jos jotain meni pieleen.

import os

import xai_sdk

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

# Tekstistä videoon -generointi automaattisella kyselyllä
video = client.video.generate(
    prompt="Auringonnousu Alpeilla, nopeutettu aikaelokuva",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Kesto: {video.duration} s, malli: {video.model}")

Näiden muutaman rivin takana SDK tekee täsmälleen sen, mitä koodasit aiemmin: se lähettää pyynnön, kysyy tilaa sekunnin välein oletuksena ja palauttaa sitten tuloksen tai nostaa poikkeuksen lopputuloksesta riippuen.

Yksi asetus ansaitsee huomiosi heti käyttöönoton yhteydessä: oletuksena SDK odottaa enintään 10 minuuttia ennen luovuttamista. Se sopii hyvin yölliseen tuotantoskriptiin, mutta on aivan liian pitkä verkkopyyntöä varten, jossa käyttäjä odottaa vastausta. Parametrit timeout ja interval, jotka ovat molemmat timedelta-objekteja, asettavat rajan ja rytmin:

from datetime import timedelta

video = client.video.generate(
    prompt="Kuvailemasi sisältö",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # Enintään 5 minuuttia
    interval=timedelta(seconds=5),  # Tarkistus joka 5. sekunti
)

Jos haluat pitää kontrollin odotuksesta – esimerkiksi välittääksesi edistymistietoja – client.video.start lähettää pyynnön ja palauttaa sen request_id:n, jota client.video.get voi sitten kysellä.

Käsittele virheet lähteellä

SDK erottaa epäonnistumiset toisistaan, mikä säästää sinua merkkijonojen analysoinnilta tilanteen selvittämiseksi:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Kuvailemasi sisältö",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video valmis: {video.url}")
except VideoGenerationError as e:
    print(f"Generointi epäonnistui [{e.code}]: {e.message}")
except TimeoutError:
    print("Aikakatkaisu ylitetty: kasvata aikakatkaisua tai yksinkertaista pyyntöä")

Jokainen virhe vaatii erilaisen reaktion, ja niiden sekoittaminen johtaa turhiin uudelleenyrityssilmukoihin tai pahimmillaan laskutettuihin generointeihin, jotka eivät tuota mitään.

VirheSyySuositeltu toiminta
VideoGenerationErrorAPI:n ilmoittama epäonnistuminen: kehote hylätty, virheellinen lähde, palvelu ylikuormitettu… (code, message)Lue koodi: korjaa pyyntö tai yritä myöhemmin uudelleen, jos palvelu ei ollut saatavilla
TimeoutErrorAsiakaspuolen odotusaika ylitettyKasvata timeout-arvoa tai lyhennä kestoa
RuntimeErrorViivästetty pyyntö vanhentunut tai valmistunut ilman tulostaKäynnistä generointi uudelleen
grpc.RpcErrorSDK:n kuljetusvirhe, mukaan lukien nopeusrajoitukset (koodi RESOURCE_EXHAUSTED) ja avainongelmatVähennä pyyntöjen tiheyttä eksponentiaalisella viiveellä tai tarkista avain

SDK käyttää gRPC:tä: ylitetty nopeusrajoitus ei näy tässä HTTP 429 -koodina, vaan grpc.RpcError-poikkeuksena, jonka koodi on RESOURCE_EXHAUSTED.

Muokkaus ja jatkaminen, sama helppous

Muokkaamiselle ei ole omaa metodia: se on generate lähdevideon kanssa, joka välitetään parametrina video_url (video enintään 8,7 sekuntia, sama kesto tulosteessa, enintään 720p).

video = client.video.generate(
    prompt="Muuta kohtaus japanilaiseksi anime-tyyliksi",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Jatkaminen pidentää 2–15 sekunnin jaksoa 2–10 sekunnin segmentillä ja palauttaa koko videon:

video = client.video.extend(
    prompt="Jatka kohtausta panoroimalla oikealle",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Huomaa ero REST API:hun: SDK ottaa videon video_url-parametrina, kun taas JSON-runko odottaa video-objektia, jossa on url-ominaisuus.

Älä koskaan jätä videota pilveen

SDK ei muuta mitään tulososoitteiden väliaikaisessa luonteessa. Jos koodisi vain näyttää video.url:n, olet maksanut generoinnista, joka katoaa pian. Paras käytäntö on ketjuttaa generointi ja lataus samaan funktioon, jotta vaiheen unohtaminen mahdotonta.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Generoi videon ja tallentaa sen paikallisesti (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Välitön lataus
    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 tallennettu: {output_file}")
    return output_file

Tallennusta varten ilman välitystä palvelimesi kautta generoinnin parametri storage_options tallettaa videon xAI Files API:hun valitsemallasi vanhenemisajalla.

Generoi useita videoita kerralla

Asynkronisen asiakkaan kanssa jokainen kutsu on korutiini, ja asyncio.gather käynnistää koko erän rinnakkain. Vaihtoehto return_exceptions=True on ratkaiseva tässä: ilman sitä yksikin hylätty pyyntö epäonnistuttaisi koko erän, ja menettäisit jo saadut tulokset.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generoi useita videoita rinnakkain."""
    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"Pyyntö {i} epäonnistui: {res}")
        else:
            print(f"Pyyntö {i} valmistui: {res.url}")

    return results

Kaksi suojakaarta rajaavat tätä rinnakkaistamista. Lähetykset kuluttavat nopeusrajoitustasi, joka lasketaan pyyntöinä sekunnissa tiimisi tason mukaan (10 videomalleille aloitustasolla): suurille erille rajoita samanaikaisuutta asyncio.Semaphore-lukolla. Muista myös, mitä rinnakkaisuus tekee ja mitä se ei tee: se ei nopeuta yksittäistä generointia, se vain lyhentää koko erän kokonaisaikaa.

Kannattaako manuaalisesta kyselystä luopua?

Ei systemaattisesti. Seuraava vertailu osoittaa, missä kumpikin lähestymistapa on vahvimmillaan.

NäkökohtaManuaalinen kyselySDK
MonimutkaisuusKorkeaMatala
VirheenkäsittelyToteutettava itseIntegroitu
AikakatkaisuToteutettava itse10 min oletus, muokattavissa
KyselyväliValittava itse1 s oletus, muokattavissa
JoustavuusTäydellinenVakio (tai start ja get)
RiippuvuusEi yhtäänxAI SDK

Manuaalinen kysely säilyttää merkityksensä kahdessa tilanteessa: kun tarvitset hienosäätöä, esimerkiksi välittääksesi edistymistietoja reaaliaikaiseen käyttöliittymään tai integroidaksesi sen olemassa olevaan jonotusjärjestelmään, ja kun käyttöönottoympäristösi kieltää ylimääräisten riippuvuuksien lisäämisen.

Keskeiset asiat

  • client.video.generate lähettää, odottaa ja palauttaa videon (url, duration, model); 10 minuutin aikakatkaisu ja yhden sekunnin tarkistus oletuksena
  • Muokkaus käyttää generate-metodia parametrilla video_url, jatkaminen käyttää client.video.extend
  • VideoGenerationError (moduulista xai_sdk.video), TimeoutError ja RuntimeError erottavat epäonnistumiset; nopeusrajoitukset saapuvat grpc.RpcError-poikkeuksina
  • Lataa video aina välittömästi generoinnin jälkeen (väliaikaiset osoitteet)
  • Asynkroninen asiakas ja asyncio.gather rinnakkaistavat erän tiimisi tason nopeusrajoitusten puitteissa