Zdroje obrázků: URL a Base64
Na této stránce
Aktualizováno 3. listopadu 2026. Na základě stránky Image Editing a reference k xAI Images API lze zdrojový obrázek určit také pomocí
file_idsouboru v Files API jako výhradní alternativu kurl. Zdroje: Image Editing · Images API.
Poskytování obrázků koncovému bodu pro úpravy
Koncový bod pro úpravy přijímá zdrojové obrázky ve třech formách: jako veřejnou URL, jako datové URI ve formátu Base64 nebo jako file_id souboru již nahraného do xAI Files API. Každá z nich má své využití; jejich zvládnutí ti umožní budovat flexibilní pipeline pro úpravy.
Formát URL
Formát URL je nejpohodlnější volbou, pokud je obrázek již online: nic není třeba kódovat, datový tok je malý a požadavek zůstává čitelný v logách. Klíčovým omezením zde je veřejnost – obrázek musí být servery xAI získatelný bez relace nebo tokenu.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Omezení URL
- URL musí být veřejně přístupná (žádné odkazy chráněné ověřováním)
- Podporované formáty jsou JPEG, PNG a WebP
- Obrázek musí být rychle dostupný (vyhni se pomalým serverům)
Používání výstupních URL z API
Právě to činí víceprůchodové úpravy praktickými: výstup jedné úpravy se stává vstupem pro další, aniž by bylo nutné obrázek stahovat na lokální stroj. Existuje však jedno upozornění – tyto URL vyprší, takže řetězec musí proběhnout v jednom tahu. Pro pracovní postup rozložený v čase si jej mezi jednotlivými kroky stáhni.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Vygenerování obrázku
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ázku
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 datového URI Base64
Pro obrázky uložené lokálně nebo generované dynamicky použij formát datového URI Base64:
import base64
# Čtení lokálního obrázku
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
}
}
Kdy použít Base64?
Kritérium je jednoduché: Base64 je nezbytný vždy, když by použití veřejné URL bylo zbytečnou oklikou. To platí pro lokální obrázky, které nejsou nikde hostovány – jejich nahrání na server pouze proto, aby byly přístupné API, přidává krok a prodlevu bez přidané hodnoty. Platí to také pro obrázky generované v paměti tvou aplikací: graf vytvořený za běhu, snímek obrazovky z renderu nebo dynamicky složená miniatura se nikdy nemusí dotknout disku. Base64 také řeší problém soukromí – obrázek zakódovaný v těle požadavku není nikdy vystaven na veřejném serveru, ani dočasně – a zjednodušuje architekturu: automatizovaná pipeline spojující generování, úpravy a ukládání funguje od začátku do konce bez nutnosti zřizovat, zabezpečovat a čistit průběžné hostování.
Hlídej si velikost
Base64 zvětší datový tok přibližně o třetinu, což je u miniatury zanedbatelné, ale u fotografie o velikosti několika megabajtů se to stává významným – delší časy nahrávání a riziko překročení limitů velikosti požadavku. Obecné pravidlo zní: pokud je obrázek již dostupný online, použij URL; pokud je lokální, Base64 je jednodušší než jej jen pro tuto příležitost hostovat.
Třetí možnost: Soubor z Files API
Obrázek již nahraný do xAI Files API se určuje svým identifikátorem místo URL. Obě pole se vzájemně vylučují: objekt image obsahuje buď url, nebo file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Toto je přirozená volba pro obrázek znovu používaný při více úpravách: je odeslán pouze jednou a nemusí být veřejný.
Pomocná funkce
Zde je funkce, která automaticky zpracovává 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}")
Tato funkce automaticky detekuje, zda je zdroj URL nebo cesta k lokálnímu souboru, a odpovídajícím způsobem naformátuje objekt.
Praktické cvičení
Otestuj oba formáty se stejným obrázkem a promptem, abys ověřil, že obě cesty fungují; výsledné obrázky se budou lišit od spuštění ke spuštění, jako u jakékoli generace:
# Pomocí URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Pomocí Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Klíčové poznatky
- Tři formy vstupu: veřejná URL, datové URI Base64 nebo
file_idz Files API - Dočasné URL vrácené API mohou sloužit jako zdroje pro úpravy
- Base64 zvětšuje velikost datového toku přibližně o 33 %
- Vytvoř pomocnou funkci pro automatické zpracování obou formátů
- URL musí být veřejně přístupná, aby fungovala