Formati immagine: URL e Base64
In questa pagina
Aggiornato il 3 novembre 2026. Con le Responses API, gli oggetti
input_imageeinput_textvanno inseriti nel campocontentdi un messaggio{"role": "user", ...}, non direttamente ininput. L’esempio Python precedente chiamavaclient.responses.create()sul clientxai-sdk, che non dispone di questo metodo, e scriveva la chiave API nel codice: ora utilizzauser(...)eimage(...)dall’SDK, con la chiave letta dalle variabili d’ambiente. Aggiunto l’avviso di xAI sull’archiviazione della cronologia. Codice verificato conxai-sdk1.21.0. Fonte: Image Understanding.
Invio di immagini a Grok
I modelli Grok dalla versione 4.5 in poi includono capacità visive. Puoi inviare una o più immagini nelle tue richieste API e il modello le analizzerà per rispondere alle tue domande. Questo processo è chiamato comprensione delle immagini o visione multimodale.
Prima di approfondire i casi d’uso, è essenziale padroneggiare i due formati di invio immagini supportati dall’API xAI.
URL diretto
Il metodo più semplice consiste nel fornire l’URL pubblico di un’immagine. Il modello la scaricherà e la analizzerà automaticamente.
Con le Responses API (endpoint principale):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Descrivi questa immagine in dettaglio."
}
]
}
]
}
xAI raccomanda di non archiviare la cronologia delle richieste e delle risposte sui propri server quando si inviano immagini, altrimenti la richiesta potrebbe fallire: con le Responses API, passa "store": false.
Con le Chat Completions API (legacy, compatibile con OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Descrivi questa immagine in dettaglio."
}
]
}
]
}
L’URL deve puntare a un file immagine pubblicamente accessibile. Se l’immagine è protetta da autenticazione o si trova su un CDN privato, utilizza invece il formato Base64.
Codificato in Base64 (Data URI)
Il secondo formato prevede la codifica dell’immagine direttamente nella richiesta come stringa Base64, preceduta da un prefisso MIME. Questo è il metodo ideale quando lavori con immagini locali, screenshot o file generati dinamicamente.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Il prefisso data:image/jpeg;base64, indica al modello il tipo MIME dell’immagine. Adattalo in base al formato:
data:image/jpeg;base64,per file JPG/JPEGdata:image/png;base64,per file PNG
Codifica di un’immagine in Python
import base64
with open("photo.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
image_url = f"data:image/jpeg;base64,{image_data}"
Codifica in JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Differenze chiave tra URL e Base64
| Criterio | URL | Base64 |
|---|---|---|
| Dimensione richiesta | Leggera (solo l'URL) | Pesante (+33% rispetto al file originale) |
| Accessibilità | Richiede immagine pubblica | Funziona con qualsiasi file locale |
| Latenza | Download dal server | Dati direttamente nella richiesta |
| Caso d'uso tipico | Immagini web, CDN, cloud storage | File locali, screenshot, upload |
Combinazione di testo e immagini
Il campo content di un messaggio accetta un array misto di oggetti input_image e input_text, in qualsiasi ordine: puoi alternare liberamente testo e immagini. Con l’SDK nativo xAI, lo stesso messaggio viene costruito con user(), che accetta testo e immagini creati da image() in sequenza:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # chiave letta da XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Confronta queste due foto:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Quali sono le principali differenze?",
)
)
response = chat.sample()
print(response.content)
image() accetta un URL pubblico o un Data URI Base64.
Punti chiave
- Sono supportati due formati immagine: URL diretto e Base64 (Data URI)
- I formati accettati sono solo JPG, JPEG e PNG
- Ogni immagine non deve superare i 20 MiB
- Il numero di immagini per richiesta è illimitato
- Le Responses API inseriscono
input_imagenelcontentdi un messaggio; le Chat Completions usano partiimage_url; l’SDK xAI usaimage()all’interno diuser() - Preferisci l’URL per le immagini pubbliche e il Base64 per i file locali