Skip to main content
Сервіс редагування зображень OpenAI дозволяє передавати будь-яку кількість зображень та інструкцій, отримуючи на виході відредаговані зображення. Наразі інтерфейс підтримує 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:

Ми хочемо змінити кольорову схему на «нічний режим». Запит виглядає так:
Або на Python:
Відповідь:
Відредаговане зображення:

Структура модулів, розподіл інформації та шрифти збережені, змінена лише кольорова схема на темну.
Підказка: поле 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:
Для роботи з SDK потрібно встановити два змінні середовища: 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:
Для виклику через 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 у запиті:
Відразу отримаємо відповідь:
Через деякий час у Webhook URL з’явиться результат редагування:
У відповіді є поле task_id та поле data з результатом редагування, як і при синхронному виклику. За task_id можна зв’язати результат із завданням.

Обробка помилок

При виклику API у разі помилки повертається код та повідомлення про помилку. Наприклад:
  • 400 token_mismatched: некоректний запит, можливо відсутні або невірні параметри.
  • 400 api_not_implemented: некоректний запит, можливо відсутні або невірні параметри.
  • 401 invalid_token: неавторизовано, недійсний або відсутній токен.
  • 429 too_many_requests: перевищено ліміт запитів.
  • 500 api_error: внутрішня помилка сервера.

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

Висновок

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