Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Codificare e inviare immagini in Base64

Lezione 5 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Perché usare il Base64?
  2. Quando usare URL o Base64
  3. Codificare un’immagine in Base64
  4. Formato Data URI
  5. Esempio completo
  6. Codificare immagini da altre fonti
  7. Ottimizzare le dimensioni prima della codifica
  8. Limiti da conoscere
  9. Punti chiave

Perché usare il Base64?

Nella lezione precedente hai imparato a inviare immagini tramite URL. Tuttavia, la maggior parte delle immagini elaborate in contesti aziendali non dispone di un URL: una fattura appena arrivata via email, uno screenshot generato da un test automatizzato o una foto scattata da un operatore su una linea di produzione. Pubblicare questi file su un server accessibile via Internet solo per analizzarli sarebbe assurdo e spesso vietato.

È qui che entra in gioco la codifica Base64. Trasforma i dati binari di un’immagine in una stringa di testo che puoi includere direttamente nella tua richiesta API, senza bisogno di un URL esterno o di un hosting intermedio.

Quando usare URL o Base64

CriterioURLBase64
Immagini già ospitateIdealeInutile
Immagini localiNon adattoIdeale
Immagini generate dinamicamenteNon adattoIdeale
Latenza di reteDipende dal serverNessuna (incorporata)
Dimensione della richiestaLeggeraPiù pesante (~33%)
Sicurezza/privacyURL pubblicoDati dentro la richiesta

La regola è semplice: se l’immagine è accessibile tramite un URL stabile, usa l’URL. Altrimenti, usa il Base64.

Codificare un’immagine in Base64

Non sono necessarie dipendenze esterne; Python fornisce il modulo base64 nella sua libreria standard:

import base64

def encode_image(file_path):
    """Codifica un file immagine in una stringa Base64."""
    with open(file_path, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Codifica un'immagine locale
image_b64 = encode_image("captures/screenshot.png")
print(f"Lunghezza stringa Base64: {len(image_b64)} caratteri")

La modalità "rb" durante l’apertura del file non è opzionale: leggere un’immagine in modalità testo genererà un errore di decodifica. Aspettati stringhe lunghe: la codifica aumenta le dimensioni di circa il 33% rispetto al file originale, quindi un’immagine da 1 MB produce circa 1,33 MB di testo.

Formato Data URI

La stringa grezza non basta: l’API deve conoscere il formato dell’immagine. Devi quindi presentarla come data URI, che antepone i dati al loro tipo MIME:

data:image/{format};base64,{base64_data}

I quattro prefissi utilizzabili corrispondono ai formati supportati:

  • data:image/jpeg;base64,...
  • data:image/png;base64,...
  • data:image/gif;base64,...
  • data:image/webp;base64,...

Dichiarare un PNG come image/jpeg causa un errore di elaborazione; da qui la necessità della funzione di rilevamento nell’esempio seguente.

Esempio completo

Ecco l’intera catena, dalla lettura del file locale alla risposta del modello:

import base64
import os
from mistralai.client import Mistral

def encode_image(chemin):
    """Codifica un'immagine locale in Base64."""
    with open(chemin, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Determina il tipo MIME
def obtenir_mime(chemin):
    """Restituisce il tipo MIME in base all'estensione."""
    extensions = {
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".png": "image/png",
        ".gif": "image/gif",
        ".webp": "image/webp"
    }
    ext = os.path.splitext(chemin)[1].lower()
    return extensions.get(ext, "image/jpeg")

# Prepara l'immagine
chemin_image = "documents/facture-2024.png"
image_b64 = encode_image(chemin_image)
mime_type = obtenir_mime(chemin_image)
data_uri = f"data:{mime_type};base64,{image_b64}"

# Chiama l'API
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Estrai tutte le informazioni da questa fattura."},
                {"type": "image_url", "image_url": data_uri}
            ]
        }
    ]
)

print(response.choices[0].message.content)

Punto fondamentale: il campo si chiama sempre image_url, anche quando contiene un data URI. La struttura del messaggio non cambia di una virgola rispetto alla Lezione 4; cambia solo il valore.

Codificare immagini da altre fonti

Un file su disco è solo uno dei tanti casi. Se la tua immagine esiste già in memoria, come oggetto Pillow derivante da un’acquisizione o da un passaggio di elaborazione, scriverla su disco per leggerla immediatamente dopo sarebbe un giro inutile: un buffer di memoria funziona perfettamente:

import base64
from io import BytesIO
from PIL import Image

def pil_to_base64(pil_image):
    """Converte un'immagine Pillow in un data URI Base64."""
    buffer = BytesIO()
    pil_image.save(buffer, format="PNG")
    b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
    return f"data:image/png;base64,{b64}"

# Esempio con un'immagine Pillow
img = Image.open("capture.png")
data_uri = pil_to_base64(img)

La stessa logica si applica a un’immagine recuperata via HTTP che non vuoi archiviare, ad esempio perché proviene da un link a breve durata:

import base64
import requests

def url_to_base64(url):
    """Scarica un'immagine e la converte in un data URI."""
    response = requests.get(url, timeout=10)
    response.raise_for_status()
    content_type = response.headers.get("Content-Type", "image/jpeg")
    b64 = base64.standard_b64encode(response.content).decode("utf-8")
    return f"data:{content_type};base64,{b64}"

data_uri = url_to_base64("https://example.com/photo.jpg")

Ottimizzare le dimensioni prima della codifica

Una foto scattata con uno smartphone oggi pesa dai 4 agli 8 MB, che diventano quasi 10 MB una volta codificata. L’API la ridimensionerà comunque, come hai visto nella Lezione 2: pagheresti il trasferimento per nulla. Quindi, ridimensiona sempre prima di codificare.

from PIL import Image
from io import BytesIO
import base64

def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
    """Ridimensiona, comprime e codifica un'immagine."""
    img = Image.open(chemin)

    # Ridimensiona se necessario
    if max(img.size) > taille_max:
        img.thumbnail((taille_max, taille_max))

    # Converti in JPEG per ridurre le dimensioni
    buffer = BytesIO()
    img.convert("RGB").save(buffer, format="JPEG", quality=qualite)

    b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
    taille_ko = len(buffer.getvalue()) / 1024
    print(f"Immagine codificata: {taille_ko:.0f} KB")

    return f"data:image/jpeg;base64,{b64}"

data_uri = preparer_et_encoder("photo_haute_resolution.png")

Visualizzare la dimensione finale non è solo decorativo: tienila durante i tuoi test, poiché ti dirà immediatamente se la tua pipeline sta inviando 80 KB o 8 MB a ogni chiamata.

Limiti da conoscere

Tre vincoli accompagnano il Base64. L’immagine codificata si aggiunge al corpo della richiesta HTTP, quindi oltre i 10 MB rischi i timeout. La codifica carica inoltre l’intera immagine in memoria: per l’elaborazione in batch, gestisci le immagini una per una invece di costruire una lista di mille stringhe codificate. Infine, a differenza degli URL, le immagini Base64 vengono ritrasmesse per intero a ogni richiesta: analizzare due volte la stessa fattura significa inviarla due volte.

Punti chiave

  • Il Base64 è ideale per immagini locali o generate dinamicamente
  • Il formato data URI combina tipo MIME e dati: data:image/png;base64,...
  • Ridimensiona e comprimi le tue immagini prima della codifica per ottimizzare la latenza
  • Il Base64 aumenta le dimensioni di circa il 33%: mantieni le tue immagini sotto i 10 MB
  • Usa l’URL quando l’immagine è già ospitata, il Base64 in tutti gli altri casi