Képfelhasználási források: URL és Base64
Ezen az oldalon
Frissítve: 2026. november 3. Az Image Editing oldal és az xAI Images API referenciája alapján: a forráskép megadható a Files API-ban lévő fájl
file_idazonosítójával is, aurlkizárólagos alternatívájaként. Források: Image Editing · Images API.
Képek biztosítása a szerkesztési végponthoz
A szerkesztési végpont három formátumban fogad el forrásképeket: nyilvános URL-cím, Base64 Data URI, vagy egy már az xAI Files API-ra feltöltött fájl file_id azonosítója. Mindegyiknek megvan a maga felhasználási területe; ezek elsajátításával rugalmas szerkesztési folyamatokat építhetsz fel.
URL formátum
Az URL formátum a legkényelmesebb lehetőség, amennyiben a kép már elérhető online: nincs szükség kódolásra, a hasznos adat mérete kicsi, és a kérés olvasható marad a naplókban. Itt a kulcsfontosságú megkötés a nyilvánosság: a képnek elérhetőnek kell lennie az xAI szerverei számára munkamenet vagy token nélkül.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
URL korlátozások
- Az URL-nek nyilvánosan elérhetőnek kell lennie (nincs hitelesítéssel védett link)
- A támogatott formátumok: JPEG, PNG és WebP
- A képnek gyorsan elérhetőnek kell lennie (kerüld a lassú szervereket)
Az API által visszaadott kimeneti URL-ek használata
Ez teszi lehetővé a többlépéses szerkesztés gyakorlati megvalósítását: az egyik szerkesztés kimenete lesz a következő bemenete, anélkül, hogy valaha is letöltenéd a képet a helyi gépedre. Van azonban egy csavar: ezek az URL-ek lejárnak, így a láncolatnak egy menetben kell lefutnia. Ha az időben elszórt munkafolyamatot végzel, töltsd le a képet minden lépés között.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Kép generálása
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"]
# A generált kép szerkesztése
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 formátum
A helyileg tárolt vagy dinamikusan generált képekhez használd a Base64 Data URI formátumot:
import base64
# Helyi kép beolvasása
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
}
}
Mikor használj Base64-et?
A kritérium egyszerű: a Base64 akkor szükséges, amikor egy nyilvános URL használata felesleges kitérő lenne. Ez vonatkozik azokra a helyi képekre, amelyek sehol sincsenek hosztolva – a szerverre való feltöltésük csak azért, hogy az API elérje őket, plusz lépést és késleltetést jelent érték nélkül. Ugyanez igaz az alkalmazásod által memóriában generált képekre is: egy menet közben előállított diagram, egy renderelésről készült képernyőkép vagy egy dinamikusan összeállított bélyegkép soha nem érinti a lemezt. A Base64 egy adatvédelmi aggályt is kezel: a kérés törzsébe kódolt kép soha nem válik láthatóvá egy nyilvános szerveren, még átmenetileg sem –, és leegyszerűsíti az architektúrát: egy automatizált folyamat, amely összeláncolja a generálást, szerkesztést és mentést, végig működik köztes hosztolás nélkül, amit ki kellene építeni, biztosítani és takarítani.
Figyeld a méretet
A Base64 körülbelül egyharmadával növeli a hasznos adat méretét, ami egy bélyegképnél elhanyagolható, de több megabájtos fotóknál jelentőssé válik – hosszabb feltöltési idők és a kérés méretkorlátjának túllépésének kockázata. Az ökölszabály: ha a kép már elérhető online, használd az URL-t; ha helyi, a Base64 egyszerűbb, mint csak emiatt hosztolni azt.
Harmadik lehetőség: Fájl a Files API-ból
Egy már az xAI Files API-ra feltöltött képet az azonosítójával adsz meg, URL-cím helyett. A két mező kölcsönösen kizárja egymást: egy image objektum vagy url-t, vagy file_id-t tartalmaz.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Ez a természetes választás olyan képeknél, amelyeket több szerkesztés során is újrahasználsz: csak egyszer kell elküldeni, és nem kell nyilvánosnak lennie.
Segédfüggvény
Íme egy függvény, amely mindkét formátumot automatikusan kezeli:
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}")
Ez a függvény automatikusan észleli, hogy a forrás egy URL vagy egy helyi fájl elérési útja, és ennek megfelelően formázza az objektumot.
Gyakorlati feladat
Teszteld mindkét formátumot ugyanazzal a képpel és prompttal, hogy ellenőrizd: mindkét út működik; az eredményül kapott képek futtatásonként változni fognak, mint bármely generálás esetén:
# URL-en keresztül
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Base64-en keresztül
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Főbb megállapítások
- Három bemeneti forma: nyilvános URL, Base64 Data URI vagy
file_ida Files API-ból - Az API által visszaadott ideiglenes URL-ek szerkesztési forrásként szolgálhatnak
- A Base64 körülbelül 33%-kal növeli a hasznos adat méretét
- Készíts segédfüggvényt mindkét formátum automatikus kezelésére
- Az URL-nek nyilvánosan elérhetőnek kell lennie a működéshez