> ## 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 служба редагування зображень дозволяє передавати будь-яку кількість зображень та інструкцій, виводячи змінені зображення. Наразі інтерфейс підтримує `dall-e-2`, `gpt-image-1`, останню **`gpt-image-2`**, а також серію моделей **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`**, які підключаються через той самий інтерфейс. Цей документ в основному описує процес використання OpenAI Images Edits API, за допомогою якого ми можемо легко використовувати офіційні функції редагування зображень OpenAI. ## Процес заявки Щоб використовувати OpenAI Images Edits API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API Token, залиште його на випадок потреби. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви будете автоматично повернені на цю сторінку. **Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно спробувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація: [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## Модель GPT-Image-2 `gpt-image-2` має дуже помітні покращення в сценаріях редагування зображень у порівнянні з `gpt-image-1`: * **Структура залишається більш стабільною**: при зміні шкіри, кольору, фону майже не порушується оригінальний макет та композиція. * **Текст зберігається більш точно**: інформаційні графіки, плакати, меню та інші зображення з текстом залишаються чіткими та читабельними після редагування. * **Підтримка прямих URL**: окрім традиційного завантаження файлів `multipart/form-data`, `gpt-image-2` також **додатково підтримує передачу URL зображень у форматі JSON**, без необхідності спочатку завантажувати зображення на локальний комп'ютер, що дуже підходить для інтеграції на сервері. * **Підтримка прямої передачі base64**: відповідно до офіційних стандартів, поле `image` також може безпосередньо приймати base64 (`data:image/png;base64,...` або чистий base64), локальні зображення не потрібно спочатку завантажувати на хостинг для редагування. * **Підтримка високої роздільної здатності**: можна передати зображення з роздільною здатністю 1K, запитуючи 2K / 4K через параметр `size`, модель під час редагування також виконає масштабування. ### Офіційний маршрут / Реверсна варіація (`:official` / `:reverse`) `gpt-image-2` за замовчуванням використовує реверсний маршрут. Через суфікс імені моделі можна явно вибрати маршрут: * **`gpt-image-2:official`**: офіційний маршрут. Підтримує `n > 1` (повертає кілька зображень за один раз) та справжні 2K / 4K, **оплата за кожне зображення, ціна вдвічі вища за стандартну `gpt-image-2`**. Наразі доступно лише через канал openai-hk, у разі недоступності маршруту повертається помилка, без зниження до реверсного маршруту. * **`gpt-image-2:reverse`**: повністю еквівалентно стандартному `gpt-image-2` (реверсний маршрут), ціна залишається незмінною. > Обмеження, наведені нижче в розділі "Про параметр `n`", застосовуються лише до стандартного / реверсного маршруту; `gpt-image-2:official` підтримує `n > 1` і оплачує за зображення. ### Підтримувані значення `size` Обмеження редагувального інтерфейсу щодо `size` повністю збігається з обмеженнями генеративного інтерфейсу — `gpt-image-2` вимагає, щоб `size` було `auto`, порожнім або відповідало формату `WIDTHxHEIGHT`, будь-яка інша форма поверне 400. **Всі розміри (1K / 2K / 4K / індивідуальні) оплачуються за одне зображення, незалежно від роздільної здатності оригіналу та запитуваного значення `size`.** Вимоги до індивідуальних розмірів також застосовуються: ширина та висота мають бути кратними 16, довга сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400. | Співвідношення | Рекомендоване 1K | Рекомендоване 2K | Рекомендоване 4K | | -------------- | ---------------- | ---------------- | ---------------- | | 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` | > Наприклад: якщо оригінал має роздільну здатність `1024x1024`, при передачі `size` як `2048x2048` модель переробить та виведе 2K зображення; при передачі `size` як `3840x2160` виведе 4K горизонтальне зображення; передача `auto` або пропуск призведе до вибору моделі. Усі три варіанти мають однакову вартість. > **Про параметр `n`** > Інтерфейс редагування `gpt-image-2` наразі **не підтримує `n > 1`**: цей параметр буде тихо проігноровано, незалежно від того, передано `n=1` чи `n=10`, одноразовий запит завжди поверне лише 1 зображення, і оплата буде лише за 1 зображення. Якщо вам потрібно отримати кілька варіантів редагування одночасно, будь ласка, **ініціюйте кілька запитів паралельно**. Це обмеження також застосовується до `gpt-image-1` / `gpt-image-1.5`, а також до серій `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`. `dall-e-2` є наразі єдиною моделлю редагування, яка нативно підтримує `n > 1`. Нижче наведено два різні реальні приклади, щоб відчути можливості редагування `gpt-image-2`. ### Спосіб виклику 1: JSON + URL зображення (рекомендується) Прямо відправте запит у форматі `application/json`, заповнивши поле `image` URL одного зображення, модель забере це зображення та відредагує його відповідно до `prompt`. Наприклад, нижче наведене оригінальне зображення, яке було згенеровано за допомогою `gpt-image-2` у вигляді науково-популярного довідника:

Ми хочемо змінити його на кольорову схему "нічний режим". Можна викликати так: ```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": "Перетворіть цю інфографіку в темний режим: темно-синій фон, світлий кремовий текст, глибокі сірі округлі модульні картки з м'якими тінями. Залиште всю розкладку, структуру та розташування модулів ідентичними — лише інвертуйте кольорову схему.", "size": "1024x1536" }' ``` або на Python: ```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": "Перетворіть цю інфографіку в темний режим: темно-синій фон, світлий кремовий текст, глибокі сірі округлі модульні картки з м'якими тінями. Залиште всю розкладку, структуру та розташування модулів ідентичними — лише інвертуйте кольорову схему.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Результат буде таким: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Перетворіть цю інфографіку в темний режим: темно-синій фон, світлий кремовий текст, глибокі сірі округлі модульні картки з м'якими тінями. Залиште всю розкладку, структуру та розташування модулів ідентичними — лише інвертуйте кольорову схему.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` Редаговане зображення виглядає так:

Можна побачити, що структура модулів, інформаційні зони, шрифтове оформлення були строго збережені, лише кольорова схема була інвертована в темну тему. > **Підказка**: поле `image` також підтримує передачу масиву, наприклад, `"image": ["url1", "url2", "url3"]`, максимум можна передати 16 зображень для редагування, щоб модель могла врахувати кілька зображень. > **Прямий base64**: `image` (та кожен елемент масиву) може бути не лише URL, а й base64 — `data:image/png;base64,...` або чистий base64, що підходить для локальних зображень, які не хочеться спочатку завантажувати на хостинг. Наприклад: > > ```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": "Перетворіть цю інфографіку в темний режим.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### Спосіб виклику два: JSON + кілька зображень `gpt-image-2` підтримує одночасне використання кількох зображень для генерації фінального результату, наприклад, об'єднання кількох фотографій продуктів в один подарунковий кошик: ```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": "Об'єднайте всі вищезазначені предмети в один подарунковий кошик 'Розслабтесь і відпочиньте' на чистому білому фоні, фотореалістично, з м'яким природним освітленням.", "size": "1024x1024" } ``` ### Приклад сценарію: змінити стиль + зберегти структуру Ось ще один приклад, де дерев'яна книжкова полиця замінюється на сучасну плаваючу полицю, але строго зберігається кількість і розташування книг на кожному рівні. Оригінальне зображення (згенероване за допомогою `gpt-image-2` дерев'яної книжкової полиці):

Виклик: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Замініть дерев'яну книжкову полицю на сучасну білу плаваючу полицю, закріплену на пастельній блакитній стіні. Залиште точне таке ж розташування книг (1 книга зверху, 3 посередині, 7 внизу). Додайте маленький горщик з сукулентом на верхній полиці поруч з книгою. Яскраве повітряне денне світло зліва.", "size": "1024x1024" } ``` Результат редагування (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`):

Можна побачити, що стиль і середовище були повністю замінені відповідно до підказки, але кількість книг на кожному рівні (1 / 3 / 7) залишилася строго збереженою, і за вимогою була додана горщик з сукулентом. ### Спосіб виклику три: multipart/form-data (сумісно з OpenAI SDK) Якщо ви вже використовуєте офіційний OpenAI Python SDK, попередній спосіб завантаження `multipart/form-data` також підходить, просто змініть `model` на `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="Перетворіть це зображення в темний режим, зберігаючи розкладку незмінною." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` При використанні SDK потрібно спочатку імпортувати дві змінні середовища, `OPENAI_BASE_URL` встановити на `https://api.acedata.cloud/openai`, `OPENAI_API_KEY` встановити на отриманий токен: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## Моделі серії Nano Banana Серія `nano-banana` також підключилася до `/openai/images/edits` у сценаріях редагування, просто змініть `model` на будь-який з наведених у таблиці нижче. | Модель | Оплата (Кредити / раз) | Сценарії використання | | -------------------- | ---------------------- | ------------------------------------------------------------------------------------- | | `nano-banana` | 0.14 | Звичайне редагування зображень, найшвидше, найнижча вартість | | `nano-banana-2-lite` | 0.14 | Легка модель зображень Gemini 3.1, підтримує лише 1K, редагування з низькою затримкою | | `nano-banana-2` | 0.28 | Якість та деталі помітно покращені | | `nano-banana-pro` | 0.35 | Флагман у серії, найкраще збереження структури, тексту, стилю | > **Важливо: Діапазон підтримуваних параметрів** > Nano Banana підключається до протоколу OpenAI через адаптаційний шар, підтримує лише такі параметри: `model`, `prompt`, `image`. > > * `image` може бути завантажено через `multipart/form-data` (всередині worker буде перетворено на `data:;base64,...` для передачі вгору), також може бути передано як рядок URL зображення через поля форми. > * Не підтримуються параметри `mask`, `n`, `size`, `response_format` тощо; якщо їх заповнити, вони будуть проігноровані. > * Структура відповіді відповідає формату OpenAI (`data[].url`), але `created` завжди дорівнює `0`, і не буде повертатися `b64_json`, `revised_prompt` завжди дорівнює оригінальному `prompt`. ### Виклик через форму + URL зображення ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=додати зелене листя на верхівку яблука" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Результат відповіді виглядає так: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "додати зелене листя на верхівку яблука" } ] } ``` Редаговане зображення:

### Виклик через форму + локальний файл ```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": "додати зелене листя на верхівку яблука" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### Асинхронний зворотний виклик `callback_url` асинхронний механізм зворотного виклику також діє для nano-banana, процес виклику повністю аналогічний іншим моделям, детальніше див. розділ [Асинхронний зворотний виклик](#асинхронний-зворотний-виклик). ## Основне використання Тепер можна використовувати код для виклику, нижче наведено приклад виклику через 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=Створити милий подарунковий кошик з цими предметами в ньому' ``` При першому використанні цього інтерфейсу, нам потрібно заповнити принаймні чотири поля: одне з них - `authorization`, яке можна вибрати безпосередньо зі списку. Інший параметр - `model`, `model` - це категорія моделі OpenAI, яку ми вибираємо, тут у нас є 1 модель, деталі можна переглянути в наданих моделях. Ще один параметр - `prompt`, `prompt` - це підказка, яку ми вводимо для генерації зображення. Останній параметр - `image`, цей параметр вимагає шлях до зображення, яке потрібно редагувати, зображення наведено нижче:

Приклад коду для виклику з однаковим ефектом на Python: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Згенерувати фотореалістичне зображення подарункового кошика на білому фоні з написом 'Розслабитися та відпочити' з стрічкою та шрифтом, схожим на рукописний, який містить усі предмети з референсних зображень. """ 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) # Зберегти зображення у файл with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` Для виклику з Python нам потрібно спочатку імпортувати дві змінні середовища: одну `OPENAI_BASE_URL`, яку можна встановити на `https://api.acedata.cloud/openai`, і ще одну змінну для облікових даних `OPENAI_API_KEY`, значення якої отримується з `authorization`, в Mac OS можна встановити змінні середовища за допомогою таких команд: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` Після виклику ми виявимо, що в поточному каталозі з'явиться зображення `gift-basket.png`, конкретний результат виглядає так:

Таким чином, ми завершили редагування зображення, наразі інтерфейс Edits підтримує три моделі: `dall-e-2`, `gpt-image-1` та `gpt-image-2`, з яких `gpt-image-2` є рекомендованою моделлю, детальніше див. розділ [Модель GPT-Image-2](#модель-gpt-image-2). ## Асинхронний зворотний виклик Оскільки час редагування зображень API OpenAI Images Edits може бути відносно довгим, якщо API довго не відповідає, HTTP запит буде підтримувати з'єднання, що призводить до додаткових витрат системних ресурсів, тому цей API також пропонує підтримку асинхронного зворотного виклику. Загальний процес: коли клієнт ініціює запит, додатково вказується поле `callback_url`, після ініціації API запит повертає результат, що містить інформацію про поле `task_id`, що представляє поточний ID завдання. Коли завдання завершено, результат редагування зображення буде надіслано на вказаний клієнтом `callback_url` у форматі POST JSON, в якому також міститься поле `task_id`, таким чином результати завдання можна пов'язати за ID. Далі ми розглянемо приклад, щоб зрозуміти, як саме це працює. По-перше, Webhook зворотний виклик - це служба, яка може приймати HTTP запити, розробники повинні замінити на URL свого HTTP сервера. Для зручності демонстрації використовується публічний веб-сайт з прикладом Webhook [https://webhook.site/](https://webhook.site/), відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку: ![](https://cdn.acedata.cloud/cjjfly.png) Скопіюйте це URL, і ви зможете використовувати його як Webhook, приклад тут: `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Далі ми можемо налаштувати поле `callback_url` на вказаний Webhook URL, а також заповнити відповідні параметри, як показано в наступному коді: ```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=Створіть милий подарунковий кошик з цими предметами" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Після виклику можна відразу отримати результат, як показано нижче: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Почекавши деякий час, ми можемо спостерігати результати редагування зображення на Webhook URL, вміст виглядає так: ```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..." } ] } } ``` Можна побачити, що в результаті є поле `task_id`, поле `data` містить такі ж результати редагування зображення, як і при синхронному виклику, через поле `task_id` можна реалізувати зв'язок завдань. ## Обробка помилок При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад: * `400 token_mismatched`: Неправильний запит, можливо, через відсутні або недійсні параметри. * `400 api_not_implemented`: Неправильний запит, можливо, через відсутні або недійсні параметри. * `401 invalid_token`: Неавторизовано, недійсний або відсутній токен авторизації. * `429 too_many_requests`: Занадто багато запитів, ви перевищили ліміт запитів. * `500 api_error`: Внутрішня помилка сервера, щось пішло не так на сервері. ### Приклад відповіді з помилкою ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Висновок Завдяки цьому документу ви дізналися, як легко використовувати API OpenAI Images Edits для використання офіційних функцій редагування зображень OpenAI. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.