Skip to main content
OpenAI usługa edycji obrazów pozwala na przesyłanie dowolnej liczby obrazów i poleceń, a następnie zwraca zmodyfikowane obrazy. Obecnie interfejs obsługuje jednocześnie dall-e-2, gpt-image-1, najnowszy gpt-image-2, a także modele z serii nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro, które są dostępne przez ten sam interfejs. Dokument ten głównie opisuje proces korzystania z OpenAI Images Edits API, dzięki któremu możemy łatwo korzystać z oficjalnych funkcji edycji obrazów OpenAI.

申请流程

Aby korzystać z OpenAI Images Edits API, najpierw przejdź do Ace Data Cloud 控制台, aby uzyskać swój token API, który należy zachować na przyszłość. Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi. Przy pierwszym wniosku otrzymasz darmowy limit, aby móc skorzystać z usługi; gdy limit się wyczerpie, możesz doładować saldo ogólne w kontrolerze.
📘 Pełna dokumentacja: OpenAI Images Edits API →

GPT-Image-2 模型

gpt-image-2 w scenariuszach edycji obrazów ma znaczne ulepszenia w porównaniu do gpt-image-1:
  • Struktura jest bardziej stabilna: zmiana skóry, kolorystyki, tła prawie nie niszczy układu i kompozycji oryginalnego obrazu.
  • Zachowanie tekstu jest bardziej dokładne: obrazy zawierające tekst, takie jak infografiki, plakaty, menu, pozostają czytelne po edycji.
  • Wsparcie dla bezpośredniego przesyłania URL: oprócz tradycyjnego przesyłania plików multipart/form-data, gpt-image-2 dodatkowo wspiera przesyłanie URL obrazów w formacie JSON, co eliminuje potrzebę pobierania obrazów na lokalny dysk, co jest idealne do integracji w pipeline serwera.
  • Wsparcie dla bezpośredniego przesyłania base64: zgodnie z oficjalnymi wytycznymi, pole image może również bezpośrednio przyjmować base64 (data:image/png;base64,... lub surowy base64), co pozwala na edycję lokalnych obrazów bez konieczności przesyłania ich na hosting obrazów.
  • Wsparcie dla wysokiej rozdzielczości: można przesłać obraz o rozdzielczości 1K, a za pomocą parametru size zażądać wyjścia 2K / 4K, model jednocześnie powiększy obraz w trakcie edycji.

官方中转 / 逆向变体(:official / :reverse

gpt-image-2 domyślnie korzysta z trasy odwrotnej. Można jawnie wybrać trasę, dodając sufiks do nazwy modelu:
  • gpt-image-2:official: oficjalna trasa pośrednia. Obsługuje n > 1 (zwraca wiele obrazów jednocześnie) oraz prawdziwe 2K / 4K, opłata za każdą obraz jest dwukrotnością ceny domyślnej gpt-image-2. Obecnie dostępne tylko przez kanał openai-hk, w przypadku braku dostępności trasy zwraca błąd, nie przechodzi na trasę odwrotną.
  • gpt-image-2:reverse: całkowicie równoważne z domyślnym gpt-image-2 (trasa odwrotna), cena pozostaje bez zmian.
Ograniczenia dotyczące parametru n w dalszej części tekstu dotyczą tylko domyślnej / odwrotnej trasy; gpt-image-2:official obsługuje n > 1 i nalicza opłaty za obrazy.

支持的 size 取值

Ograniczenia interfejsu edycji dotyczące size są całkowicie zgodne z interfejsem generowania — gpt-image-2 wymaga, aby size było auto, puste lub zgodne z formatem WIDTHxHEIGHT, wszelkie inne formy zwrócą 400. Wszystkie rozmiary (1K / 2K / 4K / niestandardowe) są naliczane za pojedynczy obraz, niezależnie od rozdzielczości oryginalnego obrazu i wartości żądania size. Górne ograniczenia dotyczące niestandardowych rozmiarów również mają zastosowanie: zarówno szerokość, jak i wysokość muszą być wielokrotnością 16, dłuższy bok ≤ 3840, całkowita liczba pikseli ≤ 8,294,400.
Na przykład: jeśli oryginalny obraz ma rozmiar 1024x1024, a size to 2048x2048, model przerysuje i wyprodukuje obraz 2K zgodnie z poleceniem edycji; jeśli size to 3840x2160, wyprodukuje obraz 4K w orientacji poziomej; jeśli przekażesz auto lub pominiesz, model sam wybierze. Wszystkie trzy opcje są naliczane w ten sam sposób.
O parametrach n Interfejs edycji gpt-image-2 obecnie nie obsługuje n > 1: ten parametr będzie cicho ignorowany, niezależnie od tego, czy przekażesz n=1, czy n=10, pojedyncze żądanie zawsze zwróci tylko 1 obraz i będzie naliczane tylko za 1 obraz. Jeśli potrzebujesz uzyskać wiele wyników edycji jednocześnie, proszę samodzielnie wysłać wiele równoległych żądań. To ograniczenie dotyczy również gpt-image-1 / gpt-image-1.5, a także serii nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. dall-e-2 jest obecnie jedynym modelem edycyjnym, który natywnie obsługuje n > 1.
Poniżej przedstawiamy dwa różne rzeczywiste przykłady, aby poczuć zdolności edycyjne gpt-image-2.

调用方式一:JSON + 图片 URL(推荐)

Bezpośrednio wysyłaj żądanie w formacie application/json, wypełniając pole image URL-em jednego obrazu, model pobierze ten obraz i edytuje go zgodnie z prompt. Na przykład, poniższy oryginalny obraz został wygenerowany jako ilustracja popularnonaukowa za pomocą gpt-image-2:

Chcemy zmienić jego kolorystykę na “tryb nocny”. Możemy to wywołać w ten sposób:
lub w Pythonie:
Wynik zwrócony jest następujący:
Edytowany obrazek wygląda następująco:

Można zauważyć, że struktura modułów, podział informacji i układ czcionek zostały ściśle zachowane, tylko kolorystyka została odwrócona na ciemny motyw.
Wskazówka: pole image obsługuje również przekazywanie tablicy, na przykład "image": ["url1", "url2", "url3"], maksymalnie można jednocześnie przekazać 16 obrazów referencyjnych, aby model mógł uwzględnić wiele obrazów podczas edycji.
Bezpośredni przesył base64: image (i każda pozycja w tablicy) może być również w formacie base64 — data:image/png;base64,... lub czysty base64, co jest odpowiednie w przypadku lokalnych obrazów, które nie chcemy najpierw przesyłać na serwer. Na przykład:

Drugi sposób wywołania: JSON + wiele obrazów referencyjnych

gpt-image-2 obsługuje jednoczesne uwzględnienie wielu obrazów, aby wygenerować ostateczny wynik, na przykład połączenie wielu zdjęć produktów w jeden kosz prezentowy:

Przykład scenariusza: zmiana stylu + zachowanie struktury

Oto inny przykład, w którym drewniana półka na książki jest zastępowana nowoczesną półką wiszącą, ale ściśle zachowuje się liczbę i układ książek na każdej półce. Obraz oryginalny (półka na książki wygenerowana przez gpt-image-2):

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

Można zauważyć, że styl i otoczenie zostały całkowicie zastąpione zgodnie z podanymi wskazówkami, ale liczba książek na każdej półce (1 / 3 / 7) została ściśle zachowana, a zgodnie z wymaganiami dodano doniczkę z sukulentem.

Trzeci sposób wywołania: multipart/form-data (kompatybilne z OpenAI SDK)

Jeśli już korzystasz z oficjalnego OpenAI Python SDK, dotychczasowy sposób przesyłania multipart/form-data również jest odpowiedni, wystarczy zmienić model na gpt-image-2:
Korzystając z SDK, należy najpierw zaimportować dwie zmienne środowiskowe, OPENAI_BASE_URL ustaw na https://api.acedata.cloud/openai, a OPENAI_API_KEY na uzyskany token:

Modele serii Nano Banana

Seria nano-banana również wprowadza edytowanie w scenariuszach za pomocą /openai/images/edits, wystarczy zmienić model na dowolny z poniższej tabeli.
Ważne: Zakres obsługiwanych parametrów Nano Banana łączy się z protokołem OpenAI przez warstwę adaptacyjną, obsługuje tylko następujące parametry: model, prompt, image.
  • image można przesłać zarówno przez multipart/form-data (wewnętrznie zamieniane na data:<mime>;base64,... i przesyłane do upstream), jak i bezpośrednio jako ciąg URL obrazu w polu formularza.
  • Nie obsługuje parametrów mask, n, size, response_format itp.; wypełnione będą ignorowane.
  • Struktura odpowiedzi przestrzega formatu OpenAI (data[].url), ale created jest stałe jako 0, a b64_json nie będzie zwracane, revised_prompt zawsze równa się oryginalnemu prompt.

Wywołanie przez formularz + URL obrazu

Odpowiedź wygląda następująco:
Edytowany obraz:

Wywołanie przez formularz + lokalny plik

Asynchroniczny callback

Mechanizm asynchronicznego callbacku callback_url działa również dla nano-banana, proces wywołania jest identyczny jak w przypadku innych modeli, szczegóły w sekcji Asynchroniczny callback.

Podstawowe użycie

Teraz można użyć kodu do wywołania, poniżej znajduje się przykład wywołania za pomocą CURL:
Podczas pierwszego użycia tego interfejsu musimy wypełnić co najmniej cztery elementy, jeden to authorization, który można wybrać z rozwijanej listy. Kolejny parametr to model, model to kategoria modelu, którą wybieramy z oficjalnej strony OpenAI, tutaj mamy głównie 1 model, szczegóły można znaleźć w dostarczonych modelach. Następny parametr to prompt, prompt to nasz tekst wskazujący, co ma być wygenerowane w obrazie. Ostatni parametr to image, który wymaga ścieżki do edytowanego obrazu, który wygląda jak na poniższym obrazku:

Przykładowy kod wywołania w Pythonie o tym samym efekcie:
Aby wywołać w Pythonie, musimy najpierw zaimportować dwie zmienne środowiskowe, jedną OPENAI_BASE_URL, którą można ustawić na https://api.acedata.cloud/openai, oraz zmienną z poświadczeniami OPENAI_API_KEY, której wartość pochodzi z authorization, w systemie Mac OS można ustawić zmienne środowiskowe za pomocą następujących poleceń:
Po wywołaniu zauważymy, że w bieżącym katalogu zostanie wygenerowany obraz gift-basket.png, a konkretny wynik wygląda następująco:

W ten sposób zakończyliśmy operację edycji obrazu, obecnie interfejs Edits obsługuje trzy modele: dall-e-2, gpt-image-1 i gpt-image-2, z których gpt-image-2 jest obecnie zalecanym modelem, szczegóły w sekcji Model GPT-Image-2.

Asynchroniczny callback

Ponieważ czas edycji obrazów przez OpenAI Images Edits API może być stosunkowo długi, jeśli API nie odpowiada przez dłuższy czas, żądanie HTTP będzie utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API oferuje również wsparcie dla asynchronicznego callbacku. Cały proces polega na tym, że klient podczas wysyłania żądania dodatkowo określa pole callback_url, po wysłaniu żądania API natychmiast zwraca wynik, zawierający pole task_id, które reprezentuje bieżące ID zadania. Po zakończeniu zadania wynik edycji obrazu zostanie wysłany do określonego przez klienta callback_url w formie POST JSON, w tym również pole task_id, dzięki czemu wyniki zadania można powiązać za pomocą ID. Poniżej przedstawiamy przykład, aby zrozumieć, jak to działa. Po pierwsze, callback Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić ją URL swojego serwera HTTP. W celu wygodnej demonstracji używamy publicznej strony przykładowej Webhook https://webhook.site/, otwierając tę stronę można uzyskać URL Webhook, jak pokazano na obrazku: Skopiuj ten URL, aby móc go używać jako Webhook, przykładowy URL to https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Następnie możemy ustawić pole callback_url na powyższy URL Webhook, a także wypełnić odpowiednie parametry, jak pokazano w poniższym kodzie:
Po wywołaniu można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej:
Po chwili możemy zaobserwować wyniki edycji zdjęcia na URL Webhook, treść jest następująca:
Można zauważyć, że w wyniku znajduje się pole task_id, a pole data zawiera te same wyniki edycji zdjęcia co w przypadku wywołania synchronicznego, a przez pole task_id można zrealizować powiązanie z zadaniem.

Obsługa błędów

Podczas wywoływania API, jeśli napotkasz błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:
  • 400 token_mismatched: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 400 api_not_implemented: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczyłeś limit szybkości.
  • 500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

Przykład odpowiedzi błędu

Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak łatwo korzystać z API OpenAI Images Edits, aby wykorzystać oficjalne funkcje edycji obrazów OpenAI. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, skontaktuj się z naszym zespołem wsparcia technicznego.