> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API 申请及使用 > OpenAI generation API guide - Ace Data Cloud 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 控制台](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## 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. | Proporcja | 1K rekomendowane | 2K rekomendowane | 4K rekomendowane | | --------- | ---------------- | ---------------- | ---------------- | | 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` | > 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Przekształć tę infografikę w tryb ciemny: ciemnoniebieskie tło, jasny kremowy tekst, głęboko szare zaokrąglone karty modułów z delikatnymi cieniami. Zachowaj cały układ, strukturę i rozmieszczenie modułów identyczne — tylko odwróć schemat kolorów.", "size": "1024x1536" }' ``` lub w Pythonie: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Przekształć tę infografikę w tryb ciemny: ciemnoniebieskie tło, jasny kremowy tekst, głęboko szare zaokrąglone karty modułów z delikatnymi cieniami. Zachowaj cały układ, strukturę i rozmieszczenie modułów identyczne — tylko odwróć schemat kolorów.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Wynik zwrócony jest następujący: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Przekształć tę infografikę w tryb ciemny: ciemnoniebieskie tło, jasny kremowy tekst, głęboko szare zaokrąglone karty modułów z delikatnymi cieniami. Zachowaj cały układ, strukturę i rozmieszczenie modułów identyczne — tylko odwróć schemat kolorów.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 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: > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "Przekształć tę infografikę w tryb ciemny.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### 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: ```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": "Połącz wszystkie powyższe przedmioty w jeden kosz prezentowy 'Relaks & Odpoczynek' na czystym białym tle, fotorealistycznie, w miękkim naturalnym świetle.", "size": "1024x1024" } ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Zastąp drewnianą półkę na książki nowoczesną białą półką wiszącą zamontowaną na pastelowej niebieskiej ścianie. Zachowaj dokładnie ten sam układ książek (1 książka na górze, 3 w środku, 7 na dole). Dodaj mały doniczkowy sukulent na górnej półce obok książki. Jasne, przewiewne światło dzienne z lewej strony.", "size": "1024x1024" } ``` 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`: ```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="Przekształć ten obraz w tryb ciemny, zachowując układ." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={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. | Model | Billing (Credits / time) | Applicable Scenarios | | -------------------- | ------------------------ | ---------------------------------------------------------------------------- | | `nano-banana` | 0.14 | Zwykła edycja obrazów, najszybsza, najtańsza | | `nano-banana-2-lite` | 0.14 | Lekki model obrazów Gemini 3.1, obsługuje tylko 1K, niskie opóźnienie edycji | | `nano-banana-2` | 0.28 | Wyraźna poprawa jakości i szczegółowości | | `nano-banana-pro` | 0.35 | Flagowy model w serii, najlepsze zachowanie struktury, tekstu i stylu | > **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:;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 ```shell theme={null} curl -X POST "https://api.acedata.cloud/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.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Odpowiedź wygląda następująco: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` Edytowany obraz:

### Wywołanie przez formularz + lokalny plik ```python theme={null} import requests url = "https://api.acedata.cloud/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) ``` ### 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](#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: ```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.acedata.cloud/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' ``` 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: ```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) ``` 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ń: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` 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](#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/](https://webhook.site/), otwierając tę stronę można uzyskać URL Webhook, jak pokazano na obrazku: ![](https://cdn.acedata.cloud/cjjfly.png) 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Stwórz uroczy kosz prezentowy z tymi przedmiotami" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Po wywołaniu można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Po chwili możemy zaobserwować wyniki edycji zdjęcia na URL Webhook, treść jest następująca: ```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..." } ] } } ``` 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "pobieranie nie powiodło się" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 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.