Przejdź do głównej treści
Polski— Wybierz język
Menu

Adresy URL tymczasowe i strategie pobierania

Lekcja 13 z 14 Zaktualizowano 3 listopada 2026 Początkujący
Na tej stronie
  1. Obsługa efemerycznych wygenerowanych obrazów
  2. Problem z tymczasowymi adresami URL
  3. Strategia 1: Natychmiastowe pobieranie
  4. Strategia 2: Użycie Base64
  5. Strategia 3: Automatyczne przechowywanie w chmurze
  6. Strategia 4: Pozwolenie xAI na przechowywanie obrazu
  7. Solidny potok z mechanizmem ponawiania
  8. Najlepsze praktyki
  9. Kluczowe wnioski

Lekcja ukończona 3 listopada 2026 r. na podstawie stron Image Generation i Imagine outputs od xAI: parametr storage_options przechowuje obraz w Files API i może utworzyć stały publiczny adres URL; dokumentacja nie precyzuje czasu życia efemerycznych adresów URL (błędy „403 lub 404“ z poprzedniej wersji tam nie występują); obrazy są domyślnie generowane w formacie JPEG. Źródła: Image Generation · Imagine outputs.

Obsługa efemerycznych wygenerowanych obrazów

Adresy URL zwracane przez API generowania i edycji obrazów są tymczasowe: dokumentacja xAI określa je jako krótkotrwałe, nie podając ich dokładnego czasu życia, i zaleca natychmiastowe pobranie lub przetworzenie obrazów. To ograniczenie bezpośrednio wpływa na sposób projektowania Twoich aplikacji.

Temp.
Adresy URL wyjścia
b64
Alternatywa trwała
+33%
Narzut rozmiaru Base64
30 dni
Przechowywanie xAI lub bez limitu

Problem z tymczasowymi adresami URL

Gdy użyjesz response_format="url" (wartość domyślna), API zwraca efemeryczny adres URL. Po nieokreślonym czasie przestaje on udostępniać obraz.

# Efemeryczny URL: pobierz niezwłocznie
response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape"
)

url = response.data[0].url

Konsekwencja: nie możesz przechowywać tych adresów URL w bazie danych i używać ich później. Musisz systematycznie pobierać obrazy.

Strategia 1: Natychmiastowe pobieranie

Najbardziej niezawodną strategią jest pobranie każdego obrazu zaraz po jego wygenerowaniu:

import urllib.request
import os
from datetime import datetime

def generate_and_save(prompt, output_dir="images"):
    """Generuje obraz i natychmiast go zapisuje."""
    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")  # Domyślnie JPEG

    urllib.request.urlretrieve(response.data[0].url, filepath)
    print(f"Obraz zapisany: {filepath}")
    return filepath

Strategia 2: Użycie Base64

Żądając odpowiedzi w formacie Base64, otrzymujesz bezpośrednio dane binarne obrazu, bez polegania na tymczasowym adresie URL:

import base64

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape",
    response_format="b64_json"
)

# Dane są bezpośrednio w odpowiedzi
image_bytes = base64.b64decode(response.data[0].b64_json)

with open("mountain.jpg", "wb") as f:  # Domyślnie JPEG
    f.write(image_bytes)

Zalety Base64

Zaletą Base64 jest jedno słowo: autonomia. Obraz trafia bezpośrednio do odpowiedzi JSON, bez polegania na tymczasowym adresie URL, który mógłby wygasnąć, zanim Twój kod go zużyje, i bez konieczności wykonywania dodatkowego żądania HTTP w celu jego pobrania – jedno okrążenie sieciowe mniej oznacza jeden punkt awarii mniej w Twoim potoku.

Wady Base64

Kompromis jest mechaniczny: kodowanie Base64 zwiększa rozmiar odpowiedzi JSON o około 33%, co kosztuje Cię potrójnie – w czasie transferu odpowiedzi API, w pamięci zużywanej przez klienta do dekodowania oraz w złożoności, jeśli manipulujesz wieloma obrazami o wysokiej rozdzielczości w tym samym żądaniu. Dla pojedynczego obrazu jest to pomijalne; dla partii dziesięciu obrazów 2k różnica staje się odczuwalna.

Strategia 3: Automatyczne przechowywanie w chmurze

W aplikacjach produkcyjnych połącz generowanie z przesyłaniem do własnego magazynu:

import boto3
import urllib.request
import tempfile

def generate_and_upload_s3(prompt, bucket, key):
    """Generuje obraz i przesyła go bezpośrednio do S3."""
    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    # Pobranie do pliku tymczasowego
    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
        urllib.request.urlretrieve(response.data[0].url, tmp.name)

        # Przesłanie do S3
        s3 = boto3.client("s3")
        s3.upload_file(tmp.name, bucket, key)

    permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
    return permanent_url

Strategia 4: Pozwolenie xAI na przechowywanie obrazu

Każde żądanie Imagine akceptuje parametr storage_options, który zapisuje wygenerowany obraz w Files API Twojego zespołu i może dodatkowo utworzyć stały publiczny adres URL do udostępniania lub osadzania. Przy użyciu SDK xAI:

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)  # Stabilny identyfikator w Files API
print(response.public_url)           # Stały publiczny adres URL

Odpowiedź zachowuje zwykły efemeryczny adres URL i dodaje dla każdego obrazu blok file_output: file_id, filename oraz, jeśli zażądasz, public_url. Tylko filename jest wymagane: bez innych opcji obraz jest przechowywany prywatnie, bez wygaśnięcia i publicznego adresu URL. expires_after (od 3600 sekund do 30 dni) harmonizuje usunięcie pliku, a public_url również akceptuje własny expires_after, który nie może przekroczyć czasu życia pliku. Zespół może mieć do 1000 aktywnych publicznych adresów URL; poza tym limitem lub w przypadku incydentu obraz nadal jest przechowywany, a odpowiedź zawiera public_url_error zamiast adresu URL. Przez REST ten sam obiekt storage_options trafia do treści żądania, również w przypadku edycji.

Solidny potok z mechanizmem ponawiania

Tymczasowe adresy URL mogą czasami zawieść podczas pobierania. Zaimplementuj mechanizm ponawiania:

import time
import urllib.request
import urllib.error

def download_with_retry(url, filepath, max_retries=3):
    """Pobiera obraz z ponawianiem w przypadku błędu."""
    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  # Wykładnicze opóźnienie
                print(f"Próba {attempt + 1} nieudana, ponawianie za {wait_time}s...")
                time.sleep(wait_time)
            else:
                print(f"Niepowodzenie po {max_retries} próbach: {e}")
                return False

Najlepsze praktyki

Cała dyscyplina wynika z jednego faktu: adresy URL są tymczasowe. Pobieranie musi więc następować niezwłocznie po generowaniu, w tym samym przepływie kodu – każda minuta przerwy to okno, w którym obraz może stać się nie do odzyskania. Z tego samego powodu tymczasowy adres URL nigdy nie powinien być przechowywany w bazie danych jako trwałe odniesienie: będzie martwy przy następnym odwołaniu, a to rodzaj błędu, który ujawnia się tylko w produkcji, dni później. W aplikacjach krytycznych, gdzie niezawodność jest priorytetem, obejdź problem, używając b64_json, które dostarcza obraz w odpowiedzi, lub storage_options, które przechowuje go w xAI ze stabilnym identyfikatorem.

Samo pobieranie zasługuje na traktowanie jak normalna operacja sieciowa: ponawianie z wykładniczym opóźnieniem, aby pochłonąć przejściowe awarie, nazewnictwo plików według znacznika czasu lub unikalnego identyfikatora, aby uniknąć kolizji przy równoległym uruchamianiu wielu generowań. Na koniec loguj metadane – monit, model, parametry – do każdego zapisanego obrazu: za sześć miesięcy, gdy będziesz potrzebować wygenerować wizualizację „taką jak tamta, ale w 2k“, ten log będzie bezcenny.

Kluczowe wnioski

  • Adresy URL wyjścia są tymczasowe: pobieraj niezwłocznie
  • Format b64_json pozwala uniknąć problemu z efemerycznym adresem URL
  • Base64 zwiększa rozmiar odpowiedzi o około 33%
  • Zaimplementuj ponawianie z wykładniczym opóźnieniem dla zwiększenia odporności
  • W środowisku produkcyjnym przesyłaj dane do trwałego magazynu (S3, GCS) lub pozwól xAI przechowywać obraz za pomocą storage_options