Zdroje obrázkov: URL a Base64
Na tejto strane
Aktualizované 3. novembra 2026. Na základe stránky Image Editing a referencie xAI Images API: zdrojový obrázok môžete zadať aj pomocou
file_idsúboru v Files API ako výhradnú alternatívu kurl. Zdroje: Image Editing · Images API.
Poskytovanie obrázkov koncovému bodu pre úpravy
Koncový bod pre úpravy (edit endpoint) prijíma zdrojové obrázky v troch formách: ako verejnú URL, ako Base64 Data URI alebo ako file_id súboru, ktorý ste už nahrali do xAI Files API. Každá možnosť má svoje využitie; ich ovládnutie vám umožní budovať flexibilné pipeline na úpravu obrázkov.
Formát URL
Formát URL je najpohodlnejšou voľbou, pokiaľ je obrázok už online: nič netreba kódovať, dátový balík je malý a požiadavka zostáva čitateľná v logoch. Kľúčovým obmedzením je tu verejný prístup – obrázok musia byť servery xAI schopné stiahnuť bez relácie alebo tokenu.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Obmedzenia URL
- URL musí byť verejne dostupná (žiadne odkazy chránené overením)
- Podporované formáty sú JPEG, PNG a WebP
- Obrázok musí byť rýchlo dostupný (vyhýbajte sa pomalým serverom)
Používanie výstupných URL z API
Práve toto robí viacprůchodové úpravy praktickými: výstup jednej úpravy sa stáva vstupom pre ďalšiu, pričom obrázok nikdy nemusíte sťahovať na svoj lokálny stroj. Existuje však jedno upozornenie – tieto URL vypršia, preto musí reťazec prebehnúť naraz. Ak máte workflow rozložené v čase, stiahnite obrázok medzi jednotlivými krokmi.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Generovanie obrázka
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"]
# Úprava vygenerovaného obrázka
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()
Formát Base64 Data URI
Pre obrázky uložené lokálne alebo generované dynamicky použite formát Base64 Data URI:
import base64
# Čítanie lokálneho obrázka
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
}
}
Kedy používať Base64?
Kritérium je jednoduché: Base64 je nevyhnutný vždy, keď by použitie verejnej URL bolo zbytočnou oklikou. Týka sa to lokálnych obrázkov, ktoré nie sú nikde hostované – ich nahratie na server len preto, aby boli dostupné pre API, pridáva krok a oneskorenie bez pridanej hodnoty. Platí to aj pre obrázky generované v pamäti vašej aplikácie: graf vytvorený za behu, snímka obrazovky z renderu alebo dynamicky zostavená miniatúra sa nikdy nemusia dotknúť disku. Base64 rieši aj otázku súkromia – obrázok zakódovaný v tele požiadavky nie je nikdy vystavený na verejnom serveri, ani len dočasne – a zjednodušuje architektúru: automatizovaný pipeline spájajúci generovanie, úpravy a ukladanie funguje od začiatku do konca bez potreby dočasného hostovania, ktoré by ste museli nastavovať, zabezpečovať a následne čistiť.
Sledujte veľkosť
Base64 zväčší dátový balík približne o tretinu, čo je pri miniatúre zanedbateľné, ale pri niekoľkomegabajtovej fotografii sa to stáva významným – dlhšie časy nahrávania a riziko prekročenia limitov veľkosti požiadavky. Zlaté pravidlo znie: ak je obrázok už dostupný online, použite URL; ak je lokálny, Base64 je jednoduchšie riešenie než ho len pre túto príležitosť hostovať.
Tretia možnosť: Súbor z Files API
Obrázok, ktorý ste už nahrali do xAI Files API, zadáte pomocou jeho identifikátora namiesto URL. Obe polia sa vzájomne vylučujú: objekt image obsahuje buď url, alebo file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Toto je prirodzená voľba pre obrázok, ktorý znovu používate pri viacerých úpravách: odošle sa len raz a nemusí byť verejný.
Pomocná funkcia
Tu je funkcia, ktorá automaticky spracuje oba formáty:
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áto funkcia automaticky zistí, či je zdroj URL alebo cesta k lokálnemu súboru, a podľa toho naformátuje objekt.
Praktické cvičenie
Otestujte oba formáty s rovnakým obrázkom a promptom, aby ste overili, že obe cesty fungujú; výsledné obrázky sa budú pri každom spustení líšiť, ako pri každom generovaní:
# Cez URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Cez Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Kľúčové poznatky
- Tri formy vstupu: verejná URL, Base64 Data URI alebo
file_idz Files API - Dočasné URL vrátené API môžu slúžiť ako zdroje pre úpravy
- Base64 zväčší veľkosť dátového balíka približne o 33 %
- Vytvorte si pomocnú funkciu na automatické spracovanie oboch formátov
- URL musí byť verejne dostupná, aby fungovala