Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Piltide kodeerimine ja saatmine Base64-formaadis

Õppetund 5 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Miks kasutada Base64?
  2. Millal kasutada URL-i ja millal Base64-t?
  3. Pildi kodeerimine Base64-formaati
  4. Andme-URI formaat
  5. Täielik näide
  6. Piltide kodeerimine teistest allikatest
  7. Optimeeri suurust enne kodeerimist
  8. Piirangud, mida tasub teada
  9. Peamised punktid

Miks kasutada Base64?

Eelmises õppetükis õppisid, kuidas saata pilte URL-i kaudu. Enamik ettevõtluskontekstis töödeldavaid pilte aga URL-i ei oma: näiteks just meiliga saabunud arve, automatiseeritud testi käigus tehtud ekraanitõmmis või tootmisliinil operaatori tehtud foto. Nende failide avalikku serverisse laadimine üksnes analüüsimise eesmärgil oleks absurdne ja sageli isegi keelatud.

Siin tulebki mängu Base64-kodeering. See teisendab pildi binaarsed andmed tekstistringiks, mille saad lisada otse oma API päringusse, ilma et oleks vaja välist URL-i või vahepealset majutust.

Millal kasutada URL-i ja millal Base64-t?

KriteeriumURLBase64
Juba majutatud pildidIdeaalnePole vaja
Kohalikud pildidEi sobiIdeaalne
Dünaamiliselt genereeritud pildidEi sobiIdeaalne
Võrgu viivisSõltub serveristPuudub (manustatud)
Päringu suurusKergeRaskem (~33%)
Turvalisus/privaatsusAvalik URLAndmed päringu sees

Reegel on lihtne: kui pilt on stabiilse URL-i kaudu kättesaadav, kasuta URL-i. Vastasel juhul kasuta Base64-t.

Pildi kodeerimine Base64-formaati

Ühtegi välist sõltuvust pole vaja; Python pakub moodulit base64 oma standardteegis:

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")

Faili avamisel on režiim "rb" (binary read) kohustuslik: pildi lugemine tekstirežiimis põhjustab dekodeerimisvea. Oota pikki stringe – kodeerimine suurendab faili mahtu algsega võrreldes umbes 33%, seega 1 MB suurune pilt annab tulemuseks ligikaudu 1,33 MB teksti.

Andme-URI formaat

Paljas string ei piisa: API peab teadma pildi formaati. Seetõttu pead esitama selle andme-URI (data URI) kujul, mis lisab andmete ette MIME-tüübi:

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

Neli kasutatavat eesliidet vastavad toetatud formaatidele:

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

Kui kuulutad PNG-pildi kui image/jpeg, tekib töötlemisel viga; seetõttu on järgmises näites olemas tuvastusfunktsioon.

Täielik näide

Siin on kogu ahel alates kohaliku faili lugemisest kuni mudeli vastuseni:

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)

Oluline tähelepanek: väli kannab alati nime image_url, isegi kui see sisaldab andme-URI-d. Sõnumi struktuur ei erine grammagi 4. õppetükist; muutub ainult väärtus.

Piltide kodeerimine teistest allikatest

Fail kettaga on vaid üks paljudest juhtudest. Kui su pilt eksisteerib juba mälus, näiteks Pillow objektina pärast ekraanitõmmise tegemist või töötlemist, oleks selle kettale kirjutamine ja kohe uuesti lugemine tarbetu ringkäik – mälupuhver sobib suurepäraselt:

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)

Sama loogika kehtib HTTP kaudu hangitud pildi puhul, mida sa ei soovi salvestada, näiteks kui see pärineb lühiajalisest lingist:

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")

Optimeeri suurust enne kodeerimist

Tänapäeva nutitelefoniga tehtud foto kaalub 4–8 MB, mis pärast kodeerimist kasvab peaaegu 10 MB-ni. API muudab selle niikuinii väiksemaks, nagu nägid 2. õppetükis: maksaksid edastamise eest asjatult. Seega muuda pilt alati enne kodeerimist väiksemaks.

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")

Lõpliku suuruse kuvamine pole pelgalt ilu pärast: hoia see oma testide käigus alles, sest see annab kohe teada, kas su torustik saadab iga kutsega 80 KB või 8 MB andmeid.

Piirangud, mida tasub teada

Base64-ga kaasneb kolm piirangut. Kodeeritud pilt lisandub HTTP-päringu kehale, seega üle 10 MB minekul riskid aegumistega. Kodeerimine laadib kogu pildi ka mällu: partii töötlemisel töötle pilte ükshaaval, mitte ära loo tuhande kodeeritud stringi nimekirja. Lõpuks, erinevalt URL-idest, saadetakse Base64-pildid iga päringuga täismahus uuesti – sama arve kahekordne analüüsimine tähendab selle kahekordset saatmist.

Peamised punktid

  • Base64 on ideaalne kohalike või dünaamiliselt genereeritud piltide jaoks
  • Andme-URI formaat ühendab MIME-tüübi ja andmed: data:image/png;base64,...
  • Enne kodeerimist vähenda ja tihenda pilte, et optimeerida viivitust
  • Base64 suurendab mahtu umbes 33% – hoia pildid alla 10 MB
  • Kasuta URL-i, kui pilt on juba majutatud, ja Base64-t kõigil muudel juhtudel