xAI SDK ja automaattinen kysely
Tällä sivulla
Päivitetty 2. marraskuuta 2026 xAI:n videodokumentaation ja
xai-sdk1.21.0 -koodin perusteella: metodit ovatclient.video.generatejaclient.video.extend(muokkaus käyttäägenerate-metodia parametrillavideo_url), tulos paljastaaurl-osoitteen, viive asetetaantimedelta-objektilla ja oletuskyselyväli on yksi sekunti.awaitvaatii asynkronisen asiakkaanAsyncClient, ja poikkeusluokkaVideoGenerationErrortuodaan moduulistaxai_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.
| Virhe | Syy | Suositeltu toiminta |
|---|---|---|
VideoGenerationError | API: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 |
TimeoutError | Asiakaspuolen odotusaika ylitetty | Kasvata timeout-arvoa tai lyhennä kestoa |
RuntimeError | Viivästetty pyyntö vanhentunut tai valmistunut ilman tulosta | Käynnistä generointi uudelleen |
grpc.RpcError | SDK:n kuljetusvirhe, mukaan lukien nopeusrajoitukset (koodi RESOURCE_EXHAUSTED) ja avainongelmat | Vä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ökohta | Manuaalinen kysely | SDK |
|---|---|---|
| Monimutkaisuus | Korkea | Matala |
| Virheenkäsittely | Toteutettava itse | Integroitu |
| Aikakatkaisu | Toteutettava itse | 10 min oletus, muokattavissa |
| Kyselyväli | Valittava itse | 1 s oletus, muokattavissa |
| Joustavuus | Täydellinen | Vakio (tai start ja get) |
| Riippuvuus | Ei yhtään | xAI 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.generatelähettää, odottaa ja palauttaa videon (url,duration,model); 10 minuutin aikakatkaisu ja yhden sekunnin tarkistus oletuksena- Muokkaus käyttää
generate-metodia parametrillavideo_url, jatkaminen käyttääclient.video.extend VideoGenerationError(moduulistaxai_sdk.video),TimeoutErrorjaRuntimeErrorerottavat epäonnistumiset; nopeusrajoitukset saapuvatgrpc.RpcError-poikkeuksina- Lataa video aina välittömästi generoinnin jälkeen (väliaikaiset osoitteet)
- Asynkroninen asiakas ja
asyncio.gatherrinnakkaistavat erän tiimisi tason nopeusrajoitusten puitteissa