Grok Imagine Video API: da testo a video con Python

L'API di Grok Imagine Video è asincrona: invii un prompt per creare un job, interroghi l'ID del job finché non è finito e poi scarichi l'MP4. Il modello attuale è grok-imagine-video-1.5. Il 24 ottobre 2026 la nostra clip di 6 secondi in 720p era pronta 46 secondi dopo la richiesta, e aveva una traccia audio.

Qui sotto trovi lo script che gira così com'è, i parametri che decidono il risultato, quanto costa e quanto dura una clip, e gli errori in cui ti imbatterai.

Risposta rapida

• Modello: grok-imagine-video-1.5. xAI dice che 1.5 è uscito dall'anteprima ed è disponibile in generale dal 16 giugno 2026 (xAI).
• Impostazioni: duration da 4 a 15 secondi, resolution "720p" e un ratio come "16:9".
• Costo: 0,14 USD al secondo in 720p secondo il listino xAI, quindi 0,84 USD per una clip di 6 secondi (pagina dei modelli xAI, controllata il 24 ottobre 2026).
• Tempo: il nostro job da 6 secondi in 720p ha impiegato 46 secondi. Interroga lo stesso ID del task e scarica il file entro un'ora.

Come funziona l'API di Grok Imagine Video?

Il job ha tre passaggi: creare, interrogare, scaricare (guida alla generazione video di xAI, controllata il 24 ottobre 2026).

Nell'API di xAI invii una POST a https://api.x.ai/v1/videos/generations con l'ID del modello e il prompt, e ricevi un request_id. Poi interroghi https://api.x.ai/v1/videos/{request_id} con GET finché il job è done, e leggi video.url (la stessa guida).

xAI consiglia grok-imagine-video-1.5-lite per i video semplici e grok-imagine-video-1.5 quando servono referenze, voci, fotogrammi fissati o 1080p nativo (panoramica video, controllata il 24 ottobre 2026). Per le immagini ferme, la guida all'API immagini di Grok Imagine copre i tre modelli immagine di xAI; per confrontare Grok con altre API video, leggi il nostro confronto tra modelli video.

OmniaKey vende l'accesso API a Grok Imagine Video 1.5, quindi abbiamo eseguito l'esempio tramite OmniaKey. Le chiamate sono POST https://api.omniakey.com/v1/media/tasks con un header Idempotency-Key, che risponde 202 con un id, e GET /v1/media/tasks/{id} per lo stato (panoramica media di OmniaKey, controllata il 24 ottobre 2026). Lo stesso giro crea, interroga, scarica vale per gli altri modelli video nella documentazione dell'API video: Kling 3.0, Seedance, Wan 3.0, MiniMax H3 e HappyHorse. Tutti i prezzi qui sotto sono quelli di xAI.

I nomi dei campi xAI vengono dalla referenza dell'API Videos, quelli di OmniaKey dalla documentazione dell'API video, entrambe controllate il 24 ottobre 2026.

Quali parametri puoi impostare?

Il prompt e tre impostazioni decidono cosa ottieni.

• duration è obbligatorio su OmniaKey e decide il prezzo (documentazione video di OmniaKey). Il minimo di OmniaKey per questo modello è 4 secondi, il massimo di xAI è 15 (guida alla generazione video), quindi resta tra 4 e 15.
• resolution: invia "720p" in minuscolo. OmniaKey serve il video Grok fino a 720p (panoramica media di OmniaKey). L'API di xAI aggiunge 480p come impostazione predefinita e 1080p nativo (guida alla generazione).
• ratio accetta nove valori: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 e 5:2, con 16:9 come predefinito (guida alla generazione video). Noi abbiamo usato 16:9.
• n deve essere 1 (documentazione video di OmniaKey).
• Il prompt: descrivi l'inquadratura, la luce e il movimento di camera, poi aggiungi una riga Sound:. Tutto ciò che nomini lì può comparire nell'immagine: la nostra riga audio citava un cucchiaino, e nel fotogramma sono comparsi un cucchiaino e una mano.

Come trasformi un prompt di testo in video con Python?

Installa requests, metti la chiave in OMNIAKEY_API_KEY e lancia lo script.

pip install requests
export OMNIAKEY_API_KEY="your-key"

Questo è lo script che abbiamo eseguito, senza modifiche:

import os
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

PROMPT = (
    "Close-up of a white ceramic coffee cup on a wooden café table by a window, "
    "morning sunlight, steam curling up from the coffee, the camera slowly pushes in, "
    "shallow depth of field. Sound: quiet café chatter and a spoon clinking on a saucer."
)

# 1. Crea il job. Riusa la stessa Idempotency-Key solo per ripetere questa identica richiesta.
job = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "grok-imagine-video-1.5",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": PROMPT},
        "parameters": {"duration": 6, "resolution": "720p", "ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
task = job.json()
print("task:", task["id"], task["status"])

# 2. Interroga il job finché non è finito. Un job lento non è fallito: continua con lo stesso id.
while True:
    task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] not in ("queued", "processing"):
        break
    time.sleep(5)

if task["status"] != "succeeded":
    raise SystemExit(f"job ended {task['status']}: {task.get('error')}")

# 3. Scarica subito: l'URL firmato scade in circa un'ora.
asset = task["assets"][0]
with open("coffee.mp4", "wb") as f:
    f.write(requests.get(asset["url"], timeout=120).content)
print("saved coffee.mp4", asset["mime_type"], asset["byte_size"], "bytes")

L'ultima riga che ha stampato il 24 ottobre 2026:

saved coffee.mp4 video/mp4 2659230 bytes

La prima riga dello script stampa l'ID del task e lo stato. Conserva quell'ID: è così che ritrovi il job se lo script si ferma.

Un job da 6 secondi in 720p è tornato così:

La clip segue il prompt: una tazza di ceramica bianca con caffè nero su un piattino bianco, su un tavolo di legno vicino alla finestra, con il vapore che sale e il bar sfocato dietro. La camera avanza a ritmo costante e la tazza passa da circa un terzo della larghezza del fotogramma a circa la metà. A 4,5 secondi un cucchiaino entra da destra. L'audio è una traccia tranquilla con un picco netto a 4,8 secondi, proprio quando il cucchiaino tocca il piattino.

Quanto costa una clip e quanto tempo richiede?

xAI fattura il video al secondo, e la tariffa dipende dal modello e dalla risoluzione. La pagina dei modelli (controllata il 24 ottobre 2026) dettaglia il prezzo per risoluzione, e i 0,080 USD al secondo forfettari della pagina dei prezzi sono la tariffa 480p.

A questi prezzi di listino:

• 6 secondi con 1.5 in 720p: 6 × 0,14 = 0,84 USD.
• 8 secondi, la durata predefinita, con 1.5 in 480p: 8 × 0,08 = 0,64 USD.
• 15 secondi con 1.5 in 1080p: 15 × 0,25 = 3,75 USD.
• 6 secondi con 1.5 Lite in 720p: 6 × 0,03 = 0,18 USD.

xAI pubblica solo tariffe video al secondo (pagina dei prezzi, controllata il 24 ottobre 2026).

Su OmniaKey l'addebito è la durata richiesta moltiplicata per la tariffa al secondo, tolto dal saldo alla creazione del job e rimborsato automaticamente se il job fallisce (documentazione video di OmniaKey, controllata il 24 ottobre 2026). Abbiamo chiesto 6 secondi, ricevuto un file da 6,04 secondi e pagato 6 secondi. Le tariffe attuali sono sulla pagina di Grok Imagine Video 1.5.

Il nostro job ha impiegato 46 secondi dalla richiesta a succeeded. xAI dice che la generazione «di solito richiede fino a qualche minuto», e il suo SDK aspetta fino a 10 minuti (guida alla generazione). Interroga ogni pochi secondi. Se metti un limite di tempo al ciclo, lascialo largo, e quando scade rileggi il job dal suo ID invece di inviare una nuova richiesta.

Il link firmato dura circa un'ora, e il nostro è scaduto esattamente un'ora dopo la fine del job. Il record del task resta 24 ore, quindi puoi interrogarlo di nuovo per ottenere un link fresco (panoramica media di OmniaKey, controllata il 24 ottobre 2026).

A quali errori vai incontro?

La maggior parte degli errori torna subito, prima che il job esista, quindi non costa nulla. Un job che fallisce più tardi finisce come failed e viene rimborsato. La documentazione media di OmniaKey (controllata il 24 ottobre 2026) elenca tra gli altri:

I primi due li abbiamo provocati di proposito il 24 ottobre 2026. Senza l'header la risposta è HTTP 400:

{"error":{"code":"missing_idempotency_key","message":"Idempotency-Key is required and must be at most 255 characters"}}

Riusando la chiave del job con un prompt diverso la risposta è HTTP 409:

{"error":{"code":"idempotency_key_reused","message":"Idempotency-Key was already used with a different request"}}

• Tratta un job lento come ancora in corso. Continua a interrogare lo stesso ID del task; rimandare la richiesta con una nuova Idempotency-Key avvia un secondo job e lo fattura.
• Una richiesta ripetuta risponde 200 con il task originale e senza lista assets, ed è per questo che lo script recupera prima il task e poi legge assets.

Domande frequenti

L'API di Grok Imagine Video è gratuita?

No. xAI pubblica solo tariffe al secondo, e la più economica è 1.5 Lite a 0,02 USD al secondo in 480p (pagina dei modelli, controllata il 24 ottobre 2026).

Quanto può durare un video di Grok Imagine?

Da 1 a 15 secondi nell'API di xAI, con 8 secondi come predefinito (guida alla generazione video). Tramite OmniaKey usa da 4 a 15 secondi: il minimo di OmniaKey per questo modello è 4 (documentazione video di OmniaKey, controllata il 24 ottobre 2026) e il massimo di xAI è 15.

Grok Imagine Video produce audio?

Sì, una traccia audio come predefinita, con effetti, ambiente e dialoghi generati insieme all'immagine (guida alla generazione video; annuncio di xAI). La nostra aveva una traccia AAC stereo. L'API di xAI accetta generate_audio: false per una clip muta; per togliere la traccia da un file scaricato, esegui:

ffmpeg -i coffee.mp4 -an -c:v copy coffee-silent.mp4

Grok Imagine può trasformare un'immagine in video?

Sì, nell'API di xAI: passa l'immagine come image (un URL pubblico, un data URI base64 o un file_id della Files API; JPEG, PNG o WebP), diventa il primo fotogramma, il prompt è facoltativo e la clip mantiene le proporzioni dell'immagine (guida da immagine a video; referenza dell'API Videos). Aggiungeremo qui un esempio da immagine a video tramite OmniaKey quando l'avremo verificato da capo a fondo.

Qual è la differenza tra Grok Imagine Video 1.5 e 1.5 Lite?

Lite è il più economico al secondo, fa testo a video e immagine a video con voce sincronizzata sulle labbra, arriva a 1080p salendo da 720p e non ha immagini di riferimento, voci di riferimento né fotogrammi chiave (panoramica video; pagina del modello Lite). Gli esempi qui usano 1.5, che su OmniaKey chiami come Grok Imagine Video 1.5.

grok-imagine-video-1.5-preview è ancora un ID di modello valido?

xAI lo elenca ancora come alias, ma 1.5 è uscito dall'anteprima ed è disponibile in generale dal 16 giugno 2026 (pagina del modello; annuncio di xAI). Usa grok-imagine-video-1.5.