Spring til hovedindhold
Dansk— Vælg et sprog
Menu

xAI SDK og automatisk polling

Lektion 11 af 12 Opdateret 2. november 2026 Mellem
På denne side
  1. Forenkl polling med SDK’et
  2. Ét kald i stedet for en løkke
  3. Håndtér fejl ved kilden
  4. Redigering og udvidelse, samme lethed
  5. Lad aldrig en video blive i skyen
  6. Generér flere videoer på én gang
  7. Skal du opgive manuel polling?
  8. Vigtige pointer

Opdateret 2. november 2026 baseret på xAIs videodokumentation og xai-sdk 1.21.0-kode: metoderne hedder client.video.generate og client.video.extend (redigering bruger generate med video_url), resultatet eksponerer url, forsinkelsen sættes via en timedelta, og standard-polling-intervallet er ét sekund. await kræver den asynkrone klient AsyncClient, og undtagelsen VideoGenerationError importeres fra xai_sdk.video. Den gamle version kaldte på metoder og et undtagelsesmodul, der ikke eksisterer. Kilder: Video Generation · Video Editing · Video Extension · xai-sdk-python.

Forenkl polling med SDK’et

I den forrige lektion skrev du en polling-løkke i hånden. Det er en nyttig øvelse for at forstå livscyklussen for generering, men det er også tredive linjer kode, du skal vedligeholde i hvert projekt, med sin egen timeout-håndtering, fejltilfælde og statuskonverteringer. xAIs officielle Python-SDK (pip install xai-sdk) kapsler alt dette ind: du sender anmodningen, og SDK’et håndterer ventetiden.

Ét kald i stedet for en løkke

Metoden client.video.generate samler indsendelse, sporing og hentning. Den giver først kontrollen tilbage, når videoen er klar, eller rejser en undtagelse, hvis noget gik galt.

import os

import xai_sdk

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

# Tekst-til-video-generering med automatisk polling
video = client.video.generate(
    prompt="En solopgang over Alperne, accelereret time-lapse",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

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

Bag disse få linjer gør SDK’et præcis det, du kodede tidligere: indsender anmodningen, poller status hvert sekund som standard og returnerer derefter resultatet eller rejser en undtagelse afhængigt af udfaldet.

Én indstilling fortjener din opmærksomhed lige fra starten: Som standard venter SDK’et op til 10 minutter, før det giver op. Det er behageligt til et natligt produktionsscript, men alt for længe til en webanmodning, hvor en bruger venter på et svar. Parametrene timeout og interval, som begge er timedelta-objekter, sætter grænsen og rytmen:

from datetime import timedelta

video = client.video.generate(
    prompt="Din beskrivelse",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # Maks 5 minutter
    interval=timedelta(seconds=5),  # Ét tjek hvert 5. sekund
)

Hvis du vil beholde kontrollen over ventetiden – for eksempel for at videresende fremskridt – så indsender client.video.start anmodningen og returnerer dens request_id, som client.video.get derefter spørger efter.

Håndtér fejl ved kilden

SDK’et skelner mellem fejltyper, hvilket sparer dig for at analysere strenge for at finde ud af, hvad der skete:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Din beskrivelse",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video klar: {video.url}")
except VideoGenerationError as e:
    print(f"Generering mislykkedes [{e.code}]: {e.message}")
except TimeoutError:
    print("Timeout overskredet: øg timeout'en eller forenkl anmodningen")

Hver fejl kræver en anden reaktion, og at forveksle dem fører til ubrugelige genforsøgsløkker eller, værre endnu, fakturerede genereringer, der ikke giver noget resultat.

FejlÅrsagAnbefalet handling
VideoGenerationErrorFejl signaleret af API’et: prompt afvist, ugyldig kilde, tjeneste overbelastet… (code, message)Læs koden: ret anmodningen, eller prøv igen senere, hvis tjenesten var utilgængelig
TimeoutErrorKlientens ventetid overskredetØg timeout eller reducer varigheden
RuntimeErrorUdskudt anmodning udløbet eller fuldført uden resultatGenstart genereringen
grpc.RpcErrorSDK-transportfejl, herunder hastighedsbegrænsninger (kode RESOURCE_EXHAUSTED) og nøgleproblemerSpred anmodninger med backoff, eller tjek nøglen

SDK’et bruger gRPC: En overskredet hastighedsbegrænsning vises ikke her som en HTTP 429-kode, men som en grpc.RpcError med koden RESOURCE_EXHAUSTED.

Redigering og udvidelse, samme lethed

Redigering har ingen dedikeret metode: det er generate med en kildevideo, sendt som video_url (video på op til 8,7 sekunder, samme output-varighed, maks 720p).

video = client.video.generate(
    prompt="Transformér scenen til japansk anime-stil",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Udvidelse forlænger en sekvens på 2 til 15 sekunder med et segment på 2 til 10 sekunder og returnerer hele videoen:

video = client.video.extend(
    prompt="Fortsæt scenen med et panoreringsbevægelse mod højre",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Bemærk forskellen fra REST-API’et: SDK’et tager videoen som en video_url-parameter, hvorimod JSON-bodyet forventer et video-objekt med dets url-egenskab.

Lad aldrig en video blive i skyen

SDK’et ændrer ikke på, at resultat-URL’er er midlertidige. Hvis din kode blot viser video.url, har du betalt for en generering, der snart vil være væk. Bedste praksis er at kæde generering og download sammen i samme funktion, så det bliver umuligt at glemme trinnet.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Genererer en video og gemmer den lokalt (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Øjeblikkeligt download
    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 gemt: {output_file}")
    return output_file

Til lagring uden transit gennem din server kan parameteren storage_options ved generering deponere videoen i xAI Files API med en udløbsdato efter dit valg.

Generér flere videoer på én gang

Med den asynkrone klient er hvert kald en coroutine, og asyncio.gather lancerer en hel batch parallelt. Indstillingen return_exceptions=True er afgørende her: uden den ville en enkelt afvist anmodning få hele batchen til at fejle, og du ville miste de resultater, der allerede var opnået.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Genererer flere videoer parallelt."""
    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"Anmodning {i} mislykkedes: {res}")
        else:
            print(f"Anmodning {i} fuldført: {res.url}")

    return results

To sikkerhedsforanstaltninger rammer denne parallelisering ind. Indsendelser bruger din hastighedsbegrænsning, der tælles i anmodninger per sekund afhængigt af dit teams niveau (10 på startniveauet for videomodeller): til en stor batch skal du begrænse samtidigheden med en asyncio.Semaphore. Husk også, hvad parallelisme gør, og hvad den ikke gør: den accelererer ikke nogen individuel generering, den reducerer kun den samlede batch-tid.

Skal du opgive manuel polling?

Ikke systematisk. Følgende sammenligning viser, hvor hver tilgang tager føringen.

AspektManuel pollingSDK
KompleksitetHøjLav
FejlhåndteringSkal implementeresIntegreret
TimeoutSkal implementeres10 min standard, konfigurerbar
Polling-intervalSkal vælges1 s standard, konfigurerbar
FleksibilitetTotalStandard (eller start og get)
AfhængighedIngenxAI SDK

Manuel polling beholder sin relevans i to situationer: når du har brug for fin kontrol, for eksempel for at videresende fremskridt til en realtidsgrænseflade eller for at integrere det i et eksisterende køsystem, og når din implementeringskontekst forbyder tilføjelse af en ekstra afhængighed.

Vigtige pointer

  • client.video.generate indsender, venter og returnerer videoen (url, duration, model); 10 minutters timeout og ét sekunds tjek som standard
  • Redigering bruger generate med video_url, udvidelse bruger client.video.extend
  • VideoGenerationError (fra xai_sdk.video), TimeoutError og RuntimeError skelner mellem fejl; hastighedsbegrænsninger ankommer som grpc.RpcError
  • Download altid videoen umiddelbart efter generering (midlertidige URL’er)
  • Den asynkrone klient og asyncio.gather paralleliserer en batch inden for dit levels hastighedsbegrænsning