Immagini e video in batch
In questa pagina
Aggiornato il 2 novembre 2026 sulla base della documentazione xAI: lo sconto batch è del 20% sui modelli di testo idonei (non del 50%), gli esempi seguono l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non utilizza il formato OpenAI, quindi l’SDK OpenAI non si applica) e le API Responses hanno la precedenza sulle Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Generazione multimodale in blocco
L’API Batch non si limita al testo. Puoi inviare richieste per la generazione e la modifica di immagini, oltre che per la generazione, la modifica e l’estensione di video. Questa capacità apre la strada a pipeline multimodali complete: scrivi descrizioni e produci i relativi contenuti visivi in un’unica operazione.
Generazione di immagini in batch
L’endpoint /v1/images/generations funziona in batch esattamente come in modalità sincrona. Seleziona il formato con aspect_ratio, la definizione con resolution ("1k", "1.5k" o "2k") e il numero di immagini con n:
{"custom_id": "img-001", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Minimalist logo for a fintech startup, white background, vector style", "n": 1, "aspect_ratio": "1:1", "resolution": "1k"}}
{"custom_id": "img-002", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Isometric illustration of a datacenter", "n": 1, "aspect_ratio": "16:9", "resolution": "1k"}}
Modifica di immagini in batch
L’endpoint /v1/images/edits modifica un’immagine esistente, passata all’interno di un oggetto image: può essere un url (indirizzo pubblico o dati codificati in base64) o il file_id di un file caricato.
{"custom_id": "edit-001", "method": "POST", "url": "/v1/images/edits", "body": {"model": "grok-imagine-image-2.0", "prompt": "Replace the background with a solid white background", "image": {"url": "https://example.com/photo.jpg"}}}
In modalità batch, la modifica aiuta a elaborare un catalogo: armonizza gli sfondi, aggiungi un elemento o applica lo stesso ritocco a centinaia di contenuti visivi.
Generazione di video in batch
L’endpoint /v1/videos/generations (o /v1/videos) genera video da 1 a 15 secondi (duration, 8 di default), in 480p, 720p o 1080p:
{"custom_id": "vid-001", "method": "POST", "url": "/v1/videos/generations", "body": {"model": "grok-imagine-video-1.5", "prompt": "Smooth animation of a bar chart growing progressively", "duration": 8, "resolution": "720p"}}
L’elaborazione video è più onerosa rispetto a testo o immagini, quindi queste richieste potrebbero richiedere più tempo all’interno del batch.
Modifica ed estensione video
L’endpoint /v1/videos/edits modifica un video esistente, mentre /v1/videos/extensions lo estende aggiungendo un segmento da 2 a 10 secondi. Passa il video sorgente in un oggetto video (URL di un file .mp4 o file_id):
{"custom_id": "vid-edit-001", "method": "POST", "url": "/v1/videos/edits", "body": {"model": "grok-imagine-video", "prompt": "Slow down the scene", "video": {"url": "https://example.com/clip.mp4"}}}
{"custom_id": "vid-ext-001", "method": "POST", "url": "/v1/videos/extensions", "body": {"model": "grok-imagine-video", "prompt": "The camera slowly pulls back and reveals a sunset", "video": {"url": "https://example.com/clip.mp4"}, "duration": 6}}
Utilizzo dell’SDK Python
L’SDK prepara queste richieste con metodi dedicati, per poi aggiungerle al batch come le richieste di testo:
from xai_sdk import Client
client = Client()
batch = client.batch.create(batch_name="catalog_visuals")
requetes = [
client.image.prepare(
prompt="Product shot of wireless headphones, dark background, studio lighting",
model="grok-imagine-image-2.0",
batch_request_id="prod-42-img",
),
client.video.prepare(
prompt="The headphones rotate slowly on a turntable, dramatic lighting",
model="grok-imagine-video-1.5",
batch_request_id="prod-42-vid",
),
]
client.batch.add(batch_id=batch.batch_id, batch_requests=requetes)
Prezzi dei contenuti multimodali
Punto importante: lo sconto batch si applica solo ai modelli di testo idonei. Immagini e video sono fatturati alla tariffa standard, anche in modalità batch: al 2 novembre 2026, 0,04 $ per immagine con grok-imagine-image-2.0 (0,02 $ con grok-imagine-image) e 0,08 $ al secondo di video con grok-imagine-video-1.5 (0,02 $ nella versione -lite, 0,05 $ con grok-imagine-video).
Il vantaggio dei batch per i contenuti multimodali non è economico, ma operativo: invia centinaia di generazioni in un’unica operazione, senza dover gestire altrettante chiamate o rischiare di superare i limiti di frequenza (rate limits).
Scadenza degli URL dei risultati
I risultati di immagini e video sono forniti come URL firmati che scadono dopo un’ora. Questo è un vincolo critico: scarica i file non appena recuperi i risultati.
import mimetypes
import requests
def telecharger_medias(resultats, dossier):
"""Downloads images and videos as soon as results are retrieved."""
for r in resultats:
reponse = r.proto.response
if reponse.HasField("image_response"):
url = r.image_response.url
elif reponse.HasField("video_response"):
url = r.video_response.url
else:
continue # text result
fichier = requests.get(url, timeout=120)
fichier.raise_for_status()
type_mime = fichier.headers.get("Content-Type", "").split(";")[0]
extension = mimetypes.guess_extension(type_mime) or ".bin"
with open(f"{dossier}/{r.batch_request_id}{extension}", "wb") as f:
f.write(fichier.content)
Non conservare mai gli URL firmati per un uso successivo: salva i file nel tuo storage (S3, GCS, disco locale).
Pipeline multimodale mista
Un caso d’uso concreto: produrre schede prodotto complete, testo e visual, nello stesso batch:
{"custom_id": "prod-42-desc", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Write a marketing description for a high-end wireless headphone.", "max_output_tokens": 300}}
{"custom_id": "prod-42-img", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Product shot of premium wireless headphones, dark gradient background, studio lighting"}}
Un prefisso comune negli identificatori (prod-42-desc, prod-42-img) facilita il raggruppamento dei risultati testuali e visivi per lo stesso prodotto.
Punti chiave
- Immagini (generazione, modifica) e video (generazione, modifica, estensione) funzionano in batch
- I parametri corrispondono all’API:
aspect_ratio,resolution, oggettiimageevideo - Immagini e video restano alle tariffe standard, senza sconti batch
- Gli URL firmati dei risultati scadono dopo un’ora: scaricali immediatamente
- Un prefisso comune negli identificatori raggruppa i risultati per lo stesso prodotto