Bilder in Base64 codieren und senden

Warum Base64 verwenden?

In der vorherigen Lektion haben Sie gelernt, wie man Bilder über eine URL sendet. Die meisten Bilder, die in geschäftlichen Kontexten verarbeitet werden, verfügen jedoch nicht über eine URL: eine per E-Mail eingegangene Rechnung, ein Screenshot, der von einem automatisierten Test generiert wurde, oder ein Foto, das von einem Bediener an einer Produktionslinie aufgenommen wurde. Das Veröffentlichen dieser Dateien auf einem internetzugänglichen Server, nur um sie zu analysieren, wäre absurd und oft sogar verboten.

Hier kommt die Base64-Codierung ins Spiel. Sie wandelt die Binärdaten eines Bildes in einen Textstring um, den Sie direkt in Ihre API-Anforderung einfügen können, ohne dass eine externe URL oder eine Zwischenhostung erforderlich ist.

Wann URL und wann Base64 verwenden

Die Regel ist einfach: Wenn das Bild über eine stabile URL zugänglich ist, verwenden Sie die URL. Andernfalls verwenden Sie Base64.

Ein Bild in Base64 codieren

Es sind keine Abhängigkeiten erforderlich; Python bietet das Modul base64 in seiner Standardbibliothek an:

import base64

def encode_image(file_path):
    """Ein Bilddatei in einen Base64-String codieren."""
    with open(file_path, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Ein lokales Bild codieren
image_b64 = encode_image("captures/screenshot.png")
print(f"Länge des Base64-Strings: {len(image_b64)} Zeichen")

Der Modus "rb" beim Öffnen der Datei ist nicht optional: Das Lesen eines Bildes im Textmodus führt zu einem Decodierungsfehler. Erwarten Sie lange Strings – die Codierung vergrößert die Größe um etwa 33 % im Vergleich zur Originaldatei, sodass ein 1 MB großes Bild ungefähr 1,33 MB Text erzeugt.

Data URI-Format

Der reine String reicht nicht aus: Die API muss das Bildformat kennen. Sie müssen es daher als Data URI präsentieren, das die Daten mit dem MIME-Typ voransetzt:

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

Die vier nutzbaren Präfixe entsprechen den unterstützten Formaten:

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

Die Angabe eines PNG als image/jpeg führt zu einem Verarbeitungsfehler; daher enthält der folgende Beispielcode eine Erkennungsfunktion.

Vollständiges Beispiel

Hier ist die vollständige Kette, vom Lesen der lokalen Datei bis zur Antwort des Modells:

import base64
import os
from mistralai.client import Mistral

def encode_image(chemin):
    """Ein lokales Bild in Base64 codieren."""
    with open(chemin, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# MIME-Typ ermitteln
def obtenir_mime(chemin):
    """MIME-Typ basierend auf der Erweiterung zurückgeben."""
    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")

# Bild vorbereiten
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}"

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

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extrahieren Sie alle Informationen aus dieser Rechnung."},
                {"type": "image_url", "image_url": data_uri}
            ]
        }
    ]
)

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

Wichtiger Hinweis: Das Feld heißt immer image_url, auch wenn es einen Data URI enthält. Die Nachrichtenstruktur unterscheidet sich in keinem Bit von Lektion 4; nur der Wert ist anders.

Bilder aus anderen Quellen codieren

Eine Datei auf der Festplatte ist nur einer von vielen Fällen. Wenn Ihr Bild bereits im Arbeitsspeicher existiert, beispielsweise als Pillow-Objekt aus einem Erfassungs- oder Verarbeitungsschritt, wäre das Schreiben auf die Festplatte, nur um es sofort wieder zu lesen, eine unnötige Umleitung – ein Speicherbuffer funktioniert gut:

import base64
from io import BytesIO
from PIL import Image

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

# Beispiel mit einem Pillow-Bild
img = Image.open("capture.png")
data_uri = pil_to_base64(img)

Gleiche Logik gilt für ein Bild, das über HTTP abgerufen wurde und das Sie nicht speichern möchten, beispielsweise weil es von einem kurzlebigen Link stammt:

import base64
import requests

def url_to_base64(url):
    """Ein Bild herunterladen und in einen Data URI umwandeln."""
    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")

Größe vor der Codierung optimieren

Ein Smartphone-Foto wiegt heute zwischen 4 und 8 MB, was nach der Codierung fast 10 MB ausmacht. Die API wird es ohnehin vergrößern, wie Sie in Lektion 2 gesehen haben: Sie würden für die Übertragung bezahlen, ohne einen Nutzen zu erzielen. Codieren Sie Bilder daher immer vor der Codierung neu.

from PIL import Image
from io import BytesIO
import base64

def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
    """Ein Bild neu dimensionieren, komprimieren und codieren."""
    img = Image.open(chemin)

    # Bei Bedarf neu dimensionieren
    if max(img.size) > taille_max:
        img.thumbnail((taille_max, taille_max))

    # In JPEG umwandeln, um die Größe zu reduzieren
    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"Codiertes Bild: {taille_ko:.0f} KB")

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

data_uri = preparer_et_encoder("photo_haute_resolution.png")

Die Anzeige der endgültigen Größe ist nicht nur dekorativ: Bewahren Sie sie während Ihrer Tests auf, da sie Ihnen sofort sagt, ob Ihr Pipeline bei jedem Aufruf 80 KB oder 8 MB sendet.

Zu beachtende Grenzen

Mit Base64 kommen drei Einschränkungen. Das codierte Bild wird zum HTTP-Anforderungsbody hinzugefügt; ab 10 MB besteht die Gefahr von Timeouts. Die Codierung lädt zudem das gesamte Bild in den Arbeitsspeicher: Für die Batch-Verarbeitung sollten Sie Bilder einzeln verarbeiten, anstatt eine Liste mit tausend codierten Strings zu erstellen. Schließlich werden Base64-Bilder im Gegensatz zu URLs bei jeder Anforderung vollständig erneut gesendet – die Analyse derselben Rechnung zweimal bedeutet, sie zweimal zu senden.

Wichtige Erkenntnisse

• Base64 ist ideal für lokale oder dynamisch generierte Bilder
• Das Data URI-Format kombiniert MIME-Typ und Daten: data:image/png;base64,...
• Dimensionieren und komprimieren Sie Ihre Bilder vor der Codierung, um die Latenz zu optimieren
• Base64 vergrößert die Größe um etwa 33 % – halten Sie Ihre Bilder unter 10 MB
• Verwenden Sie URL, wenn das Bild bereits gehostet ist, und Base64 in allen anderen Fällen