Asynkroninen työnkulku ja kysely
Tällä sivulla
Päivitetty 2. marraskuuta 2026. Perustuen xAI Video API -viitteeseen: URL-osoite löytyy kohdasta
video.url(eivideo_url), generoinnilla on vain kolme tilaa (pending,done,failed, joista viimeiseen liittyy virhekoodi), ja nopeusrajoitukset ilmaistaan pyyntöinä sekunnissa tiimitason perusteella. Lähteet: Videogenerointi · Videoiden viite · Nopeusrajoitukset.
Ymmärrä videon elinkaari
Kaikki xAI-rajapinnan video-operaatiot ovat asynkronisia, ja tämä ominaisuus muokkaa sovellusarkkitehtuuriasi enemmän kuin aluksi uskoisit. Keskustelukutsu tai kuvagenerointi palauttaa tuloksen välittömästi, mutta videogenerointi vaatii merkittävää käsittelyaikaa ja palauttaa vain vahvistuksen. Sinun tehtäväsi on toteuttaa seuranta: kysy tehtävän tilaa säännöllisin väliajoin, havaitse valmistuminen ja nouda tiedosto. Koko sykli koostuu neljästä vaiheesta.
Lähetä pyyntö
POST-generointi-, muokkaus- tai laajennuspäätepisteeseen. Välitön vastaus request_id-tunnuksella.
Kysy tila
GET /v1/videos/{request_id} säännöllisin väliajoin. progress-kenttä 0–100.
Nouda tulos
Kun tila on done (progress = 100), video-URL on saatavilla.
Lataa välittömästi
Video-URL on väliaikainen. Lataa se niin pian kuin mahdollista.
Tarkista generoinnin tila
Seuranta sisältää yksinkertaisen GET-pyynnön tilapäätepisteeseen käyttäen lähetyksen yhteydessä saatua tunnusta.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Vastaus paljastaa seuraavat hyödylliset tiedot:
- status : nykyinen generointitila
- progress : kokonaisluku 0–100, joka ilmaisee edistymisen
- video.url : video-URL
video-objektin sisällä, kun tila ondone, sekä sen kesto (video.duration) - video.respect_moderation : totuusarvo, joka kertoo, noudattaako sisältö moderointikäytäntöä
- error : epäonnistumisen sattuessa koodi (
invalid_argument,permission_denied,failed_precondition,service_unavailabletaiinternal_error) ja viesti - usage.cost_in_usd_ticks : pyynnön kustannus kymmenenmiljardisosina dollarista
progress-kenttä ansaitsee huomautuksen: se ei ohjaa ohjauslogiikkaasi, jonka tulee aina luottaa status-kenttään, mutta se on kultaa käyttöliittymälle. Tekstin ”62 %” näyttäminen staattisen latausanimaation sijaan muuttaa täysin useita minuutteja kestävän odotuksen kokemusta.
Kolme tilaa, kolme toimintoa
| Tila | Edistyminen | Merkitys |
|---|---|---|
pending | 0–99 | Generointi käynnissä |
done | 100 | Valmis, URL saatavilla |
failed | puuttuu | Generointi epäonnistui |
Niin kauan kuin tila on pending, generointi jatkuu: sinun tarvitsee vain kysyä tilaa säännöllisin väliajoin ja välittää progress-tieto käyttöliittymääsi. Kun tila vaihtuu arvoon done, video on valmis, ja ainoa tehtävä on lukea video.url ja ladata tiedosto välittömästi – nämä URL-osoitteet ovat väliaikaisia, eikä dokumentaatiossa määritellä niiden voimassaoloaikaa, mikä estää niiden tallentamisen tietokantaan myöhempää käyttöä varten.
Lopuksi failed-tila ilmoittaa tuotantovirheestä, ja error-kenttä kertoo, mistä virheestä on kyse. Ero on tärkeä jatkotoimien kannalta: service_unavailable (palvelu väliaikaisesti ylikuormitettu) tai internal_error oikeuttavat yrittämään uudelleen myöhemmin, kun taas invalid_argument tai permission_denied – hylätty kehote, virheellinen lähdekuva tai -video – vaativat pyynnön korjaamista ensin. Python SDK puolestaan ilmoittaa virheen kautta myös viivästyneestä pyynnöstä, jonka voimassaoloaika umpeutui ennen noutoa.
Toteuta kysely
Synkroninen versio mahtuu yhteen funktioon. Se silmukoi aikakatkaisuun saakka, poistuu ennenaikaisesti epäonnistumisen sattuessa nostamalla virhekoodin ja palauttaa URL-osoitteen heti, kun video on valmis.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Odota videogeneroinnin valmistumista."""
headers = {"Authorization": f"Bearer {api_key}"}
debut = time.time()
while time.time() - debut < timeout:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
status = resp.get("status")
progress = resp.get("progress", 0)
if status == "done":
return resp["video"]["url"]
elif status == "failed":
erreur = resp.get("error", {})
raise RuntimeError(f"Generation failed [{erreur.get('code')}] : {erreur.get('message')}")
print(f"In progress... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout after {timeout} seconds")
Palvelussa, joka käsittelee useita pyyntöjä samanaikaisesti, tämä estävä versio muodostuu pullonkaulaksi: jokainen odotus lukitsee säikeen minuuteiksi. Asynkroninen muunnos vapauttaa tapahtumasilmukan kyselyjen välillä ja mahdollistaa kymmenien generointien seuraamisen rinnakkain.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Kyselyn asynkroninen versio."""
headers = {"Authorization": f"Bearer {api_key}"}
async with httpx.AsyncClient() as client:
debut = asyncio.get_event_loop().time()
while asyncio.get_event_loop().time() - debut < timeout:
resp = await client.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
)
data = resp.json()
if data["status"] == "done":
return data["video"]["url"]
elif data["status"] == "failed":
raise RuntimeError(f"Generation failed : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Aseta kyselyväli
Välin valinta tasapainottaa vasteaikaa ja turhia pyyntöjä. Viisi sekuntia on hyvä kompromissi useimmissa tapauksissa. Pitkille generoinneille – kymmenen–viidentoista sekunnin videoille – kymmenen–viidentoista sekunnin väli kyselyjen välillä riittää ja vähentää liikennettä. Päinvastoin, interaktiivisessa sovelluksessa, jossa käyttäjä tarkkailee edistymispalkkia, on perusteltua lyhentää väli kahteen tai kolmeen sekuntiin. Alle sekunnin väleillä et kuitenkaan nopeuta mitään: generointi etenee omaa tahtiaan, ja vain kerrot pyyntöjä turhaan.
Keskeiset asiat
- Kaikki video-operaatiot ovat asynkronisia: POST lähetykseen, GET noutoon
- Kolme mahdollista tilaa: pending, done, failed (virhekoodin kera)
progress-kenttä (0–100) mahdollistaa edistymisen seuraamisen- Toteuta aikakatkaisu ja käyttötapaustasi vastaava kyselyväli
- Video-URL-osoitteet ovat väliaikaisia: lataa ne välittömästi