Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gestione degli errori e deployment in produzione

Lezione 12 di 12 Aggiornata il 3 novembre 2026 Intermedio
In questa pagina
  1. Prepara la tua applicazione per la produzione
  2. Due famiglie di errori, due momenti
  3. Riprova in modo intelligente
  4. Una coda per tenere il passo
  5. Verifica la tua chiave prima di dipenderne
  6. Vedi cosa succede in produzione
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

Aggiornato il 2 novembre 2026 sulla base della documentazione video di xAI e del codice xai-sdk 1.21.0: client.video.generate (non client.videos), risultato in url, fallimenti segnalati da VideoGenerationError con un codice (invalid_argument, service_unavailable…), limite di frequenza ricevuto come grpc.RpcError con codice RESOURCE_EXHAUSTED — la classe RateLimitError e lo stato expired non esistono. Integrazione del 3 novembre 2026: il limite di frequenza conta le richieste al secondo (10 al livello base), non “60 RPM”, e il costo effettivo per generazione si legge da usage.cost_in_usd_ticks. Fonti: Generazione Video · Limiti di frequenza.

Prepara la tua applicazione per la produzione

Uno script che genera un video sulla tua macchina e un servizio che ne produce centinaia al giorno per utenti reali non hanno quasi nulla in comune. Quest’ultimo deve gestire rifiuti di moderazione, superamenti di quota, incidenti server e URL in scadenza senza mai perdere silenziosamente una generazione addebitata. Questa lezione copre i meccanismi che fanno la differenza: classificazione degli errori, strategia di retry, architettura a coda e osservabilità.

Due famiglie di errori, due momenti

La prima famiglia appare immediatamente, al momento della chiamata POST. Si tratta di errori rigorosi di richiesta, e il codice HTTP è sufficiente per decidere cosa fare.

Codice HTTPCausaSoluzione
400Parametri non validi (ad esempio, una voce sconosciuta in reference_audios)Correggi la richiesta
401Chiave API non valida o scadutaVerifica l’autenticazione
429Limite di frequenza superato (richieste al secondo, in base al livello)Implementa il backoff
500Errore del serverRiprova con backoff esponenziale

La seconda famiglia si manifesta molto più tardi, durante il polling, dopo che la richiesta è stata accettata e la generazione è iniziata.

StatoCausa probabileAzione
failed + invalid_argument o permission_deniedRichiesta o contenuto rifiutatoModifica il prompt o la sorgente
failed + service_unavailable o internal_errorServizio sovraccarico, incidenteRiprova più tardi

Questa distinzione non è accademica: un 400 deve tornare istantaneamente al chiamante perché il codice è in errore, mentre uno stato failed si verifica dopo diversi minuti di attesa e deve essere gestito nel contesto del job, non nella richiesta HTTP che lo ha attivato.

Riprova in modo intelligente

La base comune è il backoff esponenziale con un po’ di jitter. Raddoppiare il ritardo dà tempo a un incidente transitorio di risolversi, e il jitter impedisce che tutti i tuoi processi riprovino nello stesso istante dopo un picco — un fenomeno che trasforma un micro-guasto in un fallimento duraturo.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Esegue una funzione con retry e backoff esponenziale."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Backoff esponenziale con jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Tentativo {attempt + 1} fallito: {e}. Riprovo tra {delay:.1f}s")
            await asyncio.sleep(delay)

Questo schema generico non basta tuttavia, perché non tutti gli errori meritano la stessa pazienza. Un superamento di quota si risolve aspettando un minuto intero; un rifiuto di moderazione non si risolverà mai, e riprovare equivale a pagare più volte per lo stesso fallimento. La funzione seguente differenzia i casi.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Codici di fallimento che un retry non risolverà
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Generazione video con retry mirato (client: xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # richiesta o contenuto rifiutato: correggi prima di rilanciare
            await asyncio.sleep(5 * (attempt + 1))  # servizio sovraccarico, incidente
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # limite di frequenza: backoff
        except TimeoutError:
            if is_last:
                raise
            # Concedi più tempo per il prossimo tentativo
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Una coda per tenere il passo

Non appena il tuo servizio riceve richieste da più utenti, devi disaccoppiare la ricezione delle richieste dall’esecuzione e, soprattutto, limitare la concorrenza per rimanere sotto il limite di frequenza del tuo livello. Una coda abbinata a un semaforo soddisfa entrambe le esigenze: i job si accumulano liberamente, ma ne vengono eseguiti al massimo dieci alla volta.

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Aggiunge una generazione alla coda."""
        self.queue.append((job_id, params))

    async def process(self):
        """Elabora tutte le generazioni in sospeso."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Esegue una generazione con controllo della concorrenza."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

Nota che ogni job mantiene il suo esito in results, successo o fallimento: una generazione che scompare senza lasciare traccia è un incidente che nessuno può diagnosticare.

Il secondo riflesso architetturale riguarda lo storage. Poiché gli URL dei video sono temporanei, il download deve essere automatico e immediato, con una denominazione basata su timestamp che garantisca nessuna collisione tra due generazioni simultanee.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Scarica e salva un video generato."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Verifica la tua chiave prima di dipenderne

L’endpoint GET /v1/api-key ti informa sullo stato della tua chiave. Chiamarlo all’avvio del servizio evita di scoprire una chiave bloccata dopo venti richieste fallite, mentre i tuoi utenti aspettano.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("Chiave API o team bloccati, oppure chiave disabilitata")

Vedi cosa succede in produzione

Cinque indicatori bastano per pilotare un servizio di generazione video. Il tasso di successo, ovvero la quota di generazioni che terminano in done, misura la salute generale. Il tempo medio di generazione, misurato tra l’invio e lo stato done, serve a calibrare i tuoi timeout e informare i tuoi utenti. Il tasso di errore suddiviso per tipo — failed per codice di errore, timeout, limite di frequenza — ti dice dove concentrare gli sforzi: un aumento dei timeout senza aumento dei failed segnala generazioni più lente della tua scadenza di attesa, ad esempio, non fallimenti. Il costo cumulativo, ottenuto sommando il campo usage.cost_in_usd_ticks da ogni risultato (un dollaro equivale a 10 miliardi di tick), o alternativamente moltiplicando le durate generate per il prezzo al secondo del modello, deve essere monitorato quotidianamente. Infine, l’uso della quota, in richieste al secondo rispetto al limite del tuo livello (10 al livello base per i modelli video), anticipa la saturazione prima che si traduca in 429.

Queste metriche si costruiscono naturalmente da un log strutturato, dove ogni generazione lascia una riga utilizzabile dal tuo strumento di analisi.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

Prima di aprire il tuo servizio al pubblico, rivedi tutto dall’inizio. Il retry con backoff esponenziale e jitter deve essere attivo, e la concorrenza limitata da un semaforo per rimanere sotto il limite di frequenza. I download dei video devono attivarsi automaticamente non appena sono pronti, senza dipendere dall’azione umana. Ogni generazione deve lasciare una riga di log che porti il suo request_id, lo stato e il costo, altrimenti il tasso di errore e il tempo medio di generazione rimarranno inverificabili. Controlla lo stato della chiave API all’avvio piuttosto che al primo fallimento. E imposta un budget con avvisi di superamento: a 0,05 $ al secondo, un loop di retry illimitato consuma più velocemente di quanto pensi.

Prezzi verificati il 3 novembre 2026 — i prezzi evolvono regolarmente: prima di qualsiasi calcolo di budget, verifica la griglia attuale sulla pagina ufficiale dei modelli e prezzi xAI.

Punti chiave

  • Gli errori si dividono in sincroni (richiesta) e asincroni (generazione)
  • Non tutti gli errori meritano un retry: la moderazione è definitiva
  • Usa un semaforo per limitare le generazioni concorrenti
  • Gli URL temporanei richiedono un download immediato e sistematico
  • Traccia le metriche di costo, successo e tempo di generazione per pilotare il tuo servizio

Metti alla prova le tue conoscenze

Video generativo in produzione: valida l’intero flusso di lavoro.

1. Quali sono le particolarità di un prompt video?

Risposta: Descrivi l’azione e il movimento, non solo la scena: soggetto, spostamento, atmosfera, inquadratura — la dimensione temporale è ciò che distingue il prompt video dal prompt immagine.

2. Cosa permette l'image-to-video?

Risposta: Animare un’immagine esistente, o portare persone e prodotti dati in una nuova scena usando immagini di riferimento — e, su grok-imagine-video-1.5, fissare la prima, l’ultima o le immagini chiave: la tua identità visiva diventa un punto di partenza, non un caso fortuito.

3. Editing ed estensione: quali usi?

Risposta: /videos/edits modifica un video generato, /videos/extensions lo prolunga — ed entrambi si combinano per costruire lunghe sequenze per iterazioni.

4. Perché il workflow è asincrono?

Risposta: La generazione video richiede tempo: invii un job, ne verifichi lo stato (polling), poi recuperi il risultato — l’SDK xAI automatizza questo polling.

5. Cosa pianificare per la produzione?

Risposta: Gestione degli errori e job falliti, download immediato degli output e tracciamento dei costi (risoluzione, durata, iterazioni) — il video è la modalità più costosa: va budgettata.

Prompt temporale, riferimento visivo, asincrono padroneggiato: il video generativo diventa una pipeline, non una lotteria.