Formato dei contenuti
In questa pagina
I due formati di input di Grok
Quando invii un messaggio a Grok, il campo content di ogni messaggio può assumere una di due forme distinte. Comprendere questa differenza è fondamentale perché determina ciò che puoi inviare al modello: solo testo o una combinazione di testo e immagini.
Semplice stringa di testo
La forma più diretta: il contenuto è una semplice stringa. Utilizzerai questo formato per la maggior parte delle tue interazioni basate sul testo.
{
"role": "user",
"content": "Explain the advantages of the Rust language compared to C++"
}
Questo formato funziona per tutte le attività puramente testuali: domande, istruzioni, fornitura di dati o richieste di generazione. Usalo quando non hai bisogno di includere elementi visivi.
Array di oggetti tipizzati
Per le richieste multimodali (testo + immagini), Grok accetta un array di oggetti in cui ogni elemento include un campo type che ne indica la natura.
Formato Chat Completions (Endpoint legacy)
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this user interface and suggest improvements"},
{"type": "image_url", "image_url": {"url": "https://exemple.com/screenshot.png", "detail": "high"}}
]
}
Formato Responses (Endpoint principale)
{
"input": [
{"type": "input_text", "text": "Analyze this chart and extract the main trends"},
{"type": "input_image", "image_url": "https://exemple.com/graphique.png"}
]
}
Nota la differenza di denominazione tra i due endpoint: text e image_url per Chat Completions, input_text e input_image per Responses.
Combinare testo e immagini
L’array di oggetti ti permette di mescolare liberamente testo e immagini in qualsiasi ordine. Puoi inviare più immagini nella stessa richiesta, con testo prima, dopo o tra di esse.
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two interface mockups:"},
{"type": "image_url", "image_url": {"url": "https://exemple.com/maquette-v1.png"}},
{"type": "text", "text": "Version 1 above, version 2 below:"},
{"type": "image_url", "image_url": {"url": "https://exemple.com/maquette-v2.png"}},
{"type": "text", "text": "Identify the main differences and recommend the best version."}
]
}
Fonti immagine accettate
Grok accetta le immagini in due modi:
- URL diretto: un link HTTPS all’immagine ospitata online
- Codificato in Base64: l’immagine incorporata direttamente nella richiesta come data URI
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
Il formato Base64 è utile quando le tue immagini non sono ospitate online (screenshot locali, immagini generate dalla tua applicazione).
Il parametro detail per le immagini
Ogni immagine può ricevere un parametro detail che controlla il livello di analisi:
- auto: il modello sceglie automaticamente (comportamento predefinito)
- low: analisi rapida ed economica, consuma meno token
- high: analisi dettagliata, consuma più token ma cattura i fini dettagli
{"type": "image_url", "image_url": {"url": "https://...", "detail": "low"}}
Usa low per compiti semplici (classificazione, descrizione generale) e high per analisi precise (OCR, rilevamento di dettagli, lettura di grafici).
Vincoli tecnici
Tieni a mente questi limiti quando lavori con le immagini:
- Dimensione massima: 20 MB per immagine
- Formati accettati: solo JPG, JPEG, PNG
- Nessun limite sul numero di immagini per richiesta
- Modelli compatibili: grok-4.5 e superiori
- Le immagini consumano tra 256 e 1.792 token a seconda delle loro dimensioni e del livello di dettaglio
Esercitazione pratica
Testa entrambi i formati con un compito semplice:
Formato testo semplice:
{"role": "user", "content": "What are the 5 fundamental principles of UX design?"}
Formato array (solo testo, ma strutturato):
{
"role": "user",
"content": [
{"type": "text", "text": "Context: I'm designing a mobile food delivery application."},
{"type": "text", "text": "Question: what are the 5 most important UX principles for this type of application?"}
]
}
Anche senza un’immagine, il formato ad array ti permette di separare chiaramente il contesto dalla domanda, il che può migliorare la pertinenza della risposta.
Punti chiave
- Il contenuto può essere una semplice stringa (testo normale) o un array di oggetti (multimodale)
- Il formato ad array ti permette di mescolare testo e immagini in qualsiasi ordine
- Esistono due formati di denominazione a seconda dell’endpoint: Chat Completions vs Responses
- Il parametro
detailcontrolla la profondità dell’analisi dell’immagine (low, auto, high) - Le immagini consumano token: adatta il livello di dettaglio alle tue esigenze
- Il formato Base64 ti permette di inviare immagini senza doverle ospitare online