Przejdź do głównej treści
Polski— Wybierz język
Menu

Kodowanie i wysyłanie obrazów w formacie Base64

Lekcja 5 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Dlaczego używać Base64?
  2. Kiedy użyć URL, a kiedy Base64?
  3. Kodowanie obrazu do Base64
  4. Format Data URI
  5. Pełny przykład
  6. Kodowanie obrazów z innych źródeł
  7. Optymalizacja rozmiaru przed kodowaniem
  8. Ograniczenia, które musisz znać
  9. Kluczowe wnioski

Dlaczego używać Base64?

W poprzedniej lekcji nauczyłeś się wysyłać obrazy za pomocą adresu URL. Jednak większość obrazów przetwarzanych w kontekście biznesowym nie posiada takiego adresu: faktura, która właśnie dotarła mailem, zrzut ekranu wygenerowany przez test automatyczny czy zdjęcie wykonane przez operatora na linii produkcyjnej. Publikowanie tych plików na serwerze dostępnym w internecie tylko po to, by je przeanalizować, byłoby absurdalne i często zabronione.

Tutaj z pomocą przychodzi kodowanie Base64. Przekształca ono dane binarne obrazu w ciąg tekstowy, który dołączasz bezpośrednio do żądania API, bez potrzeby używania zewnętrznego adresu URL ani pośredniego hostingu.

Kiedy użyć URL, a kiedy Base64?

KryteriumURLBase64
Obrazy już hostowaneIdealneNiepotrzebne
Obrazy lokalneNieodpowiednieIdealne
Obrazy generowane dynamicznieNieodpowiednieIdealne
Opóźnienie siecioweZależne od serweraBrak (osadzone)
Rozmiar żądaniaLekkieCięższe (~33%)
Bezpieczeństwo/prywatnośćPubliczny URLDane wewnątrz żądania

Zasada jest prosta: jeśli obraz jest dostępny pod stabilnym adresem URL, użyj URL. W przeciwnym razie użyj Base64.

Kodowanie obrazu do Base64

Nie są wymagane żadne zewnętrzne zależności; Python udostępnia moduł base64 w swojej bibliotece standardowej:

import base64

def encode_image(file_path):
    """Encode an image file to a Base64 string."""
    with open(file_path, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Encode a local image
image_b64 = encode_image("captures/screenshot.png")
print(f"Base64 string length: {len(image_b64)} characters")

Tryb "rb" podczas otwierania pliku nie jest opcjonalny: odczyt obrazu w trybie tekstowym spowoduje błąd dekodowania. Przygotuj się na długie ciągi – kodowanie zwiększa rozmiar o około 33% w porównaniu do oryginalnego pliku, więc obraz o wielkości 1 MB wygeneruje około 1,33 MB tekstu.

Format Data URI

Sam surowy ciąg znaków nie wystarczy: API musi znać format obrazu. Musisz więc przedstawić go jako data URI, co oznacza dodanie prefiksu z typem MIME przed danymi:

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

Cztery użyteczne prefiksy odpowiadają obsługiwanym formatom:

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

Zgłoszenie pliku PNG jako image/jpeg spowoduje błąd przetwarzania; stąd funkcja wykrywania w poniższym przykładzie.

Pełny przykład

Oto pełny łańcuch operacji, od odczytu pliku lokalnego po odpowiedź modelu:

import base64
import os
from mistralai.client import Mistral

def encode_image(chemin):
    """Encode a local image to Base64."""
    with open(chemin, "rb") as f:
        return base64.standard_b64encode(f.read()).decode("utf-8")

# Determine MIME type
def obtenir_mime(chemin):
    """Return MIME type based on extension."""
    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")

# Prepare the image
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}"

# Call the 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": "Extract all information from this invoice."},
                {"type": "image_url", "image_url": data_uri}
            ]
        }
    ]
)

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

Kluczowa uwaga: pole zawsze nazywa się image_url, nawet gdy zawiera data URI. Struktura wiadomości nie zmienia się ani o jotę w stosunku do Lekcji 4; różni się tylko wartość.

Kodowanie obrazów z innych źródeł

Plik na dysku to tylko jeden z wielu przypadków. Jeśli Twój obraz istnieje już w pamięci, jako obiekt Pillow pochodzący z przechwycenia lub etapu przetwarzania, zapisywanie go na dysku tylko po to, by natychmiast go odczytać, byłoby niepotrzebną objazdową drogą – bufor w pamięci sprawdzi się doskonale:

import base64
from io import BytesIO
from PIL import Image

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

# Example with a Pillow image
img = Image.open("capture.png")
data_uri = pil_to_base64(img)

Ta sama logika dotyczy obrazu pobranego przez HTTP, którego nie chcesz zapisywać, na przykład dlatego, że pochodzi z linku o krótkim czasie ważności:

import base64
import requests

def url_to_base64(url):
    """Download an image and convert it to a 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")

Optymalizacja rozmiaru przed kodowaniem

Zdjęcie ze smartfona waży dziś od 4 do 8 MB, co po zakodowaniu daje nearly 10 MB. API i tak zmieni jego rozmiar, jak widziałeś w Lekcji 2: płaciłbyś za transfer bez potrzeby. Dlatego zawsze zmieniaj rozmiar przed kodowaniem.

from PIL import Image
from io import BytesIO
import base64

def preparer_et_encoder(chemin, taille_max=1024, qualite=85):
    """Resize, compress, and encode an image."""
    img = Image.open(chemin)

    # Resize if necessary
    if max(img.size) > taille_max:
        img.thumbnail((taille_max, taille_max))

    # Convert to JPEG to reduce size
    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"Encoded image: {taille_ko:.0f} KB")

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

data_uri = preparer_et_encoder("photo_haute_resolution.png")

Wyświetlanie końcowego rozmiaru nie jest tylko ozdobnikiem: zachowaj to podczas testów, ponieważ natychmiast powie Ci, czy Twój pipeline wysyła przy każdym wywołaniu 80 KB, czy 8 MB.

Ograniczenia, które musisz znać

Z Base64 wiążą się trzy ograniczenia. Zakodowany obraz powiększa treść żądania HTTP, więc powyżej 10 MB ryzykujesz przekroczenie limitu czasu (timeout). Kodowanie ładuje również cały obraz do pamięci: przy przetwarzaniu wsadowym obsługuj obrazy pojedynczo, zamiast budować listę tysiąca zakodowanych ciągów. Wreszcie, w przeciwieństwie do adresów URL, obrazy Base64 są przesyłane w całości z każdym żądaniem – analiza tej samej faktury dwukrotnie oznacza wysłanie jej dwa razy.

Kluczowe wnioski

  • Base64 jest idealny dla obrazów lokalnych lub generowanych dynamicznie
  • Format data URI łączy typ MIME z danymi: data:image/png;base64,...
  • Zmień rozmiar i skompresuj obrazy przed kodowaniem, aby zoptymalizować opóźnienia
  • Base64 zwiększa rozmiar o około 33% – utrzymuj obrazy poniżej 10 MB
  • Używaj URL, gdy obraz jest już hostowany, a Base64 we wszystkich innych przypadkach