Lähteet: URL ja Base64
Tällä sivulla
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 vaihtoehtourl: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_idFiles 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