Flusso di lavoro asincrono e polling
In questa pagina
Aggiornato il 2 novembre 2026. Basato sul riferimento dell’API Video di xAI: l’URL si trova in
video.url(nonvideo_url), una generazione ha solo tre stati (pending,done,failed, quest’ultimo accompagnato da un codice di errore) e i limiti di frequenza sono espressi in richieste al secondo in base al livello del team. Fonti: Generazione Video · Riferimento Video · Limiti di frequenza.
Comprendere il ciclo di vita del video
Tutte le operazioni video nell’API xAI sono asincrone, e questa caratteristica modella l’architettura della tua applicazione più di quanto potresti pensare inizialmente. Una chiamata chat o una generazione di immagini restituiscono un risultato immediato; la generazione video, invece, richiede un tempo di elaborazione significativo e restituisce solo una conferma. Sta a te implementare il tracciamento: interrogare periodicamente lo stato del task, rilevare il completamento e recuperare il file. Il ciclo completo consiste in quattro passaggi.
Invia richiesta
POST all'endpoint di generazione, modifica o estensione. Risposta immediata con un request_id.
Polling dello stato
GET /v1/videos/{request_id} a intervalli regolari. Campo progress da 0 a 100.
Recupera risultato
Quando lo stato è done (progress = 100), l'URL del video è disponibile.
Scarica immediatamente
L'URL del video è temporaneo. Scaricalo il prima possibile.
Verificare lo stato della generazione
Il tracciamento implica una semplice richiesta GET all’endpoint di stato, utilizzando l’identificatore ricevuto al momento dell’invio.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
La risposta espone le seguenti informazioni utili:
- status : lo stato corrente della generazione
- progress : un intero da 0 a 100 che indica l’avanzamento
- video.url : l’URL del video, all’interno dell’oggetto
videopresente quando lo stato èdone, con la sua durata (video.duration) - video.respect_moderation : un booleano che indica se il contenuto è conforme alla politica di moderazione
- error : in caso di fallimento, un codice (
invalid_argument,permission_denied,failed_precondition,service_unavailable, ointernal_error) e un messaggio - usage.cost_in_usd_ticks : il costo della richiesta, in decimiliardesimi di dollaro
Il campo progress merita una nota: non guida la tua logica di controllo, che dovrebbe sempre basarsi su status, ma è prezioso per l’interfaccia utente. Visualizzare «62%» invece di un indicatore di caricamento statico cambia completamente la percezione di un’attesa che può durare diversi minuti.
Tre stati, tre azioni
| Stato | Progresso | Significato |
|---|---|---|
pending | 0-99 | Generazione in corso |
done | 100 | Completato, URL disponibile |
failed | assente | Generazione fallita |
Finché lo stato è pending, la generazione prosegue: devi semplicemente continuare a interrogare a intervalli regolari, relayando progress alla tua interfaccia. Quando passa a done, il video è pronto e l’unica cosa da fare è leggere video.url e scaricare immediatamente il file: questi URL sono temporanei e la documentazione non specifica la loro durata, il che vieta di archiviarli in un database per un uso successivo.
Infine, lo stato failed indica un errore di produzione e il campo error ti dice quale. La distinzione è importante per ciò che segue: service_unavailable (servizio temporaneamente sovraccarico) o internal_error giustificano un nuovo tentativo più tardi, mentre invalid_argument o permission_denied—prompt rifiutato, immagine o video sorgente non validi—richiedono prima di correggere la richiesta. L’SDK Python, dal canto suo, segnala anche tramite un errore una richiesta differita scaduta prima di essere recuperata.
Implementare il polling
La versione sincronica sta in un’unica funzione. Esegue un loop fino al timeout, esce anticipatamente in caso di errore sollevandone il codice e restituisce l’URL non appena il video è pronto.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Attendi il completamento della generazione video."""
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"Generazione fallita [{erreur.get('code')}] : {erreur.get('message')}")
print(f"In corso... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout dopo {timeout} secondi")
In un servizio che gestisce più richieste contemporaneamente, questa versione bloccante diventa un collo di bottiglia: ogni attesa immobilizza un thread per minuti. La trasposizione asincrona libera l’event loop tra le query e ti permette di tracciare dozzine di generazioni in parallelo.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Versione asincrona del 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"Generazione fallita : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Impostare l’intervallo di polling
Scegliere l’intervallo significa bilanciare reattività e richieste sprecate. Cinque secondi sono un buon compromesso nella maggior parte dei casi. Per generazioni lunghe—da dieci a quindici secondi di video—dieci o quindici secondi tra un polling e l’altro sono sufficienti e riducono il traffico. Al contrario, un’applicazione interattiva in cui l’utente osserva una barra di avanzamento giustifica la discesa a due o tre secondi. Sotto il secondo, tuttavia, non accelererai nulla: la generazione procede al suo ritmo e moltiplicherai solo le richieste inutilmente.
Punti chiave
- Tutte le operazioni video sono asincrone: POST per inviare, GET per recuperare
- Tre stati possibili: pending, done, failed (con un codice di errore)
- Il campo
progress(0-100) ti permette di tracciare l’avanzamento - Implementa un timeout e un intervallo di polling adatti al tuo caso d’uso
- Gli URL dei video sono temporanei: scaricali immediatamente