Asynkront workflow og polling
På denne side
Opdateret 2. november 2026. Baseret på xAI Video API-referencen: URL’en findes i
video.url(ikkevideo_url), en generering har kun tre statusser (pending,done,failed, hvor den sidste ledsages af en fejlkode), og hastighedsgrænser angives i anmodninger pr. sekund baseret på team-niveauet. Kilder: Video Generation · Videos Reference · Rate limits.
Forstå videolivscyklussen
Alle videooperationer i xAI API’en er asynkrone, og denne egenskab former din applikationsarkitektur mere, end du måske umiddelbart forventer. Et chat-opkald eller en billedgenerering returnerer et resultat med det samme; videogenerering kræver derimod betydelig behandlingstid og returnerer kun en bekræftelse. Det er op til dig at implementere sporing: du skal regelmæssigt forespørge opgavens status, registrere færdiggørelse og hente filen. Den komplette cyklus består af fire trin.
Indsend anmodning
POST til endpointet for generering, redigering eller udvidelse. Øjeblikkeligt svar med et request_id.
Poll status
GET /v1/videos/{request_id} med regelmæssige intervaller. progress-feltet går fra 0 til 100.
Hent resultat
Når status er done (progress = 100), er video-URL'en tilgængelig.
Download straks
Video-URL'en er midlertidig. Download den så hurtigt som muligt.
Tjek genereringsstatus
Sporing indebærer en simpel GET-anmodning til status-endpointet ved hjælp af identifikatoren, du modtog ved indsendelse.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Svaret indeholder følgende nyttige oplysninger:
- status : den aktuelle genereringstilstand
- progress : et heltal fra 0 til 100, der angiver fremskridt
- video.url : video-URL’en, placeret inde i
video-objektet, som kun eksisterer, når status erdone, sammen med dens varighed (video.duration) - video.respect_moderation : en boolean, der angiver, om indholdet overholder moderationspolitikken
- error : i tilfælde af fejl, en kode (
invalid_argument,permission_denied,failed_precondition,service_unavailableellerinternal_error) og en besked - usage.cost_in_usd_ticks : omkostningen ved anmodningen, i ti-milliardtedele af en dollar
Feltet progress fortjener en bemærkning: det styrer ikke din kontrollogik, som altid bør basere sig på status, men det er guld værd til brugergrænsefladen. At vise „62 %” i stedet for en statisk spinner ændrer fuldstændig opfattelsen af en ventetid, der kan vare flere minutter.
Tre tilstande, tre handlinger
| Status | Progress | Betydning |
|---|---|---|
pending | 0-99 | Generering i gang |
done | 100 | Færdig, URL tilgængelig |
failed | fraværende | Generering mislykkedes |
Så længe status er pending, fortsætter genereringen: du skal blot fortsætte med at forespørge med regelmæssige intervaller og videregive progress til din grænseflade. Når den skifter til done, er videoen klar, og det eneste, du skal gøre, er at læse video.url og downloade filen med det samme – disse URL’er er midlertidige, og dokumentationen specificerer ikke deres levetid, hvilket forbyder lagring af dem i en database til senere brug.
Endelig indikerer statussen failed en produktionsfejl, og feltet error fortæller dig hvilken. Distinktionen er vigtig for det, der følger: service_unavailable (tjenesten er midlertidigt overbelastet) eller internal_error berettiger til at prøve igen senere, mens invalid_argument eller permission_denied – afvist prompt, ugyldig kildebillede eller -video – kræver, at du først korrigerer anmodningen. Python SDK’en signalerer også via en fejl, hvis en udskudt anmodning er udløbet, før den blev hentet.
Implementer polling
Den synkrone version passer ind i en enkelt funktion. Den kører i en løkke indtil timeout, afslutter tidligt ved fejl ved at kaste dens kode og returnerer URL’en, så snart videoen er klar.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Vent på, at videogenereringen er færdig."""
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"Generering mislykkedes [{erreur.get('code')}] : {erreur.get('message')}")
print(f"I gang... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout efter {timeout} sekunder")
I en tjeneste, der håndterer flere anmodninger på én gang, bliver denne blokerende version en flaskehals: hver ventetid immobiliserer en tråd i minutter. Den asynkrone overførsel frigør event loop’en mellem forespørgslerne og lader dig spore dusinvis af genereringer parallelt.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Asynkron version af polling."""
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"Generering mislykkedes : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Indstil polling-intervallet
Valg af intervallet afbalancerer responsivitet mod spildte anmodninger. Fem sekunder er et godt kompromis i de fleste tilfælde. Ved lange genereringer – ti til femten sekunders video – er ti til femten sekunder mellem polls rigeligt og reducerer trafikken. Omvendt berettiger en interaktiv applikation, hvor brugeren ser på en fremskridtslinje, at gå ned til to eller tre sekunder. Under ét sekund vil du dog ikke accelerere noget: genereringen fortsætter i sit eget tempo, og du ganger kun antallet af anmodninger uden grund.
Vigtige pointer
- Alle videooperationer er asynkrone: POST til indsendelse, GET til hentning
- Tre mulige statusser: pending, done, failed (med en fejlkode)
- Feltet
progress(0-100) lader dig spore fremskridt - Implementer en timeout og et polling-interval, der passer til dit brugstilfælde
- Video-URL’er er midlertidige: download straks