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:
  • 1K стандартна ціна: будь-який рекомендований розмір 1K з таблиці нижче або поширені 1K псевдоніми (1254x1254, 1672x941, 941x1672).
  • Інші тарифи (1.5×): рекомендовані 2K / 4K розміри з таблиці, а також будь-які ваші власні WIDTHxHEIGHT.
Жорсткі обмеження з боку сервера: ширина і висота мають бути кратні 16, довша сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400.
Наприклад: якщо оригінал 1024x1024, а size передано як 2048x2048, модель відредагує та виведе 2K зображення, тарифікується як «інші»; при 3840x2160 виводиться 4K горизонтальне зображення, також тарифікується як «інші»; при auto або пропущеному параметрі тарифікується як 1K стандартна ціна.
Про параметр 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 також підтримує масив, наприклад "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.xhuoapi.ai/v1/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,... для upstream), або як 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.xhuoapi.ai/v1/openai та OPENAI_API_KEY зі значенням токена:
Після виклику у поточній директорії з’явиться файл gift-basket.png. Результат:

Таким чином, ми завершили редагування зображення. Інтерфейс Edits підтримує три моделі: dall-e-2, gpt-image-1 та gpt-image-2, остання є рекомендованою (див. розділ GPT-Image-2 модель).

Асинхронний callback

Оскільки редагування зображень може займати тривалий час, щоб уникнути тривалого утримання HTTP-з’єднання і зайвих ресурсів, API підтримує асинхронний callback. Процес: клієнт при запиті вказує поле callback_url. API одразу повертає відповідь із task_id — ідентифікатором завдання. Після завершення редагування результат у форматі POST JSON надсилається на callback_url, включно з task_id для зв’язку результату із завданням. Приклад: Webhook callback — це HTTP-сервер, який приймає запити. Для демонстрації можна використати публічний сервіс https://webhook.site/, де після відкриття сайту отримаєте URL вебхука, наприклад: Скопіюйте URL, наприклад https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Далі виконайте запит із параметром callback_url:
Відповідь одразу:
Через деякий час на webhook.site з’явиться результат редагування:
У відповіді є task_id та поле data з результатом редагування, що дозволяє зв’язати завдання за 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. Якщо виникнуть питання, звертайтеся до нашої технічної підтримки.