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 для отримання вашого API Token, залиште його на випадок потреби.
Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви будете автоматично повернені на цю сторінку.
Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу. Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно спробувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в консолі.
📘 Повна документація: OpenAI Images Edits API →
Модель 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.
Наприклад: якщо оригінал має роздільну здатність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 у вигляді науково-популярного довідника:


Підказка: полеimageтакож підтримує передачу масиву, наприклад,"image": ["url1", "url2", "url3"], максимум можна передати 16 зображень для редагування, щоб модель могла врахувати кілька зображень.
Прямий base64:image(та кожен елемент масиву) може бути не лише URL, а й base64 —data:image/png;base64,...або чистий base64, що підходить для локальних зображень, які не хочеться спочатку завантажувати на хостинг. Наприклад:
Спосіб виклику два: JSON + кілька зображень
gpt-image-2 підтримує одночасне використання кількох зображень для генерації фінального результату, наприклад, об’єднання кількох фотографій продуктів в один подарунковий кошик:
Приклад сценарію: змінити стиль + зберегти структуру
Ось ще один приклад, де дерев’яна книжкова полиця замінюється на сучасну плаваючу полицю, але строго зберігається кількість і розташування книг на кожному рівні. Оригінальне зображення (згенероване за допомогоюgpt-image-2 дерев’яної книжкової полиці):

task_id: e9544dba-727e-44a2-81e1-223d49869380):

Спосіб виклику три: multipart/form-data (сумісно з OpenAI SDK)
Якщо ви вже використовуєте офіційний OpenAI Python SDK, попередній спосіб завантаженняmultipart/form-data також підходить, просто змініть model на gpt-image-2:
OPENAI_BASE_URL встановити на https://api.acedata.cloud/openai, OPENAI_API_KEY встановити на отриманий токен:
Моделі серії Nano Banana
Серіяnano-banana також підключилася до /openai/images/edits у сценаріях редагування, просто змініть model на будь-який з наведених у таблиці нижче.
Важливо: Діапазон підтримуваних параметрів Nano Banana підключається до протоколу OpenAI через адаптаційний шар, підтримує лише такі параметри:model,prompt,image.
imageможе бути завантажено черезmultipart/form-data(всередині worker буде перетворено наdata:<mime>;base64,...для передачі вгору), також може бути передано як рядок URL зображення через поля форми.- Не підтримуються параметри
mask,n,size,response_formatтощо; якщо їх заповнити, вони будуть проігноровані.- Структура відповіді відповідає формату OpenAI (
data[].url), алеcreatedзавжди дорівнює0, і не буде повертатисяb64_json,revised_promptзавжди дорівнює оригінальномуprompt.
Виклик через форму + URL зображення

Виклик через форму + локальний файл
Асинхронний зворотний виклик
callback_url асинхронний механізм зворотного виклику також діє для nano-banana, процес виклику повністю аналогічний іншим моделям, детальніше див. розділ Асинхронний зворотний виклик.
Основне використання
Тепер можна використовувати код для виклику, нижче наведено приклад виклику через CURL:authorization, яке можна вибрати безпосередньо зі списку. Інший параметр - model, model - це категорія моделі OpenAI, яку ми вибираємо, тут у нас є 1 модель, деталі можна переглянути в наданих моделях. Ще один параметр - prompt, prompt - це підказка, яку ми вводимо для генерації зображення. Останній параметр - image, цей параметр вимагає шлях до зображення, яке потрібно редагувати, зображення наведено нижче:

OPENAI_BASE_URL, яку можна встановити на https://api.acedata.cloud/openai, і ще одну змінну для облікових даних OPENAI_API_KEY, значення якої отримується з authorization, в Mac OS можна встановити змінні середовища за допомогою таких команд:
gift-basket.png, конкретний результат виглядає так:

dall-e-2, gpt-image-1 та 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/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку:
Скопіюйте це URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Далі ми можемо налаштувати поле callback_url на вказаний Webhook URL, а також заповнити відповідні параметри, як показано в наступному коді:
task_id, поле data містить такі ж результати редагування зображення, як і при синхронному виклику, через поле task_id можна реалізувати зв’язок завдань.
Обробка помилок
При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

