Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Koodaa ja lähetä kuvia Base64-muodossa

Oppitunti 5 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi käyttää Base64:ta?
  2. Milloin käyttää URL:ää ja milloin Base64:ta
  3. Kuvan koodaaminen Base64-muotoon
  4. Data URI -muoto
  5. Täydellinen esimerkki
  6. Kuvien koodaaminen muista lähteistä
  7. Optimoi koko ennen koodausta
  8. Huomioitavat rajat
  9. Keskeiset asiat

Miksi käyttää Base64:ta?

Edellisessä oppitunnissa opit lähettämään kuvia URL-osoitteen kautta. Useimmilla yrityskontekstissa käsiteltävillä kuvilla ei kuitenkaan ole URL-osoitetta: sähköpostilla juuri saapunut lasku, automatisoidun testin tuottama kuvakaappaus tai tuotantolinjalla operaattorin ottama valokuva. Näiden tiedostojen julkaiseminen internetissä reachable-palvelimella pelkkää analysointia varten olisi absurdiä ja usein kiellettyä.

Tässä tulee avuksi Base64-koodaus. Se muuntaa kuvan binääridatan merkkijonoksi, jonka voit sisällyttää suoraan API-pyyntöösi ilman ulkoista URL-osoitetta tai välihostingia.

Milloin käyttää URL:ää ja milloin Base64:ta

KriterioURLBase64
Jo hostatut kuvatIhanteellinenTarpeeton
Paikalliset kuvatEi sovelluIhanteellinen
Dynaamisesti luodut kuvatEi sovelluIhanteellinen
Verkon viiveRiippuu palvelimestaEi ole (upotettu)
Pyynnön kokoKevytRaskaampi (~33 %)
Turvallisuus/yksityisyysJulkinen URLData pyynnön sisällä

Sääntö on yksinkertainen: jos kuva on saatavilla vakaan URL-osoitteen kautta, käytä URL-osoitetta. Muussa tapauksessa käytä Base64:ta.

Kuvan koodaaminen Base64-muotoon

Ulkoisia riippuvuuksia ei tarvita; Python tarjoaa base64-moduulin vakio kirjastossaan:

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

Tiedostoa avattaessa käytettävä "rb"-tila ei ole valinnainen: kuvan lukeminen teksti-tilassa aiheuttaa dekoodausvirheen. Oleta merkkijonojen olevan pitkiä – koodaus kasvattaa kokoa noin 33 % alkuperäiseen tiedostoon verrattuna, joten 1 Mt:n kuvasta tulee noin 1,33 Mt tekstiä.

Data URI -muoto

Pelkkä merkkijono ei riitä: API:n on tiedettävä kuvan formaatti. Sinun on siis esitettävä se data URI:na, joka lisää datan eteen sen MIME-tyypin:

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

Neljä käytettävissä olevaa etuliitettä vastaavat tuettuja formaatteja:

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

PNG-kuvan ilmoittaminen muodossa image/jpeg aiheuttaa käsittelyvirheen; siksi seuraavassa esimerkissä on tunnistusfunktio.

Täydellinen esimerkki

Tässä on koko ketju paikallisen tiedoston lukemisesta mallin vastaukseen:

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)

Tärkein oivallus: kentän nimi on aina image_url, vaikka se sisältäisi data URI:n. Viestin rakenne ei muutu lainkaan oppitunnista 4; vain arvo eroaa.

Kuvien koodaaminen muista lähteistä

Levyllä oleva tiedosto on vain yksi monista tapauksista. Jos kuvasi on jo muistissa, esimerkiksi Pillow-objektina kaappauksen tai käsittelyvaiheen jälkeen, sen kirjoittaminen levylle vain lukeaksesi sen heti uudelleen olisi tarpeeton kiertotie – muistipuskuri toimii hyvin:

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 logiikka pätee HTTP:n kautta haettuun kuvaan, jota et halua tallentaa, esimerkiksi koska se tulee lyhytikäisestä linkistä:

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

Optimoi koko ennen koodausta

Nykyään älypuhelimen ottama valokuva painaa 4–8 Mt, mikä koodattuna on lähes 10 Mt. API skaalaa sen joka tapauksessa, kuten näit oppitunnilla 2: maksaisit siirrosta turhaan. Siksi skaalaa kuva aina ennen koodausta.

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

Lopullisen koon näyttäminen ei ole vain koristeellista: pidä se testauksessasi, sillä se kertoo välittömästi, lähettääkö putkesi jokaisella kutsulla 80 kt vai 8 Mt.

Huomioitavat rajat

Base64:ään liittyy kolme rajoitusta. Koodattu kuva lisääntyy HTTP-pyynnön rungossa, joten yli 10 Mt:n koossa riskinä on aikakatkaisu. Koodaus lataa myös koko kuvan muistiin: eräajossa käsittele kuvat yksi kerrallaan sen sijaan, että rakentaisit listan tuhannesta koodatusta merkkijonosta. Lopuksi, toisin kuin URL-osoitteet, Base64-kuvat lähetetään kokonaisina jokaisessa pyynnössä – saman laskun analysointi kahdesti tarkoittaa sen lähettämistä kahdesti.

Keskeiset asiat

  • Base64 on ihanteellinen paikallisille tai dynaamisesti luoduille kuville
  • Data URI -muoto yhdistää MIME-tyypin ja datan: data:image/png;base64,...
  • Skaalaa ja pakkaa kuvasi ennen koodausta viiveen optimoimiseksi
  • Base64 kasvattaa kokoa noin 33 % – pidä kuvasi alle 10 Mt:n kokoisina
  • Käytä URL:ää, kun kuva on jo hostattu, ja Base64:ta kaikissa muissa tapauksissa