dall-e-2, gpt-image-1, найновішу модель gpt-image-2, а також серію моделей nano-banana / nano-banana-2 / nano-banana-pro, підключених через той самий інтерфейс.
Цей документ головним чином описує процес використання OpenAI Images Edits API, що дозволяє легко користуватися офіційними функціями редагування зображень OpenAI.
Процес подачі заявки
Щоб користуватися OpenAI Images Edits API, спочатку перейдіть на сторінку OpenAI Images Edits API та натисніть кнопку «Acquire» для отримання необхідних облікових даних: Якщо ви ще не увійшли або не зареєстровані, вас автоматично перенаправлять на сторінку входу, де можна зареєструватися та увійти. Після входу ви повернетесь на цю сторінку. При першій подачі заявки надається безкоштовний ліміт для безкоштовного використання API.Модель GPT-Image-2
У сценаріях редагування зображеньgpt-image-2 має суттєві покращення у порівнянні з gpt-image-1:
- Стабільніше збереження структури: при зміні шкіри, кольорів чи фону майже не порушується макет і композиція оригінального зображення.
- Точніше збереження тексту: у інфографіках, постерах, меню та інших зображеннях з текстом текст залишається чітким і читабельним після редагування.
- Підтримка прямої передачі URL: окрім традиційного завантаження файлів через
multipart/form-data,gpt-image-2також підтримує передачу URL зображень у форматі JSON, що дозволяє не завантажувати зображення локально — ідеально для серверних конвеєрів. - Підтримка високої роздільної здатності: можна передати 1K оригінал і через параметр
sizeзапросити вихід 2K / 4K, модель одночасно виконає масштабування під час редагування.
Підтримувані значення параметра size
Обмеження параметра size в інтерфейсі редагування повністю збігаються з інтерфейсом генерації — gpt-image-2 приймає size зі значеннями auto, порожнє або у форматі WIDTHxHEIGHT. Будь-які інші варіанти повернуть помилку 400. Вартість розраховується за одне зображення незалежно від роздільної здатності оригіналу та запиту size.
Жорсткі обмеження на розмір: ширина і висота мають бути кратні 16, довга сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400.
Наприклад: якщо оригінал1024x1024, приsize=2048x2048модель відредагує та виведе 2K зображення; приsize=3840x2160— 4K горизонтальне; приautoабо відсутності параметра модель вибере сама. Вартість усіх трьох варіантів однакова.
Про параметрНижче наведено два реальні приклади, що демонструють можливості редагуванняnІнтерфейс редагуванняgpt-image-2наразі не підтримуєn > 1: цей параметр ігнорується, незалежно від значенняnповертається лише одне зображення і стягується плата за одне. Якщо потрібно отримати кілька варіантів, слід робити кілька паралельних запитів. Це обмеження також діє дляgpt-image-1/gpt-image-1.5та серіїnano-banana. Лишеdall-e-2підтримуєn > 1нативно.
gpt-image-2.
Варіант виклику 1: JSON + URL зображення (рекомендовано)
Відправляйте запит у форматіapplication/json, у полі image вказуйте URL зображення — модель завантажить його та відредагує згідно з prompt.
Наприклад, оригінальне зображення — науково-популярна ілюстрація, згенерована gpt-image-2:
Ми хочемо змінити кольорову схему на «нічний режим». Запит виглядає так:
Підказка: полеimageпідтримує масив URL, наприклад"image": ["url1", "url2", "url3"], можна передати до 16 зображень для комплексного редагування.
Варіант виклику 2: JSON + кілька референсних зображень
gpt-image-2 підтримує одночасне використання кількох зображень для створення результату, наприклад, об’єднання кількох фото товарів у кошик подарунків:
Приклад сценарію: зміна стилю + збереження структури
Інший приклад — замінити дерев’яну книжкову полицю на сучасну плаваючу, при цьому строго зберегти кількість і розташування книг на кожній полиці. Оригінал (створенийgpt-image-2 дерев’яна полиця):
Запит:
task_id: e9544dba-727e-44a2-81e1-223d49869380):
Стиль і оточення повністю змінені відповідно до підказки, але кількість книг (1 / 3 / 7) збережена, а також додано маленьку сукуленту на верхній полиці.
Варіант виклику 3: 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 через адаптаційний шар підтримує лише параметри:model,prompt,image.
imageможна передавати черезmultipart/form-data(внутрішньо конвертується уdata:<mime>;base64,...) або як URL у формі.- Параметри
mask,n,size,response_formatне підтримуються і ігноруються.- Відповідь відповідає формату OpenAI (
data[].url), алеcreatedзавжди 0,b64_jsonне повертається, аrevised_promptзавжди дорівнює оригінальномуprompt.
Виклик через форму + URL зображення
Виклик через форму + локальний файл
Асинхронний callback
Механізм асинхронного callback черезcallback_url також підтримується для nano-banana, процес виклику ідентичний іншим моделям (див. розділ Асинхронний callback).
Основне використання
Далі можна викликати API через код. Приклад виклику через CURL:authorization (вибирається зі списку), model (модель OpenAI, тут доступна одна основна, див. опис моделей), prompt (текстова підказка для генерації зображення) та image (шлях до зображення для редагування). Нижче приклад зображення для редагування:
Еквівалентний приклад на Python:
OPENAI_BASE_URL на https://api.acedata.cloud/openai та OPENAI_API_KEY на отриманий токен. У Mac OS це можна зробити так:
gift-basket.png з результатом:
Таким чином, ми завершили операцію редагування зображення. Інтерфейс Edits підтримує три моделі: dall-e-2, gpt-image-1 та gpt-image-2, причому рекомендована модель — gpt-image-2 (див. розділ Модель GPT-Image-2).
Асинхронний callback
Оскільки редагування зображень через OpenAI Images Edits API може займати тривалий час, HTTP-запит може довго утримувати з’єднання, що призводить до додаткових витрат системних ресурсів. Тому API підтримує асинхронний callback. Загальний процес: клієнт при запиті вказує полеcallback_url. Після отримання запиту API одразу повертає результат із полем task_id, що ідентифікує завдання. Коли завдання завершується, результат редагування надсилається POST-запитом у форматі JSON на вказаний callback_url, включно з task_id для зв’язку результату із завданням.
Розглянемо приклад.
Webhook callback — це HTTP-сервер, який приймає запити. Розробник повинен замінити URL на власний сервер. Для демонстрації можна використати публічний сервіс https://webhook.site/, який генерує унікальний URL:
Скопіюйте цей URL, наприклад https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, і використовуйте як callback_url у запиті:
task_id та поле data з результатом редагування, як і при синхронному виклику. За task_id можна зв’язати результат із завданням.
Обробка помилок
При виклику API у разі помилки повертається код та повідомлення про помилку. Наприклад:400 token_mismatched: некоректний запит, можливо відсутні або невірні параметри.400 api_not_implemented: некоректний запит, можливо відсутні або невірні параметри.401 invalid_token: неавторизовано, недійсний або відсутній токен.429 too_many_requests: перевищено ліміт запитів.500 api_error: внутрішня помилка сервера.

