Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formati immagine: URL e Base64

Lezione 1 di 12 Aggiornata il 3 novembre 2026 Principiante
In questa pagina
  1. Invio di immagini a Grok
  2. URL diretto
  3. Codificato in Base64 (Data URI)
  4. Differenze chiave tra URL e Base64
  5. Combinazione di testo e immagini
  6. Punti chiave

Aggiornato il 3 novembre 2026. Con le Responses API, gli oggetti input_image e input_text vanno inseriti nel campo content di un messaggio {"role": "user", ...}, non direttamente in input. L’esempio Python precedente chiamava client.responses.create() sul client xai-sdk, che non dispone di questo metodo, e scriveva la chiave API nel codice: ora utilizza user(...) e image(...) dall’SDK, con la chiave letta dalle variabili d’ambiente. Aggiunto l’avviso di xAI sull’archiviazione della cronologia. Codice verificato con xai-sdk 1.21.0. Fonte: Image Understanding.

Invio di immagini a Grok

Grok mentre analizza un'immagine 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.

2
Formati supportati
20 MiB
Dimensione massima per immagine
JPG/PNG
Formati accettati
Illimitato
Numero di immagini

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/JPEG
  • data: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_image nel content di un messaggio; le Chat Completions usano parti image_url; l’SDK xAI usa image() all’interno di user()
  • Preferisci l’URL per le immagini pubbliche e il Base64 per i file locali