Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato del contenuto: stringa semplice e array di oggetti

Lezione 3 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Due formati per il campo content
  2. Formato stringa: il caso più comune
  3. Formato array: contenuti multimediali
  4. Quando usare quale formato?
  5. Vincoli tecnici per le immagini
  6. Punti chiave

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à text
  • image_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 content accetta 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