Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Zdroje obrázků: URL a Base64

Lekce 6 z 14 Aktualizováno 3. listopadu 2026 Začátečník
Na této stránce
  1. Poskytování obrázků koncovému bodu pro úpravy
  2. Formát URL
  3. Formát datového URI Base64
  4. Třetí možnost: Soubor z Files API
  5. Pomocná funkce
  6. Praktické cvičení
  7. Klíčové poznatky

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_id souboru v Files API jako výhradní alternativu k url. 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_id z 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