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żna łatwo używać oficjalnych funkcji edycji obrazów OpenAI.
Proces rejestracji
Aby korzystać z OpenAI Images Edits API, należy najpierw przejść na stronę OpenAI Images Edits API i kliknąć przycisk „Acquire”, aby uzyskać niezbędne poświadczenia do żądań: 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 zgłoszeniu otrzymujesz darmowy limit, który pozwala na bezpłatne korzystanie z API.Model GPT-Image-2
Modelgpt-image-2 oferuje znaczące ulepszenia w scenariuszach edycji obrazów w porównaniu do gpt-image-1:
- Stabilniejsze zachowanie struktury: zmiana skórek, kolorystyki czy tła niemal nie narusza układu i kompozycji oryginalnego obrazu.
- Dokładniejsze zachowanie tekstu: obrazy zawierające tekst, takie jak infografiki, plakaty czy menu, po edycji zachowują czytelność tekstu.
- Obsługa bezpośredniego przesyłania URL: oprócz tradycyjnego przesyłania plików w formacie
multipart/form-data,gpt-image-2dodatkowo obsługuje przekazywanie URL obrazu w formacie JSON, co eliminuje konieczność pobierania obrazu lokalnie i jest idealne do integracji po stronie serwera. - Obsługa wysokiej rozdzielczości: można przesłać obraz 1K i za pomocą parametru
sizezażądać wyjścia w rozdzielczości 2K lub 4K; model podczas edycji jednocześnie powiększy obraz.
Obsługiwane wartości parametru size
Ograniczenia parametru size w interfejsie edycji są takie same jak w interfejsie generowania — gpt-image-2 akceptuje size równe auto, puste lub w formacie WIDTHxHEIGHT. Każda inna forma zwróci błąd 400. Wszystkie rozmiary (1K / 2K / 4K / niestandardowe) są rozliczane jednolicie za pojedynczy obraz, niezależnie od rozdzielczości oryginału i wartości size.
Obowiązują też ograniczenia dotyczące niestandardowych rozmiarów: szerokość i wysokość muszą być wielokrotnością 16, dłuższy bok ≤ 3840, łączna liczba pikseli ≤ 8 294 400.
Przykład: jeśli oryginalny obraz ma rozmiar1024x1024, asizeustawimy na2048x2048, model wygeneruje obraz 2K zgodnie z instrukcją edycji; dla3840x2160wyjściem będzie obraz 4K w orientacji poziomej; dlaautolub pominięcia parametru model sam wybierze rozmiar. Opłata jest taka sama w każdym przypadku.
O parametrzePoniżej przedstawiamy dwa przykłady pokazujące możliwości edycji modelunInterfejs edycjigpt-image-2nie obsługujen > 1: parametr ten jest ignorowany, niezależnie czy podaszn=1czyn=10, w odpowiedzi zwracany jest tylko jeden obraz i naliczana jest opłata za jeden obraz. Jeśli potrzebujesz wielu wariantów, musisz wykonać wiele równoległych żądań. To ograniczenie dotyczy również modeligpt-image-1/gpt-image-1.5oraz seriinano-banana. Modeldall-e-2jest obecnie jedynym natywnie obsługującymn > 1.
gpt-image-2.
Metoda wywołania 1: JSON + URL obrazu (zalecane)
Wysyłamy żądanie jakoapplication/json, w polu image podajemy 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:
Wskazówka: poleimagemoże też przyjmować tablicę URL-i, np."image": ["url1", "url2", "url3"], maksymalnie do 16 obrazów referencyjnych, które model uwzględni podczas edycji.
Metoda wywołania 2: JSON + wiele obrazów referencyjnych
Modelgpt-image-2 potrafi korzystać z wielu obrazów referencyjnych, np. łączyć kilka zdjęć produktów w jeden kosz prezentowy:
Przykład scenariusza: zmiana stylu przy zachowaniu struktury
Kolejny przykład: zamiana drewnianej półki na nowoczesną, ale zachowanie dokładnej liczby i układu książek na każdej półce. Oryginalny obraz (drewniana półka wygenerowana przezgpt-image-2):
Wywołanie:
task_id: e9544dba-727e-44a2-81e1-223d49869380):
Widać, że styl i otoczenie zostały zmienione zgodnie z poleceniem, ale liczba książek na każdej półce (1 / 3 / 7) pozostała niezmieniona, 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 używać tradycyjnego przesyłania plikówmultipart/form-data, wystarczy zmienić model na gpt-image-2:
OPENAI_BASE_URL na https://api.acedata.cloud/openai oraz OPENAI_API_KEY na uzyskany token:
Modele z serii Nano Banana
Modelenano-banana również są dostępne pod /openai/images/edits. Wystarczy zmienić parametr model na dowolny z poniższej tabeli:
Ważne: obsługiwane parametry Nano Banana korzysta z warstwy adaptacyjnej OpenAI i obsługuje tylko parametry:model,prompt,image.
imagemożna przesłać jako plik wmultipart/form-data(worker konwertuje go do formatudata:<mime>;base64,...dla upstream) lub jako URL w polu formularza.- Nie obsługuje parametrów
mask,n,size,response_format– są ignorowane.- Odpowiedź ma format zgodny z OpenAI (
data[].url), alecreatedjest zawsze0, nie zwracab64_json, arevised_promptjest zawsze równy oryginalnemuprompt.
Wywołanie przez formularz + URL obrazu
Wywołanie przez formularz + lokalny plik
Asynchroniczne wywołanie zwrotne (callback)
Mechanizm asynchronicznego callbackcallback_url działa również dla nano-banana i jest identyczny jak dla innych modeli (szczegóły w sekcji Asynchroniczne wywołanie zwrotne).
Podstawowe użycie
Możesz wywołać API za pomocą CURL:authorization (wybierany z listy), model (wybór modelu OpenAI, tutaj dostępny jest jeden model, szczegóły w dokumentacji modeli), prompt (tekstowy opis generowanego obrazu) oraz image (ścieżka do edytowanego obrazu). Przykładowy obraz do edycji:
Analogiczne wywołanie w Pythonie:
OPENAI_BASE_URL na https://api.acedata.cloud/openai oraz OPENAI_API_KEY na uzyskany token. Na Mac OS można to zrobić tak:
gift-basket.png z wynikiem:
W ten sposób zakończyliśmy edycję obrazu. Interfejs Edits obsługuje trzy modele: dall-e-2, gpt-image-1 i gpt-image-2. Zalecanym modelem jest gpt-image-2 (szczegóły w sekcji Model GPT-Image-2).
Asynchroniczne wywołanie zwrotne
Ponieważ edycja obrazów przez OpenAI Images Edits API może trwać długo, a długie oczekiwanie na odpowiedź HTTP obciąża zasoby systemowe, API oferuje wsparcie dla asynchronicznych callbacków. Proces jest następujący: klient wysyła żądanie z dodatkowym polemcallback_url. API natychmiast zwraca odpowiedź zawierającą task_id – identyfikator zadania. Po zakończeniu edycji wynik jest przesyłany metodą POST w formacie JSON na podany callback_url, zawierając również task_id, co pozwala powiązać odpowiedź z zadaniem.
Przykład działania:
Webhook callback to usługa HTTP, którą należy zastąpić własnym serwerem HTTP. Dla demonstracji można użyć publicznego serwisu https://webhook.site/, który generuje unikalny URL webhooka, np.:
Skopiuj ten URL, np. https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, i użyj go jako callback_url:
task_id oraz pole data z wynikiem edycji, analogicznie do wywołania synchronicznego. Dzięki task_id można powiązać zadanie z odpowiedzią.
Obsługa błędów
W przypadku błędów API zwraca odpowiedni kod i komunikat, np.:400 token_mismatched: złe żądanie, brak lub nieprawidłowe parametry.400 api_not_implemented: złe żądanie, brak lub nieprawidłowe parametry.401 invalid_token: brak autoryzacji, nieprawidłowy lub brakujący token.429 too_many_requests: zbyt wiele żądań, przekroczono limit.500 api_error: błąd wewnętrzny serwera.

