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

Źródła obrazów: adres URL i Base64

Lekcja 6 z 14 Zaktualizowano 3 listopada 2026 Początkujący
Na tej stronie
  1. Przekazywanie obrazów do punktu końcowego edycji
  2. Format adresu URL
  3. Format identyfikatora URI danych Base64
  4. Trzecia opcja: plik z Files API
  5. Funkcja użytkowa
  6. Ćwiczenia praktyczne
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Na podstawie strony Image Editing oraz dokumentacji referencyjnej xAI Images API: obraz źródłowy można również określić, używając file_id pliku znajdującego się w Files API, jako wyłączną alternatywę dla url. Źródła: Image Editing · Images API.

Przekazywanie obrazów do punktu końcowego edycji

Punkt końcowy edycji akceptuje obrazy źródłowe w trzech formach: publiczny adres URL, identyfikator URI danych Base64 lub file_id pliku już przesłanego do xAI Files API. Każda z nich ma swoje zastosowania; opanowanie ich pozwoli Ci budować elastyczne potoki edycji.

Format adresu URL

Format adresu URL jest najwygodniejszą opcją, pod warunkiem że obraz jest już dostępny online: nic do kodowania, malutki ładunek danych, a żądanie pozostaje czytelne w dziennikach. Kluczowym ograniczeniem jest tutaj publiczny dostęp – obraz musi być możliwy do pobrania przez serwery xAI bez sesji ani tokena.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a gold frame around this image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

Ograniczenia dotyczące adresu URL

  • Adres URL musi być publicznie dostępny (brak linków chronionych uwierzytelnianiem)
  • Obsługiwane formaty to JPEG, PNG i WebP
  • Obraz musi być szybko dostępny (unikaj wolnych serwerów)

Wykorzystywanie adresów URL wyjściowych z API

To właśnie sprawia, że wieloetapowa edycja staje się praktyczna: wynik jednej edycji staje się wejściem dla kolejnej, bez konieczności pobierania obrazu na lokalny komputer. Jest jednak jeden haczyk – te adresy URL wygasają, więc łańcuch musi zostać wykonany natychmiast. W przypadku przepływu pracy rozłożonego w czasie, pobierz obraz między każdym krokiem.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

# Generowanie obrazu
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"]

# Edycja wygenerowanego obrazu
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()

Format identyfikatora URI danych Base64

W przypadku obrazów przechowywanych lokalnie lub generowanych dynamicznie użyj formatu identyfikatora URI danych Base64:

import base64

# Odczyt lokalnego obrazu
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
    }
}

Kiedy używać Base64?

Kryterium jest proste: Base64 jest konieczne zawsze wtedy, gdy użycie publicznego adresu URL byłoby niepotrzebną objazdową drogą. Dotyczy to obrazów lokalnych, które nie są nigdzie hostowane – przesyłanie ich na serwer tylko po to, by API mogło je uzyskać, dodaje krok i opóźnienie bez żadnej wartości. Dotyczy to również obrazów generowanych w pamięci przez Twoją aplikację: wykres tworzony na bieżąco, zrzut ekranu renderowania czy dynamicznie komponowana miniatura nigdy nie muszą dotknąć dysku. Base64 rozwiązuje również problem prywatności – obraz zakodowany w treści żądania nigdy nie jest udostępniany na publicznym serwerze, nawet tymczasowo – i upraszcza architekturę: zautomatyzowany potok łączący generowanie, edycję i zapisywanie działa od początku do końca bez konieczności provisioningowania, zabezpieczania i czyszczenia pośredniego hostingu.

Uważaj na rozmiar

Base64 zwiększa rozmiar ładunku danych o około jedną trzecią, co jest pomijalne w przypadku miniatury, ale staje się istotne przy zdjęciach wielomegabajtowych – dłuższy czas przesyłania i ryzyko przekroczenia limitów rozmiaru żądania. Zasada jest prosta: jeśli obraz jest już dostępny online, użyj adresu URL; jeśli jest lokalny, Base64 jest prostsze niż hostowanie go tylko na tę okazję.

Trzecia opcja: plik z Files API

Obraz już przesłany do xAI Files API określa się za pomocą jego identyfikatora, zamiast adresu URL. Dwa pola wzajemnie się wykluczają: obiekt image zawiera albo url, albo file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"file_id": "file_abc123"}
}

Jest to naturalny wybór dla obrazu wykorzystywanego wielokrotnie w różnych edycjach: jest wysyłany tylko raz i nie musi być publiczny.

Funkcja użytkowa

Oto funkcja, która automatycznie obsługuje oba formaty:

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}")

Funkcja ta automatycznie wykrywa, czy źródłem jest adres URL, czy ścieżka do pliku lokalnego, i odpowiednio formatuje obiekt.

Ćwiczenia praktyczne

Przetestuj oba formaty, używając tego samego obrazu i monitu, aby sprawdzić, czy obie ścieżki działają; wynikowe obrazy będą się różnić przy każdym uruchomieniu, tak jak w przypadku każdego generowania:

# Poprzez adres URL
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Poprzez Base64
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": prepare_image_source("paysage.jpg")
}

Kluczowe wnioski

  • Trzy formy wejścia: publiczny adres URL, identyfikator URI danych Base64 lub file_id z Files API
  • Tymczasowe adresy URL zwracane przez API mogą służyć jako źródła do edycji
  • Base64 zwiększa rozmiar ładunku danych o ~33%
  • Stwórz funkcję użytkową do automatycznej obsługi obu formatów
  • Adres URL musi być publicznie dostępny, aby działać