SDK xAI e polling automatico
In questa pagina
Aggiornato il 2 novembre 2026 sulla base della documentazione video di xAI e del codice
xai-sdk1.21.0: i metodi si chiamanoclient.video.generateeclient.video.extend(il montaggio usagenerateconvideo_url), il risultato esponeurl, il ritardo si imposta tramite untimedeltae l’intervallo di polling predefinito è di un secondo.awaitrichiede il client asincronoAsyncCliente l’eccezioneVideoGenerationErrorsi importa daxai_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.
| Errore | Causa | Azione raccomandata |
|---|---|---|
VideoGenerationError | Fallimento 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 |
TimeoutError | Tempo di attesa lato client superato | Aumenta il timeout o riduci la durata |
RuntimeError | Richiesta differita scaduta o completata senza risultato | Riavvia la generazione |
grpc.RpcError | Errore di trasporto SDK, inclusi limiti di frequenza (codice RESOURCE_EXHAUSTED) e problemi di chiave | Spazia 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.
| Aspetto | Polling manuale | SDK |
|---|---|---|
| Complessità | Alta | Bassa |
| Gestione errori | Da implementare | Integrata |
| Timeout | Da implementare | 10 min default, configurabile |
| Intervallo polling | Da scegliere | 1 s default, configurabile |
| Flessibilità | Totale | Standard (o start e get) |
| Dipendenza | Nessuna | xAI 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.generateinvia, attende e restituisce il video (url,duration,model); timeout di 10 minuti e controllo ogni secondo per default- Il montaggio usa
generateconvideo_url, l’estensione usaclient.video.extend VideoGenerationError(daxai_sdk.video),TimeoutErroreRuntimeErrordistinguono i fallimenti; i limiti di frequenza arrivano comegrpc.RpcError- Scarica sempre il video immediatamente dopo la generazione (URL temporanei)
- Il client asincrono e
asyncio.gatherparallelizzano un batch, entro il limite di frequenza del tuo tier