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

Dočasné URL adresy a strategie stahování

Lekce 13 z 14 Aktualizováno 3. listopadu 2026 Začátečník
Na této stránce
  1. Práce s efemérními generovanými obrázky
  2. Problém s dočasnými URL adresami
  3. Strategie 1: Okamžité stažení
  4. Strategie 2: Použití Base64
  5. Strategie 3: Automatické cloudové úložiště
  6. Strategie 4: Nechání uložení obrázku na xAI
  7. Robustní pipeline s opakováním
  8. Osvědčené postupy
  9. Klíčové poznatky

Lekce dokončena 3. listopadu 2026 na základě stránek Image Generation a Imagine outputs od xAI: parametr storage_options uchová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.

Doč.
Výstupní URL
b64
Trvalá alternativa
+33 %
Režie velikosti Base64
30 dní
Úložiště xAI, nebo neomezeně

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