> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API – rejestracja i użycie > OpenAI generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) i kliknąć przycisk „Acquire”, aby uzyskać niezbędne poświadczenia do zapytań: ![](https://cdn.xhuoapi.ai/nyq0xz.png) 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: ```shell theme={null} 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: ```python theme={null} 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ź: ```json theme={null} { "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: ```python theme={null} 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: ```python theme={null} 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`: ```python theme={null} 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: ```shell theme={null} 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:;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 ```shell theme={null} 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ź: ```json theme={null} { "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 ```python theme={null} 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](#asynchroniczne-wywołanie-zwrotne). ## Podstawowe użycie Poniżej przykład wywołania CURL: ```curl theme={null} 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[]=@test.png" \ -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: ```python theme={null} 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: ```shell theme={null} 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](#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/](https://webhook.site/), który generuje unikalny URL webhooka, np.: ![](https://cdn.xhuoapi.ai/cjjfly.png) Skopiuj URL, np. `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`, i użyj go jako `callback_url`: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -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: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Po chwili na stronie webhooka pojawi się wynik edycji: ```json theme={null} { "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 ```json theme={null} { "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.