Źródła obrazów: adres URL i Base64
Na tej stronie
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_idpliku znajdującego się w Files API, jako wyłączną alternatywę dlaurl. Ź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_idz 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ć