OpenAI Images Edits API – rejestracja i użycie

Usługa edycji obrazów OpenAI pozwala przesłać dowolną liczbę obrazów i poleceń, a następnie otrzymać zmodyfikowane obrazy. Obecnie interfejs obsługuje modele dall-e-2, gpt-image-1, najnowszy gpt-image-2, a także modele z serii nano-banana / nano-banana-2 / nano-banana-pro dostępne przez ten sam interfejs. Niniejsza dokumentacja opisuje proces korzystania z OpenAI Images Edits API, dzięki któremu możemy łatwo korzystać z oficjalnych funkcji edycji obrazów OpenAI.

Proces rejestracji

Aby korzystać z OpenAI Images Edits API, najpierw należy przejść na stronę OpenAI Images Edits API i kliknąć przycisk „Acquire”, aby uzyskać niezbędne poświadczenia do zapytań:

Jeśli nie jesteś zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie możesz się zarejestrować i zalogować. Po zalogowaniu zostaniesz automatycznie przekierowany z powrotem na tę stronę. Przy pierwszym wniosku otrzymujesz darmowy limit, który pozwala bezpłatnie korzystać z API.

Model GPT-Image-2

gpt-image-2 w scenariuszach edycji obrazów oferuje znaczną poprawę w porównaniu do gpt-image-1:

Stabilniejsze zachowanie struktury: zmiana skórek, kolorów czy tła niemal nie narusza układu i kompozycji oryginalnego obrazu.
Dokładniejsze zachowanie tekstu: obrazy zawierające tekst, takie jak infografiki, plakaty, menu, po edycji zachowują czytelność tekstu.
Obsługa przesyłania URL bezpośrednio: oprócz tradycyjnego przesyłania plików w formacie multipart/form-data, gpt-image-2 dodatkowo obsługuje przekazywanie URL obrazu w formacie JSON, co eliminuje konieczność pobierania obrazów lokalnie i jest idealne do integracji po stronie serwera.
Obsługa wysokiej rozdzielczości: można przesłać obraz 1K i za pomocą parametru size zażądać wyjścia w 2K lub 4K; model podczas edycji jednocześnie dokonuje powiększenia.

Obsługiwane wartości `size` i poziomy rozliczeń

Ograniczenia parametru size w interfejsie edycji są takie same jak w interfejsie generowania — gpt-image-2 akceptuje size jako auto, pusty lub w formacie WIDTHxHEIGHT. Każda inna forma zwróci błąd 400. Rozliczenie odbywa się na dwóch poziomach, niezależnie od rozdzielczości oryginału, tylko na podstawie wartości size:

1K – standardowa cena: dowolny z rekomendowanych rozmiarów 1K z tabeli poniżej lub popularne aliasy 1K (1254x1254, 1672x941, 941x1672).
Inne poziomy (1,5×): obejmują rekomendowane rozmiary 2K / 4K oraz dowolne niestandardowe WIDTHxHEIGHT.

Obowiązują też ograniczenia upstream: szerokość i wysokość muszą być wielokrotnością 16, dłuższy bok ≤ 3840, całkowita liczba pikseli ≤ 8 294 400.

Proporcje	1K (standard)	2K rekomendowane (×1,5)	4K rekomendowane (×1,5)
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

Przykład: jeśli oryginał ma rozmiar 1024x1024 i size ustawimy na 2048x2048, model przerysuje obraz zgodnie z poleceniem i zwróci obraz 2K, rozliczając go na poziomie „inne”; jeśli size to 3840x2160, otrzymamy obraz 4K w orientacji poziomej, również rozliczany jako „inne”; jeśli size to auto lub pominiemy ten parametr, rozliczenie nastąpi według ceny standardowej 1K.

O parametrze n Interfejs edycji gpt-image-2 nie obsługuje n > 1: ten parametr jest ignorowany, niezależnie czy podamy n=1 czy n=10, w odpowiedzi zwrócony zostanie tylko jeden obraz i rozliczony jako jeden. Jeśli potrzebujesz wielu wariantów, musisz wykonać wiele równoległych zapytań. To samo ograniczenie dotyczy modeli gpt-image-1 / gpt-image-1.5 oraz serii nano-banana. Jedynie dall-e-2 natywnie wspiera n > 1.

Poniżej przedstawiamy dwa przykłady pokazujące możliwości edycji gpt-image-2.

Metoda wywołania 1: JSON + URL obrazu (zalecane)

Wysyłamy zapytanie jako application/json, w polu image podając URL obrazu, który model pobierze i edytuje zgodnie z prompt. Na przykład, poniższy obraz to infografika wygenerowana przez gpt-image-2:

Chcemy zmienić ją na tryb nocny. Wywołanie wygląda tak:

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

Lub w Pythonie:

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Odpowiedź:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

Edytowany obraz:

Widać, że struktura modułów, podział informacji i typografia zostały zachowane, zmieniono jedynie schemat kolorów na ciemny.

Wskazówka: pole image może przyjmować tablicę URL-i, np. "image": ["url1", "url2", "url3"], maksymalnie do 16 obrazów, co pozwala modelowi korzystać z wielu referencji podczas edycji.

Metoda wywołania 2: JSON + wiele obrazów referencyjnych

gpt-image-2 pozwala na jednoczesne użycie wielu obrazów referencyjnych do wygenerowania wyniku, np. połączenie kilku zdjęć produktów w jeden kosz prezentowy:

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

Przykład scenariusza: zmiana stylu z zachowaniem struktury

Inny przykład: zamiana drewnianej półki na nowoczesną, ale z zachowaniem dokładnej liczby i układu książek na każdej półce. Oryginalny obraz (drewniana półka wygenerowana przez gpt-image-2):

Wywołanie:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

Wynik edycji (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Widać, że styl i otoczenie zostały całkowicie zmienione zgodnie z poleceniem, ale liczba książek na każdej półce (1 / 3 / 7) pozostała nienaruszona, a na górnej półce dodano małą sukulentę.

Metoda wywołania 3: multipart/form-data (kompatybilne z OpenAI SDK)

Jeśli korzystasz z oficjalnego OpenAI Python SDK, możesz nadal używać tradycyjnego przesyłania plików multipart/form-data, wystarczy zmienić model na gpt-image-2:

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

Przed użyciem SDK należy ustawić dwa zmienne środowiskowe: OPENAI_BASE_URL na https://api.xhuoapi.ai/v1/openai oraz OPENAI_API_KEY na uzyskany token:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

Modele z serii Nano Banana

Modele z serii nano-banana również obsługują endpoint /openai/images/edits; wystarczy zmienić model na dowolny z poniższej tabeli.

Model	Koszt (Credits / wywołanie)	Zastosowanie
`nano-banana`	0.14	Standardowa edycja obrazów, najszybsza i najtańsza
`nano-banana-2`	0.28	Wyraźna poprawa jakości i detali
`nano-banana-pro`	0.35	Flagowy model serii, najlepsze zachowanie struktury, tekstu i stylu

Ważne: obsługiwane parametry Nano Banana korzysta z warstwy adaptacyjnej zgodnej z protokołem OpenAI i obsługuje tylko parametry: model, prompt, image.

image można przesłać jako plik w multipart/form-data (wewnętrznie konwertowany do data:<mime>;base64,... dla upstream) lub jako URL w polu formularza.

Nie obsługuje parametrów mask, n, size, response_format – jeśli zostaną podane, zostaną zignorowane.

Odpowiedź ma format zgodny z OpenAI (data[].url), ale created jest zawsze 0, nie zwracany jest b64_json, a revised_prompt jest zawsze taki sam jak oryginalny prompt.

Wywołanie przez formularz + URL obrazu

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Przykładowa odpowiedź:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

Edytowany obraz:

Wywołanie przez formularz + plik lokalny

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

Asynchroniczne wywołanie zwrotne (callback)

Mechanizm asynchronicznego callback callback_url działa również z nano-banana, proces wywołania jest identyczny jak dla innych modeli, opisany w sekcji Asynchroniczne wywołanie zwrotne.

Podstawowe użycie

Poniżej przykład wywołania CURL:

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

Przy pierwszym użyciu tego interfejsu należy podać co najmniej cztery elementy: authorization (wybierane z listy rozwijanej), model (wybór modelu OpenAI, tutaj mamy 1 model, szczegóły w dokumentacji modeli), prompt (tekst polecenia do wygenerowania obrazu) oraz image (ścieżka do obrazu do edycji). Przykładowy obraz do edycji:

Równoważny przykład w Pythonie:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Zapisz obraz do pliku
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

Przed wywołaniem w Pythonie należy ustawić dwie zmienne środowiskowe: OPENAI_BASE_URL na https://api.xhuoapi.ai/v1/openai oraz OPENAI_API_KEY na token z pola authorization. Na Mac OS można to zrobić tak:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token} 

Po wywołaniu w bieżącym katalogu pojawi się plik gift-basket.png, efekt:

W ten sposób zakończyliśmy edycję obrazu. Interfejs Edits obsługuje obecnie trzy modele: dall-e-2, gpt-image-1 oraz gpt-image-2. Zalecanym modelem jest gpt-image-2, szczegóły powyżej w sekcji Model GPT-Image-2.

Asynchroniczne wywołanie zwrotne

Ponieważ edycja obrazów przez OpenAI Images Edits API może trwać dłużej, a długie oczekiwanie na odpowiedź HTTP może obciążać zasoby systemowe, API oferuje wsparcie dla asynchronicznego callbacku. Proces jest następujący: klient wysyła zapytanie z dodatkowym polem callback_url. API natychmiast zwraca odpowiedź z task_id – identyfikatorem zadania. Po zakończeniu edycji wynik jest przesyłany metodą POST w formacie JSON na wskazany callback_url, zawierając również task_id, co pozwala powiązać wynik z zadaniem. Przykład działania: Webhook to usługa HTTP, która odbiera zapytania. Należy podać adres własnego serwera HTTP. Dla demonstracji można użyć publicznego serwisu https://webhook.site/, który generuje unikalny URL webhooka, np.:

Skopiuj URL, np. https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, i użyj go jako callback_url:

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

Otrzymasz natychmiast:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Po chwili na stronie webhooka pojawi się wynik edycji:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

Wynik zawiera task_id oraz pole data z obrazem w formacie base64, co pozwala powiązać odpowiedź z zadaniem.

Obsługa błędów

W przypadku błędów API zwraca odpowiedni kod i komunikat, np.:

400 token_mismatched: Niepoprawne żądanie, brak lub błędne parametry.
400 api_not_implemented: Niepoprawne żądanie, brak lub błędne parametry.
401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token.
429 too_many_requests: Zbyt wiele żądań, przekroczono limit.
500 api_error: Błąd wewnętrzny serwera.

Przykład odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Podsumowanie

W tej dokumentacji poznaliście sposób korzystania z OpenAI Images Edits API, które umożliwia łatwe użycie oficjalnych funkcji edycji obrazów OpenAI. Mamy nadzieję, że pomoże to w integracji i efektywnym wykorzystaniu API. W razie pytań prosimy o kontakt z zespołem wsparcia technicznego.

Documentation Index

​Proces rejestracji

​Model GPT-Image-2

​Obsługiwane wartości size i poziomy rozliczeń

​Metoda wywołania 1: JSON + URL obrazu (zalecane)

​Metoda wywołania 2: JSON + wiele obrazów referencyjnych

​Przykład scenariusza: zmiana stylu z zachowaniem struktury

​Metoda wywołania 3: multipart/form-data (kompatybilne z OpenAI SDK)

​Modele z serii Nano Banana

​Wywołanie przez formularz + URL obrazu

​Wywołanie przez formularz + plik lokalny

​Asynchroniczne wywołanie zwrotne (callback)

​Podstawowe użycie

​Asynchroniczne wywołanie zwrotne

​Obsługa błędów

​Przykład odpowiedzi błędu

​Podsumowanie