Punkt końcowy /v1/images/edits: Edytuj swoje obrazy
Na tej stronie
Zaktualizowano 2 listopada 2026 r. — Imagine. Model
grok-imagine-image-qualityzostał usunięty 2 listopada 2026 r. (jego żądania są obsługiwane przez Imagine 2.0 w jakościlow): przykłady wykorzystują terazgrok-imagine-image(Imagine 1.0) orazgrok-imagine-image-2.0(Imagine 2.0, jakośćlow,mediumlubauto). W przypadku korzystania z OpenAI SDK parametryaspect_ratio,resolutioniqualityprzesyła się przezextra_body, a edycja wymaga użycia xAI SDK lub bezpośredniego żądania HTTP.
Edycja obrazów za pomocą Grok API
Poza generowaniem, API xAI oferuje dedykowany punkt końcowy do edycji istniejących obrazów: POST /v1/images/edits. Umożliwia on modyfikację, przekształcanie lub ulepszanie obrazów poprzez opisanie pożądanych zmian w prostym poleceniu tekstowym (prompcie).
Struktura żądania edycji
Edycja działa podobnie do generowania, z jedną kluczową różnicą, która zmienia sposób tworzenia promptów: prompt opisuje modyfikację, a nie finalny obraz. Polecenie „kobieta w okularach przeciwsłonecznych“ wygeneruje całkowicie nowy obraz, podczas gdy „dodaj okulary przeciwsłoneczne“ zachowa oryginalne zdjęcie i wprowadzi zmiany tylko w tym zakresie. To najczęstszy błąd przy pierwszej próbie, który odpowiada za większość rozczarowujących rezultatów.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Dodaj czerwony kapelusz postaci",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
Dlaczego używać biblioteki requests zamiast OpenAI SDK?
Oto techniczna pułapka tej lekcji, o której warto wiedzieć, zanim zmarnujesz na to godzinę: kompatybilność z OpenAI SDK, która działa perfekcyjnie przy generowaniu, kończy się na edycji. Punkt końcowy edycji xAI korzysta z formatu JSON, podczas gdy metoda images.edit() w SDK wysyła dane jako multipart/form-data. Ta niezgodność typów treści oznacza, że do edycji musisz użyć bezpośrednio interfejsu REST za pomocą biblioteki requests.
# NIE DZIAŁA z API xAI
# client.images.edit(...) # Wysyła multipart, a nie JSON
# DZIAŁA: bezpośrednie wywołanie REST
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Parametry punktu końcowego edycji
model(wymagane):grok-imagine-image(Imagine 1.0) lubgrok-imagine-image-2.0(Imagine 2.0, który akceptuje również parametrquality)prompt(wymagane): opis modyfikacji do zastosowaniaimage: obiekt zawierający URL pojedynczego obrazu źródłowegoimages: tablica obiektów dla wielu obrazów źródłowych (wzajemnie wykluczająca się zimage)mask: obiekt zawierający URL maski obszaru do edycjin: liczba wariantów do wygenerowania (od 1 do 10)response_format:urllubb64_json
Rodzaje możliwych edycji
Poniższych pięć kategorii nie charakteryzuje się takim samym wskaźnikiem sukcesu, co warto wiedzieć przed obiecaniem konkretnego rezultatu. Dodawanie elementów i zmiana atmosfery działają bardzo dobrze, ponieważ opierają się na istniejącej treści. Usuwanie jest trudniejsze – model musi zrekonstruować to, co znajdowało się za usuniętym elementem – i tutaj maska staje się niezbędna, precyzyjnie wyznaczając obszar do przeliczenia.
- Dodawanie elementów: „Dodaj postaci okulary przeciwsłoneczne“
- Usuwanie: „Usuń tło i zastąp je białym tłem“
- Transformacja stylu: „Przekształć to zdjęcie w ilustrację akwarelową“
- Modyfikacja atmosfery: „Zmień scenę z dnia na noc“
- Korekta: „Popraw oświetlenie i zwiększ kontrast“
# Przykład: zmiana stylu obrazu
payload = {
"model": "grok-imagine-image",
"prompt": "Przekształć to zdjęcie w ilustrację w stylu komiksu franko-belgijskiego",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Ćwiczenia praktyczne
Spróbuj edytować obraz w kilku krokach. Zacznij od prostej modyfikacji, a następnie dopracuj wynik:
# Krok 1: modyfikacja tła
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Zastąp tło zachodem słońca nad oceanem",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Kluczowe wnioski
- Punkt końcowy edycji to
POST /v1/images/edits - W Pythonie używaj biblioteki
requests, a nie OpenAI SDK (niezgodność formatów) - Możesz dostarczyć do 5 obrazów źródłowych na jedno żądanie
- Prompt opisuje pożądaną modyfikację w języku naturalnym
- Dostępne są oba modele (Imagine 1.0 i Imagine 2.0) do edycji; w przypadku OpenAI SDK metoda
images.edit()nie jest obsługiwana przez xAI: użyj xAI SDK lub żądania HTTP