Endpoint /v1/videos/generations: La tua prima video
In questa pagina
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-liteegrok-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 parametrosizepresentato 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.
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 economicagrok-imagine-video-1.5-lite, raccomandata da xAI per video semplici, oppuregrok-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),720po1080p: quest’ultima è resa nativamente dagrok-imagine-video-1.5nel text-to-video e image-to-video, ottenuta tramite upsampling da 720p sulla versione-lite, e assente ingrok-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, congrok-imagine-video-1.5, la sua versione-liteogrok-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_idda interrogare successivamente - Sono disponibili nove rapporti di aspetto per adattarsi a tutti i formati
- Una traccia audio è generata di default;
"generate_audio": falseproduce un video muto