Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Endpoint /v1/videos/generations: La tua prima video

Lezione 1 di 12 Aggiornata il 3 novembre 2026 Intermedio
In questa pagina
  1. Generare un video da testo
  2. Struttura della richiesta
  3. Una prima chiamata end-to-end
  4. Audio, di default
  5. Punti chiave

Aggiornato il 3 novembre 2026 sulla base della documentazione video di xAI: sono disponibili tre modelli video (grok-imagine-video-1.5, la sua versione -lite e grok-imagine-video), la risoluzione arriva fino a 1080p sui modelli 1.5, i video includono una traccia audio di default (generate_audio), i limiti di frequenza si contano in richieste al secondo e il parametro size presentato dalla vecchia versione non compare nel riferimento API. Fonti: Video Generation · Pricing.

Generare un video da testo

L’API di xAI espone un endpoint video dedicato, POST /v1/videos/generations, che trasforma una descrizione scritta in una sequenza animata utilizzando uno dei tre modelli Grok Imagine Video. Pensalo come uno studio on demand: descrivi una scena, il modello la mette in movimento e tu recuperi un file MP4 pronto per il montaggio. Clip promozionali, visualizzazioni di concept, animazioni illustrative: tutti questi casi d’uso passano da questo stesso endpoint, quindi lo analizzeremo per primo.

L’esempio sopra ti dà un’idea del risultato atteso. Prima di scrivere la tua prima richiesta, tieni a mente i quattro limiti che inquadrano tutto ciò che produci con questi modelli.

1-15s
Durata per video
1080p
Risoluzione massima
da $0.02
Per secondo generato
9
Rapporti disponibili

Struttura della richiesta

Il corpo della richiesta è un oggetto JSON di rassicurante semplicità. Dichiarì il modello, scrivi il tuo prompt e inquadri il risultato con tre parametri di formattazione.

{
  "model": "grok-imagine-video",
  "prompt": "A dolphin jumping in a sunset",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

Ecco il significato esatto di ogni campo:

  • model: grok-imagine-video-1.5, il più recente, la sua versione economica grok-imagine-video-1.5-lite, raccomandata da xAI per video semplici, oppure grok-imagine-video, la generazione precedente, ancora utilizzata negli esempi di questo corso
  • prompt: la tua descrizione testuale della scena desiderata
  • duration: durata in secondi, tra 1 e 15 (8 di default)
  • aspect_ratio: rapporto dell’immagine (16:9 di default, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
  • resolution: 480p (default), 720p o 1080p: quest’ultima è resa nativamente da grok-imagine-video-1.5 nel text-to-video e image-to-video, ottenuta tramite upsampling da 720p sulla versione -lite, e assente in grok-imagine-video, che si ferma a 720p

Due punti meritano enfasi immediata. Il modello grok-imagine-video costa $0.050 per secondo di video generato ($0.08 per grok-imagine-video-1.5, $0.02 per la sua versione -lite, al 3 novembre 2026): una sequenza di cinque secondi ti costa quindi $0.25 con il primo, indipendentemente da quanti tentativi ti hanno portato lì. E il limite di frequenza si conta in richieste al secondo, a seconda del tier del tuo team: 10 al tier di ingresso per i modelli video, un margine confortevole per l’uso normale, che diventa un vincolo quando lanci batch massivi.

Soprattutto, la generazione è asincrona. La tua chiamata POST non restituisce un video: restituisce un request_id, e spetta poi a te interrogare lo stato finché il file non è pronto. Questo meccanismo di polling è oggetto di una lezione completa più avanti nel corso; per ora, ricorda solo che la risposta immediata è un’accusa di ricevuta, non un risultato.

Una prima chiamata end-to-end

Passiamo alla pratica con curl. La seguente richiesta ordina una sequenza di cinque secondi in 720p, formato landscape.

curl -X POST "https://api.x.ai/v1/videos/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cat playing with a ball of yarn in a bright living room",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

La risposta sta su una riga:

{
  "request_id": "vid_abc123def456"
}

Conserva con cura questo identificatore. È l’unico modo per recuperare il video una volta completata la generazione, e un’applicazione che lo perde ha pagato per una generazione che non recupererà mai. In un servizio reale, lo registri nei log prima ancora di avviare il polling.

Audio, di default

Un video generato include una traccia audio di default, con, su grok-imagine-video-1.5 e la sua versione -lite, un parlato sincronizzato al movimento delle labbra. Per un video muto, destinato ad esempio come sfondo di un sito o per un montaggio in cui aggiungerai la tua musica, aggiungi "generate_audio": false alla richiesta.

Per inquadrare l’output, tuttavia, l’API conosce solo il rapporto (aspect_ratio) e la definizione (resolution): il riferimento API non fornisce alcun parametro per la dimensione in pixel. Nell’image-to-video, il rapporto di output segue sempre quello dell’immagine sorgente.

Punti chiave

  • L’endpoint è POST /v1/videos/generations, con grok-imagine-video-1.5, la sua versione -lite o grok-imagine-video
  • La durata va da 1 a 15 secondi (8 di default), la risoluzione da 480p a 1080p (max 720p con grok-imagine-video)
  • Il prezzo si conta per secondo generato: $0.020 (-lite), $0.050 (grok-imagine-video) o $0.080 (grok-imagine-video-1.5)
  • La generazione è asincrona: ricevi un request_id da interrogare successivamente
  • Sono disponibili nove rapporti di aspetto per adattarsi a tutti i formati
  • Una traccia audio è generata di default; "generate_audio": false produce un video muto