Skip to main content
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 для отримання вашого 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 у вигляді науково-популярного довідника:

Ми хочемо змінити його на кольорову схему “нічний режим”. Можна викликати так:
або на Python:
Результат буде таким:
Редаговане зображення виглядає так:

Можна побачити, що структура модулів, інформаційні зони, шрифтове оформлення були строго збережені, лише кольорова схема була інвертована в темну тему.
Підказка: поле 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):

Можна побачити, що стиль і середовище були повністю замінені відповідно до підказки, але кількість книг на кожному рівні (1 / 3 / 7) залишилася строго збереженою, і за вимогою була додана горщик з сукулентом.

Спосіб виклику три: multipart/form-data (сумісно з OpenAI SDK)

Якщо ви вже використовуєте офіційний OpenAI Python SDK, попередній спосіб завантаження multipart/form-data також підходить, просто змініть model на gpt-image-2:
При використанні SDK потрібно спочатку імпортувати дві змінні середовища, 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, цей параметр вимагає шлях до зображення, яке потрібно редагувати, зображення наведено нижче:

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

Таким чином, ми завершили редагування зображення, наразі інтерфейс Edits підтримує три моделі: 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, а також заповнити відповідні параметри, як показано в наступному коді:
Після виклику можна відразу отримати результат, як показано нижче:
Почекавши деякий час, ми можемо спостерігати результати редагування зображення на 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: Внутрішня помилка сервера, щось пішло не так на сервері.

Приклад відповіді з помилкою

Висновок

Завдяки цьому документу ви дізналися, як легко використовувати API OpenAI Images Edits для використання офіційних функцій редагування зображень OpenAI. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.