xAI SDK och automatisk pollning
På denna sida
Uppdaterat 2 november 2026 baserat på xAI:s videodokumentation och kod för
xai-sdk1.21.0: metoderna heterclient.video.generateochclient.video.extend(redigering användergeneratemedvideo_url), resultatet exponerarurl, fördröjningen ställs in via etttimedelta-objekt och standardintervallet för pollning är en sekund.awaitkräver den asynkrona klientenAsyncClient, och undantagetVideoGenerationErrorimporteras frånxai_sdk.video. Den gamla versionen anropade metoder och ett undantagsmodul som inte finns. Källor: Video Generation · Video Editing · Video Extension · xai-sdk-python.
Förenkla pollning med SDK:t
I föregående lektion fick du skriva en pollningsloop för hand. Det är en nyttig övning för att förstå livscykeln för generering, men det är också trettio rader kod som måste underhållas i varje projekt, med egen timeout-hantering, felhantering och statuskonverteringar. xAI:s officiella Python-SDK (pip install xai-sdk) kapslar in allt detta: du skickar begäran och SDK:t hanterar väntetiden åt dig.
Ett enda anrop istället för en loop
Metoden client.video.generate samlar inskickning, spårning och hämtning. Den lämnar bara tillbaka kontrollen när videon är klar, eller kastar ett undantag om något gick fel.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Text-till-video-generering med automatisk pollning
video = client.video.generate(
prompt="En soluppgång över Alperna, accelererat time-lapse",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Duration: {video.duration} s, model: {video.model}")
Bakom dessa få rader gör SDK:t exakt det du kodade tidigare: skickar begäran, pollar status varje sekund som standard, och returnerar sedan resultatet eller kastar ett undantag beroende på utfallet.
En inställning förtjänar din uppmärksamhet direkt vid driftsättning: som standard väntar SDK:t upp till 10 minuter innan det ger upp. Det är bekvämt för ett nattligt produktionsskript, men alldeles för långt för en webbförfrågan där en användare väntar på ett svar. Parametrarna timeout och interval, båda timedelta-objekt, styr gränsen och rytmen:
from datetime import timedelta
video = client.video.generate(
prompt="Din beskrivning",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # Max 5 minuter
interval=timedelta(seconds=5), # En kontroll var 5:e sekund
)
Om du vill behålla kontrollen över väntetiden – för att exempelvis rapportera framsteg – så skickar client.video.start begäran och returnerar dess request_id, som client.video.get sedan frågar efter.
Hantera fel vid källan
SDK:t skiljer på olika typer av misslyckanden, vilket sparar dig från att behöva analysera strängar för att lista ut vad som hände:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Din beskrivning",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video klar: {video.url}")
except VideoGenerationError as e:
print(f"Generering misslyckades [{e.code}]: {e.message}")
except TimeoutError:
print("Timeout överskriden: öka timeout eller förenkla begäran")
Varje fel kräver en annan reaktion, och att blanda ihop dem leder till onödiga försöksloopar eller, värre, debiterade genereringar som inte ger något resultat.
| Fel | Orsak | Rekommenderad åtgärd |
|---|---|---|
VideoGenerationError | Misslyckande signalerat av API:t: prompt vägrad, ogiltig källa, tjänsten överbelastad… (code, message) | Läs koden: åtgärda begäran eller försök igen senare om tjänsten inte var tillgänglig |
TimeoutError | Klientens väntetid överskriden | Öka timeout eller minska durationen |
RuntimeError | Senarelagd begäran har löpt ut, eller slutfördes utan resultat | Starta om genereringen |
grpc.RpcError | SDK-transportsfel, inklusive hastighetsbegränsningar (kod RESOURCE_EXHAUSTED) och nyckelproblem | Sprid ut begäranden med backoff-strategi eller kontrollera nyckeln |
SDK:t använder gRPC: en överskriden hastighetsbegränsning visas inte som en HTTP 429-kod här, utan som ett grpc.RpcError med koden RESOURCE_EXHAUSTED.
Redigering och förlängning, samma enkelhet
Redigering har ingen dedikerad metod: det är generate med en källvideo, skickad som video_url (video på upp till 8,7 sekunder, samma utmatningslängd, max 720p).
video = client.video.generate(
prompt="Transformera scenen till japansk anime-stil",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Förlängning förlänger en sekvens på 2 till 15 sekunder med ett segment på 2 till 10 sekunder, och returnerar hela videon:
video = client.video.extend(
prompt="Fortsätt scenen med en panering åt höger",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Notera skillnaden mot REST-API:t: SDK:t tar emot videon som en parameter video_url, medan JSON-bodyn förväntar sig ett video-objekt med dess url-egenskap.
Lämna aldrig en video i molnet
SDK:t ändrar ingenting på det faktum att resultat-URL:er är tillfälliga. Om din kod bara visar video.url har du betalt för en generering som snart försvinner. Bästa praxis är att kedja generering och nedladdning i samma funktion, så att det blir omöjligt att glömma steget.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Genererar en video och sparar den lokalt (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Omedelbar nedladdning
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 sparad: {output_file}")
return output_file
För lagring utan transit genom din server kan parametern storage_options vid generering deponera videon i xAI Files API, med en utgångstid efter ditt val.
Generera flera videor samtidigt
Med den asynkrona klienten är varje anrop en korutin, och asyncio.gather startar en hel batch parallellt. Alternativet return_exceptions=True är avgörande här: utan det skulle en enda vägrad begäran få hela batchen att misslyckas och du skulle förlora de resultat som redan erhållits.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Genererar flera videor parallellt."""
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"Begäran {i} misslyckades: {res}")
else:
print(f"Begäran {i} slutförd: {res.url}")
return results
Två skyddsräcken ramar in denna parallellisering. Insändningar konsumerar din hastighetsbegränsning, räknad i begäranden per sekund enligt ditt teams nivå (10 på instegsnivån för videomodeller): för en stor batch, begränsa samtidigheten med en asyncio.Semaphore. Kom också ihåg vad parallellism gör och inte gör: den snabbar inte upp någon enskild generering, den minskar bara den totala batch-tiden.
Bör du överge manuell pollning?
Inte systematiskt. Följande jämförelse visar var varje metod tar ledningen.
| Aspekt | Manuell pollning | SDK |
|---|---|---|
| Komplexitet | Hög | Låg |
| Felhantering | Att implementera | Integrerad |
| Timeout | Att implementera | 10 min standard, konfigurerbar |
| Pollningsintervall | Att välja | 1 s standard, konfigurerbar |
| Flexibilitet | Total | Standard (eller start och get) |
| Beroende | Inget | xAI SDK |
Manuell pollning behåller sin relevans i två situationer: när du behöver finjusterad kontroll, till exempel för att rapportera framsteg till ett gränssnitt i realtid eller för att integrera det i ett befintligt kösystem, och när din driftsmiljö förbjuder tillägg av ytterligare beroenden.
Viktiga punkter
client.video.generateskickar, väntar och returnerar videon (url,duration,model); 10 minuters timeout och en sekunds kontroll som standard- Redigering använder
generatemedvideo_url, förlängning använderclient.video.extend VideoGenerationError(frånxai_sdk.video),TimeoutErrorochRuntimeErrorskiljer på misslyckanden; hastighetsbegränsningar anländer somgrpc.RpcError- Ladda alltid ner videon omedelbart efter generering (tillfälliga URL:er)
- Den asynkrona klienten och
asyncio.gatherparallelliserar en batch, inom din nivås hastighetsbegränsning