Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Inviare un'immagine tramite URL

Lezione 4 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il metodo più semplice
  2. Formato del messaggio
  3. Esempio completo in Python
  4. Aggiunta di un prompt di sistema
  5. Requisiti dell’URL
  6. Immagini dal cloud storage
  7. Gestione degli errori
  8. Punti chiave

Il metodo più semplice

L’invio di un’immagine tramite URL è il modo più diretto per utilizzare l’API Vision: fornisci l’indirizzo di un’immagine pubblicamente accessibile e Mistral la scarica per analizzarla. La tua richiesta rimane leggera, pochi centinaia di byte, poiché trasporta solo un link.

Dai priorità a questo metodo quando le tue immagini sono già ospitate su una CDN, su un cloud storage o su un sito web, oppure quando lavori con immagini pubbliche del web. Un team che archivia già le visualizzazioni dei prodotti su una CDN può iniziare ad analizzarle senza modificare la propria infrastruttura.

Formato del messaggio

Un messaggio multimodale contenente un URL di immagine segue questa struttura:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Your question about the image"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

Il campo image_url accetta qualsiasi URL HTTP o HTTPS che punti a un file immagine valido nei formati JPEG, PNG, GIF o WebP.

Esempio completo in Python

Ecco uno script completo e pronto all’uso che analizza un’immagine pubblica da Wikimedia, presupponendo che la tua chiave API sia impostata nell’ambiente:

from mistralai.client import Mistral
import os

# Inizializza il client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Immagine pubblica da analizzare
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Chiama l'API Vision
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe precisely what you see in this image."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

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

Nota che passiamo la chiave tramite os.environ invece di codificarla direttamente. Questo è l’unico approccio accettabile una volta che lo script lascia la tua macchina locale.

Aggiunta di un prompt di sistema

La risposta sopra sarà corretta ma generica: «una formica nera su uno sfondo sfocato». Un messaggio di sistema cambia la natura dell’analisi assegnando un ruolo al modello prima che visualizzi l’immagine:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "You are an entomology expert. Analyze insect images with scientific precision, identifying the species, family, and visible morphological characteristics."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Identify this insect."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Con questa impostazione, la stessa immagine produce un’identificazione tassonomica e una descrizione morfologica. Il prompt di sistema guida il modo in cui il modello analizza l’immagine: una leva potente per ottenere risposte specializzate al costo di poche decine di token.

Requisiti dell’URL

L’API deve essere in grado di scaricare l’immagine senza alcun contesto dalla tua sessione. Questo comporta quattro requisiti: l’URL deve essere pubblicamente accessibile (nessuna pagina protetta da autenticazione); deve puntare direttamente al file, non a una pagina HTML contenente l’immagine; il formato deve essere supportato (JPEG, PNG, GIF dove viene letto solo il primo frame, o WebP); e le dimensioni devono rimanere ragionevoli, sotto i 20 MB.

La confusione più comune riguarda i link di condivisione. Un link di Google Drive o Dropbox «condiviso con tutti» restituisce una pagina HTML, non un file immagine: la chiamata fallisce oppure il modello descrive un’interfaccia web. La migliore pratica consiste nel verificare il Content-Type prima dell’invio:

import requests

def verify_image_url(url):
    """Verifica che un URL punti a un'immagine accessibile."""
    try:
        response = requests.head(url, timeout=5, allow_redirects=True)
        content_type = response.headers.get("Content-Type", "")

        if response.status_code == 200 and "image" in content_type:
            size = int(response.headers.get("Content-Length", 0))
            print(f"Image accessible: {content_type}, {size / 1024:.0f} KB")
            return True
        else:
            print(f"Issue: status={response.status_code}, type={content_type}")
            return False
    except requests.RequestException as e:
        print(f"Connection error: {e}")
        return False

verify_image_url("https://example.com/photo.jpg")

Una richiesta HEAD è sufficiente: recupera le intestazioni senza scaricare il file.

Immagini dal cloud storage

Questo requisito di accessibilità pubblica sembra incompatibile con i documenti riservati. La soluzione risiede negli URL pre-firmati: se le tue immagini si trovano in un bucket S3, in Google Cloud Storage o in Azure Blob, generi un indirizzo temporaneo che concede l’accesso a un singolo oggetto per una durata da te specificata.

import boto3

s3 = boto3.client("s3")

# Genera un URL pre-firmato valido per 1 ora
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Usa questo URL con l'API Vision
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the total amount from this invoice."},
                {"type": "image_url", "image_url": presigned_url}
            ]
        }
    ]
)

Il tuo bucket rimane privato, l’URL scade dopo il ritardo specificato e mantieni la leggerezza della richiesta. Imposta ExpiresIn il più breve possibile: pochi minuti sono più che sufficienti per una chiamata API.

Gestione degli errori

Una chiamata che dipende da un download remoto può fallire per motivi fuori dal tuo controllo: l’immagine è stata eliminata, l’URL è scaduto o il server di hosting non è disponibile. In produzione, non lasciare mai che l’eccezione grezza risalga fino all’utente:

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Describe this image."},
                    {"type": "image_url", "image_url": "https://example.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")

Testa la tua gestione degli errori con un URL deliberatamente non valido prima del deploy: questo è lo scenario più frequente e quello meno spesso testato.

Punti chiave

  • L’invio tramite URL è il metodo più semplice: basta un URL pubblico
  • Il campo content del messaggio è un array contenente elementi text e image_url
  • L’URL deve puntare direttamente a un file immagine accessibile
  • Gli URL pre-firmati permettono di utilizzare immagini private in sicurezza
  • Aggiungi sempre un prompt di sistema per guidare l’analisi del modello