Pildiallikad: URL ja Base64
Sellel lehel
Uuendatud 3. novembril 2026. Lähtudes Pilditöötluse lehest ja xAI piltide API viitest: lähtepildi saab määrata ka Files API faili
file_idabil, mis onurl-i välistav alternatiiv. Allikad: Pilditöötlus · Piltide API.
Piltide edastamine muutmise lõpppunkti
Muutmise lõpppunkt (edit endpoint) aktsepteerib lähtepilte kolmel kujul: avalik URL, Base64 andme-URI või xAI Files API-sse juba üles laaditud faili file_id. Igal neist on oma kasutusvaldkond; nende valdamine võimaldab sul luua paindlikke töötlemise ahelaid.
URL-i formaat
URL-i formaat on kõige mugavam variant, kui pilt on juba veebis: midagi pole vaja kodeerida, kasutajaandmemaht on väike ja päring jääb logides loetavaks. Siinne peamine tingimus on avalikkus – pilt peab olema xAI serveritele kättesaadav ilma sessiooni või tokenita.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
URL-i piirangud
- URL peab olema avalikult ligipääsetav (autentimisega kaitstud lingid ei sobi)
- Toetatud formaadid on JPEG, PNG ja WebP
- Pilt peab olema kiiresti kättesaadav (välti aeglasi servereid)
API väljund-URL-ide kasutamine
See on see, mis teeb mitmeastmelise töötlemise praktiliseks: ühe muudatuse väljund saab järgmise sisendiks, ilma et peaks pilti oma kohalikku masinasse alla laadima. Üks aga – need URL-id aeguvad, seega peab ahel käivituma ühe hooga. Ajaliselt hajutatud töövoogu korraldades laadi see iga sammu vahel alla.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Pildi genereerimine
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"]
# Genereeritud pildi muutmine
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 andme-URI formaat
Kohalikele või dünaamiliselt genereeritud piltidele kasuta Base64 andme-URI formaati:
import base64
# Kohaliku pildi lugemine
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
}
}
Millal kasutada Base64-t?
Kriteerium on lihtne: Base64 on vajalik alati, kui avaliku URL-i kasutamine oleks asjatu ringtee. See kehtib kohalike piltide kohta, mida kusagil majutatud pole – nende serverisse laadimine, et muuta need API-le kättesaadavaks, lisab sammu ja viivitust ilma väärtuseta. See kehtib ka rakenduse mälus genereeritud piltide kohta: lennult loodud diagramm, renderduse ekraanitõmmis või dünaamiliselt koostatud pisipilt ei pea kunagi ketast puudutama. Base64 lahendab ka privaatsusmure – päringu kehas kodeeritud pilti ei avaldata kunagi avalikus serveris, isegi mitte ajutiselt – ja lihtsustab arhitektuuri: automatiseeritud torustik, mis aheldab genereerimise, muutmise ja salvestamise, töötab otsast otsani ilma vahepealse majutuseta, mida tuleks hallata, turvata ja puhastada.
Jälgi suurust
Base64 suurendab kasutajaandmemahtu umbes kolmandiku võrra, mis on pisipildi puhul tühine, kuid muutub mitme megabaidi suuruse foto puhul oluliseks – pikemad üleslaadimisajad ja oht ületada päringu suuruse piiranguid. Reegel on lihtne: kui pilt on juba veebis kättesaadav, kasuta URL-i; kui see on kohalik, on Base64 lihtsam kui selle ajutine majutamine.
Kolmas variant: fail Files API-st
Pilti, mis on juba xAI Files API-sse üles laaditud, määratakse selle identifikaatoriga, mitte URL-iga. Need kaks välja välistavad teineteist: image objekt sisaldab kas url või file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
See on loomulik valik pildi jaoks, mida kasutatakse mitmes muudatuses: seda saadetakse ainult üks kord ja see ei pea olema avalik.
Abifunktsioon
Siin on funktsioon, mis haldab mõlemat formaati automaatselt:
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}")
See funktsioon tuvastab automaatselt, kas allikas on URL või kohaliku faili tee, ja vormindab objekti vastavalt.
Praktiline harjutus
Testi mõlemat formaati sama pildi ja vihjega, et veenduda mõlema tee toimimises; tulemuspildid erinevad käivituste lõikes nagu iga genereerimise puhul:
# URL-i kaudu
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Base64 kaudu
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Peamised punktid
- Kolm sisendvormi: avalik URL, Base64 andme-URI või
file_idFiles API-st - API tagastatud ajutisi URL-e saab kasutada muutmise allikatena
- Base64 suurendab kasutajaandmemahtu ~33%
- Loo abifunktsioon mõlema formaadi automaatseks haldamiseks
- URL peab toimimiseks olema avalikult ligipääsetav