Dočasné URL adresy a strategie stahování
Na této stránce
Lekce dokončena 3. listopadu 2026 na základě stránek Image Generation a Imagine outputs od xAI: parametr
storage_optionsuchovává obrázek v Files API a může vytvořit trvalou veřejnou URL adresu; dokumentace nespecifikuje životnost efemérních URL adres (chyby „403 nebo 404“ z předchozí verze se zde neobjevují); výstupní obrázky jsou ve výchozím nastavení ve formátu JPEG. Zdroje: Image Generation · Imagine outputs.
Práce s efemérními generovanými obrázky
URL adresy vrácené API pro generování a úpravu obrázků jsou dočasné: dokumentace xAI je popisuje jako krátkodobé bez upřesnění jejich životnosti a žádá vás, abyste obrázky okamžitě stáhli nebo zpracovali. Toto omezení přímo ovlivňuje způsob, jakým navrhujete své aplikace.
Problém s dočasnými URL adresami
Když použijete response_format="url" (výchozí nastavení), API vrátí efemérní URL adresu. Po neurčité době přestane obrázek obsluhovat.
# Efemérní URL: stáhnout bez prodlení
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape"
)
url = response.data[0].url
Důsledek: tyto URL adresy nemůžete ukládat do databáze a později je znovu používat. Obrázky musíte systematicky stahovat.
Strategie 1: Okamžité stažení
Nejspolehlivější strategií je stáhnout každý obrázek hned po jeho vygenerování:
import urllib.request
import os
from datetime import datetime
def generate_and_save(prompt, output_dir="images"):
"""Vygeneruje obrázek a okamžitě jej uloží."""
os.makedirs(output_dir, exist_ok=True)
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filepath = os.path.join(output_dir, f"gen_{timestamp}.jpg") # Výchozí formát JPEG
urllib.request.urlretrieve(response.data[0].url, filepath)
print(f"Obrázek uložen: {filepath}")
return filepath
Strategie 2: Použití Base64
Pokud požádáte o odpověď ve formátu Base64, obdržíte binární data obrázku přímo, aniž byste se museli spoléhat na dočasnou URL adresu:
import base64
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape",
response_format="b64_json"
)
# Data jsou přímo v odpovědi
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("mountain.jpg", "wb") as f: # Výchozí formát JPEG
f.write(image_bytes)
Výhody Base64
Výhoda Base64 se dá shrnout jedním slovem: autonomie. Obrázek dorazí přímo v odpovědi JSON, aniž byste se museli spoléhat na dočasnou URL adresu, která by mohla vypršet dříve, než ji váš kód zpracuje, a bez nutnosti dalšího HTTP požadavku pro jeho stažení – jedna síťová komunikace méně znamená jeden bod selhání méně ve vašem pipeline.
Nevýhody Base64
Kompromis je mechanický: kódování Base64 zvětší odpověď JSON přibližně o 33 %, což vás stojí trojnásobně – v čase přenosu odpovědi API, v paměti spotřebované klientem k dekódování a ve složitosti, pokud manipulujete s více obrázky s vysokým rozlišením v rámci jednoho požadavku. U jednotlivého obrázku je to zanedbatelné; u dávky deseti obrázků o rozlišení 2k se rozdíl stane hmatatelným.
Strategie 3: Automatické cloudové úložiště
Pro produkční aplikace zkombinujte generování s nahráním do vašeho úložiště:
import boto3
import urllib.request
import tempfile
def generate_and_upload_s3(prompt, bucket, key):
"""Vygeneruje obrázek a přímo jej nahraje na S3."""
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
# Stažení do dočasného souboru
with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
urllib.request.urlretrieve(response.data[0].url, tmp.name)
# Nahrání na S3
s3 = boto3.client("s3")
s3.upload_file(tmp.name, bucket, key)
permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
return permanent_url
Strategie 4: Nechání uložení obrázku na xAI
Každý požadavek Imagine přijímá parametr storage_options, který uloží vytvořený obrázek do Files API vašeho týmu a může navíc vytvořit trvalou veřejnou URL adresu pro sdílení nebo vložení. Pomocí xAI SDK:
import os
import xai_sdk
client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client_xai.image.sample(
prompt="A mountain landscape at sunrise",
model="grok-imagine-image-2.0",
storage_options={"filename": "mountain.jpg", "public_url": True},
)
print(response.file_output.file_id) # Stabilní identifikátor v Files API
print(response.public_url) # Trvalá veřejná URL adresa
Odpověď zachovává obvyklou efemérní URL adresu a pro každý obrázek přidá blok file_output: file_id, filename a pokud je vyžádáno, public_url. Povinný je pouze filename: bez dalších možností je obrázek uložen soukromě, bez vypršení platnosti nebo veřejné URL adresy. Parametr expires_after (od 3 600 sekund do 30 dní) naplánuje smazání souboru a public_url také přijímá vlastní expires_after, který nemůže překročit životnost souboru. Tým může mít až 1 000 aktivních veřejných URL adres; pokud je tento limit překročen nebo dojde k incidentu, je obrázek stále uložen a odpověď místo URL adresy obsahuje public_url_error. Prostřednictvím REST jde stejný objekt storage_options do těla požadavku, a to i pro úpravu.
Robustní pipeline s opakováním
Dočasné URL adresy mohou při stahování někdy selhat. Implementujte mechanismus opakování:
import time
import urllib.request
import urllib.error
def download_with_retry(url, filepath, max_retries=3):
"""Stáhne obrázek s opakováním v případě chyby."""
for attempt in range(max_retries):
try:
urllib.request.urlretrieve(url, filepath)
return True
except urllib.error.URLError as e:
if attempt < max_retries - 1:
wait_time = 2 ** attempt # Exponenciální backoff
print(f"Pokus {attempt + 1} selhal, opakování za {wait_time}s...")
time.sleep(wait_time)
else:
print(f"Selhání po {max_retries} pokusech: {e}")
return False
Osvědčené postupy
Veškerá disciplína vychází z jediného faktu: URL adresy jsou dočasné. Stahování proto musí následovat okamžitě po generování ve stejném toku kódu – každá minuta prodlevy je oknem, během kterého se obrázek může stát neobnovitelným. Ze stejného důvodu nikdy neukládejte dočasnou URL adresu do databáze jako trvalou referenci: při dalším dotazu bude nefunkční a toto je typ chyby, která se projeví až v produkci, o dny později. V kritických aplikacích, kde je na prvním místě spolehlivost, obejděte tento problém pomocí b64_json, který doručí obrázek v odpovědi, nebo pomocí storage_options, který jej uchová na xAI se stabilním identifikátorem.
Samotné stahování si zaslouží zacházení jako běžná síťová operace: opakování s backoffem pro absorpci přechodných selhání, pojmenování souborů podle časového razítka nebo unikátního identifikátoru, aby se předešlo kolizím při paralelním spouštění více generování. Nakonec zaznamenávejte metadata – prompt, model, parametry – ke každému uloženému obrázku: za šest měsíců, když budete potřebovat znovu vygenerovat vizuál „jako tenhle, ale ve 2k“, bude tento záznam k nezaplacení.
Klíčové poznatky
- Výstupní URL adresy jsou dočasné: stahujte je okamžitě
- Formát
b64_jsonřeší problém s efemérními URL adresami - Base64 zvětšuje velikost odpovědi přibližně o 33 %
- Pro robustnost implementujte opakování s exponenciálním backoffem
- V produkci nahrávejte do trvalého úložiště (S3, GCS) nebo nechte obrázek uložit na xAI pomocí
storage_options