Bild über URL senden — Bildanalyse und visuelle Erkennung über die API

Die einfachste Methode

Das Senden eines Bildes über eine URL ist der direkteste Weg, die Vision API zu nutzen: Sie geben die Adresse eines öffentlich zugänglichen Bildes an, und Mistral lädt es für die Analyse herunter. Ihre Anfrage bleibt leichtgewichtig – nur wenige hundert Bytes –, da sie lediglich einen Link enthält.

Priorisieren Sie diese Methode, wenn Ihre Bilder bereits auf einem CDN, in Cloud-Speicher oder auf einer Website gehostet sind, oder wenn Sie mit öffentlichen Web-Bildern arbeiten. Ein Team, das Produktvisualisierungen bereits auf einem CDN speichert, kann diese ohne Änderungen an der Infrastruktur analysieren.

Nachrichtenformat

Eine multimodale Nachricht mit einer Bild-URL folgt dieser Struktur:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Ihre Frage zum Bild"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

Das Feld image_url akzeptiert jede HTTP- oder HTTPS-URL, die auf eine gültige Bilddatei im JPEG-, PNG-, GIF- oder WebP-Format verweist.

Komplettes Python-Beispiel

Hier ist ein vollständiges, sofort ausführbares Skript, das ein öffentliches Bild von Wikimedia analysiert, unter der Annahme, dass Ihr API-Schlüssel in der Umgebung gesetzt ist:

from mistralai.client import Mistral
import os

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

# Öffentliches Bild zur Analyse
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Vision API aufrufen
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Beschreiben Sie präzise, was Sie in diesem Bild sehen."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

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

Beachten Sie, dass wir den Schlüssel über os.environ übergeben, anstatt ihn hartcodiert einzufügen. Dies ist der einzige akzeptable Ansatz, sobald das Skript den lokalen Computer verlässt.

Hinzufügen eines System-Prompts

Die obige Antwort wäre zwar korrekt, aber allgemein gehalten – „eine schwarze Ameise auf einem unscharfen Hintergrund”. Eine Systemnachricht ändert die Art der Analyse, indem sie dem Modell vor dem Betrachten des Bildes eine Rolle zuweist:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "Sie sind ein Experte für Entomologie. Analysieren Sie Insektenbilder mit wissenschaftlicher Präzision, identifizieren Sie die Art, Familie und sichtbaren morphologischen Merkmale."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Identifizieren Sie dieses Insekt."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Mit dieser Rahmung liefert das gleiche Bild eine taxonomische Identifizierung und eine morphologische Beschreibung. Der System-Prompt steuert, wie das Modell das Bild analysiert – ein mächtiger Hebel, um spezialisierte Antworten zu erhalten, zum Preis von nur wenigen Dutzend Tokens.

URL-Anforderungen

Die API muss das Bild ohne jeglichen Kontext aus Ihrer Sitzung herunterladen können. Dies führt zu vier Anforderungen: Die URL muss öffentlich zugänglich sein (keine Seiten hinter Authentifizierung); sie muss direkt auf die Datei verweisen, nicht auf eine HTML-Seite, die das Bild enthält; das Format muss unterstützt werden (JPEG, PNG, GIF, wobei nur der erste Frame gelesen wird, oder WebP); und die Größe muss angemessen bleiben, unter 20 MB.

Die häufigste Verwirrung betrifft Freigabelinks. Ein Google Drive- oder Dropbox-Link, der „mit allen geteilt” ist, gibt eine HTML-Seite zurück, nicht eine Bilddatei: Der Aufruf schlägt fehl, oder das Modell beschreibt eine Benutzeroberfläche. Die beste Praxis besteht darin, den Content-Type vor dem Senden zu überprüfen:

import requests

def verify_image_url(url):
    """Überprüfen Sie, ob eine URL auf ein zugängliches Bild verweist."""
    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"Bild zugänglich: {content_type}, {size / 1024:.0f} KB")
            return True
        else:
            print(f"Problem: status={response.status_code}, type={content_type}")
            return False
    except requests.RequestException as e:
        print(f"Verbindungsfehler: {e}")
        return False

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

Eine HEAD-Anfrage reicht aus: Sie ruft Header ab, ohne die Datei herunterzuladen.

Bilder aus Cloud-Speicher

Diese Anforderung der öffentlichen Zugänglichkeit scheint mit vertraulichen Dokumenten unvereinbar. Die Lösung liegt in vorzeichen URLs (Pre-signed URLs): Wenn Ihre Bilder in einem S3-Bucket, Google Cloud Storage oder Azure Blob liegen, generieren Sie eine temporäre Adresse, die den Zugriff auf ein einzelnes Objekt für eine von Ihnen festgelegte Dauer gewährt.

import boto3

s3 = boto3.client("s3")

# Generieren Sie eine vorzeichen URL, die eine Stunde gültig ist
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Verwenden Sie diese URL mit der Vision API
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extrahieren Sie den Gesamtbetrag aus dieser Rechnung."},
                {"type": "image_url", "image_url": presigned_url}
            ]
        }
    ]
)

Ihr Bucket bleibt privat, die URL erlischt nach dem angegebenen Zeitintervall, und Sie behalten die Leichtgewichtigkeit der Anfrage bei. Stellen Sie ExpiresIn so kurz wie möglich ein: Ein paar Minuten reichen für einen API-Aufruf mehr als aus.

Fehlerbehandlung

Ein Aufruf, der von einem Remote-Download abhängt, kann aus Gründen scheitern, die außerhalb Ihrer Kontrolle liegen – das Bild wurde gelöscht, die URL ist abgelaufen oder der Hostingserver ist nicht verfügbar. In der Produktion lassen Sie niemals die rohe Ausnahme bis zum Benutzer durchblitzen:

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": "Beschreiben Sie dieses Bild."},
                    {"type": "image_url", "image_url": "https://example.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Fehler: {e}")

Testen Sie Ihre Fehlerbehandlung mit einer absichtlich ungültigen URL, bevor Sie bereitstellen: Dies ist die häufigste Situation und diejenige, die am seltensten getestet wird.

Kernaussagen

Das Senden über eine URL ist die einfachste Methode – eine öffentliche URL ist alles, was Sie benötigen
Das Nachrichtenfeld content ist ein Array, das text- und image_url-Elemente enthält
Die URL muss direkt auf eine zugängliche Bilddatei verweisen
Vorzeichen URLs ermöglichen die sichere Nutzung privater Bilder
Fügen Sie immer einen System-Prompt hinzu, um die Analyse des Modells zu steuern