Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Immagini e video in batch

Lezione 9 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Generazione multimodale in blocco
  2. Generazione di immagini in batch
  3. Modifica di immagini in batch
  4. Generazione di video in batch
  5. Modifica ed estensione video
  6. Utilizzo dell’SDK Python
  7. Prezzi dei contenuti multimodali
  8. Scadenza degli URL dei risultati
  9. Pipeline multimodale mista
  10. Punti chiave

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, oggetti image e video
  • 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