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

Lähteet: URL ja Base64

Oppitunti 6 / 14 Päivitetty 3. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Kuvien syöttäminen muokkauspäätteeseen
  2. URL-muoto
  3. Base64 Data URI -muoto
  4. Kolmas vaihtoehto: tiedosto Files API:sta
  5. Apufunktio
  6. Käytännön harjoitus
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026. Perustuen Image Editing -sivuun ja xAI Images API -viitteeseen: lähdekuvan voi määrittää myös Files API:ssa olevan tiedoston file_id:llä, joka on vaihtoehto url:lle. Lähteet: Image Editing · Images API.

Kuvien syöttäminen muokkauspäätteeseen

Muokkauspääte hyväksyy lähdekuvat kolmessa muodossa: julkisena URL-osoitteena, Base64-muotoisena Data URIna tai xAI Files API:hun jo ladatun tiedoston file_id:nä. Jokaisella on omat käyttötarkoituksensa; niiden hallinta mahdollistaa joustavien muokkausputkien rakentamisen.

URL-muoto

URL-muoto on kätevin vaihtoehto, kun kuva on jo verkossa: mitään ei tarvitse koodata, hyötykuorma on pieni ja pyyntö pysyy luettavana lokeissa. Tärkein rajoite on julkinen – xAI-palvelimien on pystyttävä noutamaan kuva ilman istuntoa tai tunnistetta.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a gold frame around this image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

URL-rajoitukset

  • URL-osoitteen on oltava julkisesti saatavilla (ei suojattuja linkkejä, jotka vaativat tunnistautumista)
  • Tuetut muodot ovat JPEG, PNG ja WebP
  • Kuvan on oltava nopeasti saatavilla (vältä hitaita palvelimia)

API:n palauttamien URL-osoitteiden käyttö

Tämä tekee monivaiheisesta muokkauksesta käytännöllistä: yhden muokkauksen tulosteesta tulee seuraavan syöte ilman, että kuvaa tarvitsee koskaan ladata paikalliselle koneelle. On kuitenkin yksi varoitus: nämä URL-osoitteet vanhenevat, joten ketjun on suorituttava kerralla. Jos työnkulku venyy ajallisesti, lataa kuva kunkin vaiheen välissä.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

# Luo kuva
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "A medieval castle on a hill"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Muokkaa luotua kuvaa
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Add a dragon flying over the castle",
        "image": {"url": generated_url}
    }
).json()

Base64 Data URI -muoto

Paikallisesti tallennetuille tai dynaamisesti luoduille kuville käytä Base64 Data URI -muotoa:

import base64

# Lue paikallinen kuva
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transform this photo into a vector illustration",
    "image": {
        "url": data_uri
    }
}

Milloin käyttää Base64:ta?

Kriteeri on yksinkertainen: Base64 on välttämätön aina, kun julkisen URL-osoitteen käyttö olisi turha kierto. Tämä koskee paikallisia kuvia, joita ei ole isännetty missään – niiden lataaminen palvelimelle pelkästään API:n saataville tekemiseksi lisää vaiheen ja viivettä ilman hyötyä. Se koskee myös sovelluksesi muistissa luomia kuvia: lennossa tuotettu kaavio, renderöinnin kuvakaappaus tai dynaamisesti koostettu pikkukuva eivät koskaan tarvitse kosketusta levyyn. Base64 ratkaisee myös tietosuojahuolen – pyynnön rungossa koodattu kuva ei ole koskaan esillä julkisella palvelimella, edes väliaikaisesti – ja yksinkertaistaa arkkitehtuuria: automatisoitu putki, joka ketjuttaa luonnin, muokkauksen ja tallennuksen, toimii alusta loppuun ilman välivaiheen isännöintiä, jota pitäisi ottaa käyttöön, suojata ja siivota.

Huomioi koko

Base64 kasvattaa hyötykuormaa noin kolmanneksella, mikä on merkityksetöntä pikkukuvalle, mutta merkitsevää usean megatavun valokuvalle – latausajat pitenevät ja pyynnön kokorajojen ylittymisen riski kasvaa. Nyrkkisääntö: jos kuva on jo saatavilla verkossa, käytä URL-osoitetta; jos se on paikallinen, Base64 on yksinkertaisempi kuin sen isännöiminen vain tätä tilaisuutta varten.

Kolmas vaihtoehto: tiedosto Files API:sta

Kuva, joka on jo ladattu xAI Files API -palveluun, määritetään sen tunnisteella URL-osoitteen sijaan. Nämä kaksi kenttää sulkevat toisensa pois: image-objekti sisältää joko url:n tai file_id:n.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"file_id": "file_abc123"}
}

Tämä on luonteva valinta kuvalle, jota käytetään uudelleen useissa muokkauksissa: se lähetetään vain kerran, eikä sen tarvitse olla julkinen.

Apufunktio

Tässä on funktio, joka käsittelee molemmat muodot automaattisesti:

import base64
import os

def prepare_image_source(source):
    """Prepares an image source for the API (URL or local file)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Invalid source: {source}")

Tämä funktio tunnistaa automaattisesti, onko lähde URL-osoite vai paikallinen tiedostopolku, ja muotoilee objektin sen mukaisesti.

Käytännön harjoitus

Testaa molempia muotoja samalla kuvalla ja kehotteella varmistaaksesi, että molemmat polut toimivat; tuloksena olevat kuvat vaihtelevat suorituskerroittain kuten mikä tahansa generointi:

# URL:n kautta
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Base64:n kautta
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": prepare_image_source("paysage.jpg")
}

Keskeiset asiat

  • Kolme syöttömuotoa: julkinen URL, Base64 Data URI tai file_id Files API:sta
  • API:n palauttamia väliaikaisia URL-osoitteita voi käyttää muokkauslähteinä
  • Base64 kasvattaa hyötykuormaa noin 33 %
  • Luo apufunktio käsittelemään molemmat muodot automaattisesti
  • URL-osoitteen on oltava julkisesti saatavilla toimiakseen