Vai al contenuto principale
Italiano— Scegli una lingua
Menu

SDK xAI e polling automatico

Lezione 11 di 12 Aggiornata il 2 novembre 2026 Intermedio
In questa pagina
  1. Semplifica il polling con l’SDK
  2. Una singola chiamata al posto di un ciclo
  3. Gestisci gli errori alla fonte
  4. Montaggio ed estensione, stessa semplicità
  5. Non lasciare mai un video nel cloud
  6. Genera più video contemporaneamente
  7. Dovresti abbandonare il polling manuale?
  8. Punti chiave

Aggiornato il 2 novembre 2026 sulla base della documentazione video di xAI e del codice xai-sdk 1.21.0: i metodi si chiamano client.video.generate e client.video.extend (il montaggio usa generate con video_url), il risultato espone url, il ritardo si imposta tramite un timedelta e l’intervallo di polling predefinito è di un secondo. await richiede il client asincrono AsyncClient e l’eccezione VideoGenerationError si importa da xai_sdk.video. La vecchia versione citava metodi e un modulo di eccezione inesistenti. Fonti: Generazione video · Montaggio video · Estensione video · xai-sdk-python.

Semplifica il polling con l’SDK

Nella lezione precedente hai scritto a mano un ciclo di polling. È un esercizio utile per comprendere il ciclo di vita della generazione, ma sono anche trenta righe di codice da mantenere in ogni progetto, con la propria gestione dei timeout, dei casi di errore e delle conversioni di stato. L’SDK Python ufficiale di xAI (pip install xai-sdk) incapsula tutto questo: invii la richiesta ed è lui a gestire l’attesa.

Una singola chiamata al posto di un ciclo

Il metodo client.video.generate raggruppa invio, tracciamento e recupero. Restituisce il controllo solo quando il video è pronto o solleva un’eccezione se qualcosa è andato storto.

import os

import xai_sdk

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

# Generazione testo-video con polling automatico
video = client.video.generate(
    prompt="Un'alba sulle Alpi, time-lapse accelerato",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

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

Dietro queste poche righe, l’SDK fa esattamente ciò che hai codificato prima: invia la richiesta, interroga lo stato ogni secondo per impostazione predefinita, quindi restituisce il risultato o solleva un’eccezione a seconda dell’esito.

Un’impostazione merita la tua attenzione fin dal deploy: per impostazione predefinita, l’SDK attende fino a 10 minuti prima di rinunciare. È comodo per uno script di produzione notturno, ma troppo lungo per una richiesta web in cui un utente attende una risposta. I parametri timeout e interval, entrambi oggetti timedelta, impostano il limite e il ritmo:

from datetime import timedelta

video = client.video.generate(
    prompt="La tua descrizione",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # max 5 minuti
    interval=timedelta(seconds=5),  # un controllo ogni 5 secondi
)

Se vuoi mantenere il controllo sull’attesa, ad esempio per relayare i progressi, client.video.start invia la richiesta e restituisce il suo request_id, che client.video.get interroga successivamente.

Gestisci gli errori alla fonte

L’SDK distingue i fallimenti, risparmiandoti l’analisi delle stringhe per capire cosa è successo:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="La tua descrizione",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video pronto: {video.url}")
except VideoGenerationError as e:
    print(f"Generazione fallita [{e.code}]: {e.message}")
except TimeoutError:
    print("Timeout superato: aumenta il timeout o semplifica la richiesta")

Ogni errore richiede una reazione diversa e confonderli porta a cicli di retry inutili o, peggio, a generazioni fatturate che non producono nulla.

ErroreCausaAzione raccomandata
VideoGenerationErrorFallimento segnalato dall’API: prompt rifiutato, sorgente non valida, servizio sovraccarico… (code, message)Leggi il codice: correggi la richiesta o riprova più tardi se il servizio non era disponibile
TimeoutErrorTempo di attesa lato client superatoAumenta il timeout o riduci la durata
RuntimeErrorRichiesta differita scaduta o completata senza risultatoRiavvia la generazione
grpc.RpcErrorErrore di trasporto SDK, inclusi limiti di frequenza (codice RESOURCE_EXHAUSTED) e problemi di chiaveSpazia le richieste con backoff o verifica la chiave

L’SDK usa gRPC: un limite di frequenza superato non appare qui come codice HTTP 429, ma come grpc.RpcError con codice RESOURCE_EXHAUSTED.

Montaggio ed estensione, stessa semplicità

Il montaggio non ha un metodo dedicato: è generate con un video sorgente, passato come video_url (video fino a 8,7 secondi, stessa durata in output, max 720p).

video = client.video.generate(
    prompt="Trasforma la scena in stile anime giapponese",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

L’estensione prolunga una sequenza da 2 a 15 secondi con un segmento da 2 a 10 secondi e restituisce il video completo:

video = client.video.extend(
    prompt="Continua la scena con una panoramica a destra",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Nota la differenza con l’API REST: l’SDK prende il video come parametro video_url, mentre il corpo JSON si aspetta un oggetto video con la sua proprietà url.

Non lasciare mai un video nel cloud

L’SDK non cambia nulla riguardo alla natura temporanea degli URL dei risultati. Se il tuo codice si limita a visualizzare video.url, hai pagato per una generazione che presto scomparirà. La best practice è concatenare generazione e download nella stessa funzione, rendendo così impossibile dimenticare il passaggio.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Genera un video e lo salva localmente (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Download immediato
    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 salvato: {output_file}")
    return output_file

Per l’archiviazione senza transito attraverso il tuo server, il parametro storage_options della generazione deposita il video nelle xAI Files API, con una scadenza a tua scelta.

Genera più video contemporaneamente

Con il client asincrono, ogni chiamata è una coroutine e asyncio.gather lancia un intero batch in parallelo. L’opzione return_exceptions=True è decisiva qui: senza di essa, una singola richiesta rifiutata farebbe fallire l’intero batch e perderesti i risultati già ottenuti.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Genera più video in parallelo."""
    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"Richiesta {i} fallita: {res}")
        else:
            print(f"Richiesta {i} completata: {res.url}")

    return results

Due guardrail incorniciano questa parallelizzazione. Le inviazioni consumano il tuo limite di frequenza, conteggiato in richieste al secondo in base al tier del tuo team (10 al tier di ingresso per i modelli video): per un batch ampio, limita la concorrenza con un asyncio.Semaphore. Ricorda anche cosa fa e cosa non fa il parallelismo: non accelera nessuna generazione individuale, riduce solo il tempo totale del batch.

Dovresti abbandonare il polling manuale?

Non sistematicamente. Il confronto seguente mostra dove ciascun approccio prende il sopravvento.

AspettoPolling manualeSDK
ComplessitàAltaBassa
Gestione erroriDa implementareIntegrata
TimeoutDa implementare10 min default, configurabile
Intervallo pollingDa scegliere1 s default, configurabile
FlessibilitàTotaleStandard (o start e get)
DipendenzaNessunaxAI SDK

Il polling manuale mantiene la sua rilevanza in due situazioni: quando hai bisogno di un controllo fine, ad esempio per relayare i progressi a un’interfaccia in tempo reale o per integrarlo in un sistema di code esistente, e quando il tuo contesto di deploy vieta l’aggiunta di una dipendenza extra.

Punti chiave

  • client.video.generate invia, attende e restituisce il video (url, duration, model); timeout di 10 minuti e controllo ogni secondo per default
  • Il montaggio usa generate con video_url, l’estensione usa client.video.extend
  • VideoGenerationError (da xai_sdk.video), TimeoutError e RuntimeError distinguono i fallimenti; i limiti di frequenza arrivano come grpc.RpcError
  • Scarica sempre il video immediatamente dopo la generazione (URL temporanei)
  • Il client asincrono e asyncio.gather parallelizzano un batch, entro il limite di frequenza del tuo tier