Formato del contenuto: stringa semplice e array di oggetti
In questa pagina
Due formati per il campo content
Il campo content di ogni messaggio accetta due formati diversi nell’API Chat Completions di xAI. La scelta dipende da ciò che invii al modello: testo semplice o contenuti multimediali (testo + immagini).
Formato stringa: il caso più comune
Per i messaggi puramente testuali, il campo content è una semplice stringa:
{
"role": "user",
"content": "Spiega come funziona un trasformatore."
}
Questo è il formato che utilizzerai nella stragrande maggioranza dei casi. È semplice, leggibile e sufficiente per tutte le interazioni testuali con Grok.
Per il messaggio system, si usa quasi sempre il formato stringa:
{
"role": "system",
"content": "Sei un esperto di architettura software. Rispondi in inglese con esempi di codice Python."
}
Formato array: contenuti multimediali
Quando devi inviare immagini insieme al testo, il campo content diventa un array di oggetti tipizzati. Ogni oggetto possiede un campo type che ne indica la natura.
{
"role": "user",
"content": [
{
"type": "text",
"text": "Cosa mostra questa immagine?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Tipi di oggetti disponibili
L’array di contenuti accetta due tipi di oggetti:
text: un blocco di testo con la proprietàtextimage_url: un riferimento a un’immagine con la proprietàimage_url
Puoi combinare quanti oggetti desideri in un singolo messaggio. Ad esempio, per chiedere al modello di confrontare due immagini:
{
"role": "user",
"content": [
{"type": "text", "text": "Confronta questi due diagrammi di architettura."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
Il parametro detail per le immagini
Ogni oggetto image_url accetta un parametro opzionale detail che controlla la risoluzione dell’analisi:
auto: il modello sceglie automaticamente il livello di dettaglio (valore predefinito)low: analisi rapida ed economica, sufficiente per immagini semplici (icone, diagrammi di base)high: analisi dettagliata, consigliata per immagini complesse (documenti, fotografie, interfacce)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
La scelta del livello di dettaglio impatta direttamente sul numero di token consumati e, di conseguenza, sul costo della richiesta.
Quando usare quale formato?
La regola è semplice:
- Solo testo → formato stringa (più semplice, più leggibile)
- Testo + immagini → formato array (obbligatorio per il multimodale)
- Solo immagini → formato array contenente esclusivamente oggetti
image_url
Un formato array con un singolo oggetto text è funzionalmente equivalente al formato stringa, ma inutilmente verboso:
// Equivalente ma inutilmente complesso
{"content": [{"type": "text", "text": "Ciao"}]}
// Preferisci questa forma
{"content": "Ciao"}
Vincoli tecnici per le immagini
Prima di inviare immagini all’API xAI, tieni a mente questi limiti:
- Dimensione massima: 20 MiB per immagine
- Formati accettati: solo JPG, JPEG, PNG (niente GIF, WebP o SVG)
- Quantità: nessun limite al numero di immagini per richiesta
- Modelli compatibili: solo grok-4.5 e versioni successive
Le immagini possono essere fornite tramite un URL pubblico o codificate in base64 direttamente nell’URL (formato data:image/jpeg;base64,...).
Punti chiave
- Il campo
contentaccetta una semplice stringa (testo) o un array di oggetti (multimodale) - Il formato array utilizza oggetti con un campo
type:"text"o"image_url" - Il parametro
detail(auto,low,high) controlla la risoluzione dell’analisi per le immagini - Le immagini sono limitate a 20 MiB in formato JPG/PNG e richiedono grok-4.5 o versioni successive
- Usa il formato stringa quando invii solo testo: è più leggibile e semplice