Codificare e inviare immagini in Base64
In questa pagina
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
| Criterio | URL | Base64 |
|---|---|---|
| Immagini già ospitate | Ideale | Inutile |
| Immagini locali | Non adatto | Ideale |
| Immagini generate dinamicamente | Non adatto | Ideale |
| Latenza di rete | Dipende dal server | Nessuna (incorporata) |
| Dimensione della richiesta | Leggera | Più pesante (~33%) |
| Sicurezza/privacy | URL pubblico | Dati 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