Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Flusso di lavoro asincrono e polling

Lezione 10 di 12 Aggiornata il 2 novembre 2026 Intermedio
In questa pagina
  1. Comprendere il ciclo di vita del video
  2. Verificare lo stato della generazione
  3. Tre stati, tre azioni
  4. Implementare il polling
  5. Impostare l’intervallo di polling
  6. Punti chiave

Aggiornato il 2 novembre 2026. Basato sul riferimento dell’API Video di xAI: l’URL si trova in video.url (non video_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.

1

Invia richiesta

POST all'endpoint di generazione, modifica o estensione. Risposta immediata con un request_id.

2

Polling dello stato

GET /v1/videos/{request_id} a intervalli regolari. Campo progress da 0 a 100.

3

Recupera risultato

Quando lo stato è done (progress = 100), l'URL del video è disponibile.

4

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 video presente 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, o internal_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

StatoProgressoSignificato
pending0-99Generazione in corso
done100Completato, URL disponibile
failedassenteGenerazione 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