OpenAI Images Edits API Заявка та використання

OpenAI сервіс редагування зображень дозволяє передавати зображення та команди, виводячи змінене зображення. Моделі серії GPT Image можуть одночасно приймати до 16 референсних зображень. Наразі інтерфейс підтримує 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: офіційний канал, стабільний та відповідний. Вартість визначається токенами текстового вводу, токенами зображення під час редагування та токенами виходу зображення, остаточний розрахунок проводиться за фактичним використанням, вказаним у відповіді; ціна якості/розміру, що відображається на сторінці, використовується лише для оцінки; за максимальним пакетом Usage ціна для клієнтів становить приблизно 80% від офіційної ціни OpenAI. Сервіс автоматично обирає доступні канали, можливості та витрати визначаються за фактичними результатами.
gpt-image-2:reverse: повністю еквівалентно за замовчуванням gpt-image-2, з кращим співвідношенням ціни та якості, ціна залишається незмінною.

:official формула розрахунку Остаточна вартість = токен текстового вводу + токен зображення (тільки редагування) + токен виходу зображення. Ціна, що відображається на сторінці quality × size, є оцінкою перед запитом, фактичні витрати визначаються за успішною відповіддю usage. Наприклад, low, 1024x1024 зазвичай становить близько 0.0505 кредитів за вихід зображення, плюс невелика кількість токенів вводу; при використанні auto модель може вибрати вищу якість, попередньо авторизований ліміт буде перевірятися за більш високими ставками.

Підтримувані значення `size`

Перевірка формату size для інтерфейсу редагування відповідає інтерфейсу генерації — gpt-image-2 вимагає, щоб size був auto, порожнім або відповідав формату WIDTHxHEIGHT, будь-яка інша форма поверне 400. За замовчуванням gpt-image-2 та :reverse стягують плату за кожне зображення однаково; :official одночасно розраховує токени текстового вводу, токени референсних зображень та токени виходу зображення, оригінал, розмір та якість можуть вплинути на остаточну вартість. Обмеження розміру: користувацькі розміри повинні відповідати кратності 16 для ширини та висоти, довга сторона ≤ 3840, загальна кількість пікселів ≤ 8,294,400, перевищення призведе до повернення 4xx.

Співвідношення	Рекомендоване 1K	Рекомендоване 2K	Рекомендоване 4K
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

Наприклад: якщо оригінал має розмір 1024x1024, а size передається як 2048x2048, модель переробить та виведе 2K зображення відповідно до інструкцій редагування; якщо size передається як 3840x2160, буде виведено 4K горизонтальне зображення. За замовчуванням стягнення за три розміри gpt-image-2 та :reverse однакове; :official базується на фактичному використанні токенів. Пропуск поля size та явна передача auto є абсолютно еквівалентними: gpt-image-2 спочатку зчитує чіткі наміри щодо розміру з підказок, включаючи пікселі, співвідношення, орієнтацію, роздільну здатність (наприклад, 4K / high-res) або назву полотна. Якщо виявлено наміри щодо розміру, використовуються конкретні розміри; якщо в підказках немає вимог до розміру або автоматичне визначення недоступне, повертається розмір першого референсного зображення. Остаточний конкретний розмір буде нормалізовано до кратності 16, обмежень для довгої сторони та загальної кількості пікселів перед подачею запиту; для абсолютного контролю, будь ласка, передайте безпосередньо WIDTHxHEIGHT. Після завершення генерації не буде автоматичних повторних спроб через різні вихідні пікселі, щоб уникнути повторних витрат на генерацію. Про параметр n Інтерфейс редагування gpt-image-2 підтримує n > 1: одночасно можна отримати відповідну кількість результатів редагування. За замовчуванням gpt-image-2 та :reverse стягують плату за кількість успішно згенерованих зображень; :official стягує плату за фактичне використання токенів за всю відповідь (значення n від 1 до 10). Це також стосується gpt-image-1 / gpt-image-1.5, а також серій nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. Зверніть увагу, що response_format=b64_json підтримує лише n=1, при n>1 використовуйте стандартне повернення URL. Якщо деякі зображення не вдалося згенерувати, буде повернуто та стягнуто плату лише за успішні частини.

Нижче наведено два різних реальних приклади, щоб відчути можливості редагування gpt-image-2.

Спосіб виклику 1: JSON + URL зображення (рекомендується)

Надішліть запит у форматі application/json, заповнивши поле image URL однієї картинки, модель завантажить це зображення та відредагує його відповідно до prompt. Наприклад, нижче наведено оригінальне зображення, яке було згенеровано за допомогою gpt-image-2:

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

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

Або за допомогою Python:

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Результат буде таким:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

Редаговане зображення виглядає так:

Можна побачити, що структура модулів, інформаційні зони, типографіка були строго збережені, лише кольорова схема була перевернута на темну тему.

Порада: Поле image також підтримує передачу масиву, наприклад, "image": ["url1", "url2", "url3"], максимум можна передати 16 зображень для редагування.

Прямий base64: image (та кожен елемент масиву) може бути не лише URL, а й base64 — data:image/png;base64,... або чистий base64, що підходить для локальних зображень, які не хочуть попередньо завантажувати на хостинг. Наприклад:
import base64, requests
b64 = base64.b64encode(open("input.png", "rb").read()).decode()
payload = {
    "model": "gpt-image-2",
    "image": f"data:image/png;base64,{b64}",
    "prompt": "Convert this infographic to dark mode.",
    "size": "1024x1536"
}
requests.post("https://api.acedata.cloud/openai/images/edits", json=payload,
              headers={"authorization": "Bearer {token}"})

Спосіб виклику 2: JSON + кілька зображень для посилання

gpt-image-2 підтримує одночасне використання кількох зображень для генерації фінального результату, наприклад, об’єднання кількох фотографій продуктів в один подарунковий кошик:

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

Приклад сценарію: змінити стиль + зберегти структуру

Ось ще один приклад, де дерев’яна книжкова полиця замінюється на сучасну плаваючу полицю, але строго зберігається кількість і розташування книг на кожному рівні. Оригінальне зображення (згенероване за допомогою gpt-image-2 дерев’яної книжкової полиці):

Виклик:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

Результат редагування (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:

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Перетворіть це зображення в темний режим, зберігаючи макет незмінним."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

При використанні SDK потрібно спочатку імпортувати дві змінні середовища, OPENAI_BASE_URL встановити на https://api.acedata.cloud/openai, OPENAI_API_KEY встановити на отриманий токен:

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

Моделі серії Nano Banana

Серія nano-banana також підключена до /openai/images/edits в сценаріях редагування, просто змініть model на будь-який з наведених у таблиці.

Модель	Оплата (Credits / раз)	Сценарії використання
`nano-banana`	0.14	Звичайне редагування зображень, найшвидше, найнижча вартість
`nano-banana-2-lite`	0.14	Легка модель зображень Gemini 3.1, підтримує лише 1K, редагування з низькою затримкою
`nano-banana-2`	0.28	Якість і деталі помітно покращені
`nano-banana-pro`	0.35	Флагман серії, найкраще збереження структури, тексту, стилю

Важливо: діапазон підтримуваних параметрів Nano Banana підключається до протоколу OpenAI через адаптаційний шар, підтримує лише такі параметри: model, prompt, image, n.

image може бути завантажено через multipart/form-data (локальні файли автоматично перетворюються в base64), також можна передати URL зображення через поля форми.

Не підтримуються параметри mask, size, response_format тощо; якщо їх вказати, вони будуть проігноровані. n > 1 підтримується (1–10), буде повернуто та нараховано відповідну кількість результатів редагування.

Структура відповіді відповідає формату OpenAI (data[].url), але created завжди дорівнює 0, і не буде повернуто b64_json, revised_prompt завжди дорівнює оригінальному prompt.

Виклик через форму + URL зображення

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=додати зелене листя на верхівку яблука" \
  -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Повернене значення виглядає так:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "додати зелене листя на верхівку яблука"
    }
  ]
}

Редаговане зображення:

Виклик через форму + локальний файл

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "додати зелене листя на верхівку яблука"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

Асинхронний зворотний виклик

Механізм асинхронного зворотного виклику callback_url також діє для nano-banana, процес виклику повністю аналогічний іншим моделям, детальніше див. розділ Асинхронний зворотний виклик.

Основне використання

Тепер ви можете використовувати код для виклику, нижче наведено приклад виклику через CURL:

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Створіть милий подарунковий кошик з цими предметами в ньому'

При першому використанні цього інтерфейсу нам потрібно заповнити щонайменше чотири поля: одне з них - authorization, яке можна вибрати безпосередньо зі списку. Інший параметр - model, model - це категорія моделі OpenAI, яку ми вибираємо, тут у нас є 1 модель, деталі можна переглянути в наданих моделях. Ще один параметр - prompt, prompt - це підказка, яку ми вводимо для генерації зображення. Останній параметр - image, цей параметр вимагає шлях до зображення, яке потрібно редагувати, зображення, яке потрібно редагувати, показано нижче:

Підказка: image[] може повторюватися кілька разів для завантаження кількох зображень, наприклад, -F "image[]=@a.png" -F "image[]=@b.png", серія GPT Image підтримує до 16 зображень (кожне не більше 50MB, формати png/webp/jpg). Перевищення кількості призведе до повернення 400.

Приклад коду для виклику з однаковим ефектом на Python:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Згенеруйте фотореалістичне зображення подарункового кошика на білому фоні 
з написом 'Розслабтесь і відпочиньте' з стрічкою та шрифтом, схожим на рукописний, 
який містить усі предмети з референсних зображень.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Зберегти зображення у файл
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

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

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

Після виклику ми виявимо, що в поточному каталозі з’явиться зображення gift-basket.png, конкретний результат виглядає так:

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

Асинхронний зворотний виклик

Оскільки редагування зображень за допомогою OpenAI Images Edits API може займати відносно багато часу, якщо API не відповідає протягом тривалого часу, HTTP-запит буде підтримувати з’єднання, що призведе до додаткових витрат системних ресурсів. Тому цей API також підтримує асинхронні зворотні виклики. Загальний процес такий: коли клієнт ініціює запит, він додатково вказує поле callback_url. Після ініціації API-запиту 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 на вказаний вище URL Webhook, а також заповнити відповідні параметри, як показано в наступному коді:

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

Після виклику можна відразу отримати результат, як показано нижче:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Через деякий час ми можемо спостерігати результати редагування зображення на URL Webhook, вміст виглядає так:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

Можна побачити, що в результаті є поле task_id, а поле data містить результати редагування зображення, аналогічні результатам синхронного виклику, за допомогою поля task_id можна пов’язати завдання.

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

При виклику API, якщо виникає помилка, API повертає відповідний код помилки та інформацію. Наприклад:

400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.
400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.
401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.
429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.
500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Висновок

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

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Coding

OpenAI Images Edits API Заявка та використання

Процес заявки

Модель GPT-Image-2

Варіанти маршруту (`:official` / `:reverse`)

Підтримувані значення `size`

Спосіб виклику 1: JSON + URL зображення (рекомендується)

Спосіб виклику 2: JSON + кілька зображень для посилання

Приклад сценарію: змінити стиль + зберегти структуру

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

Моделі серії Nano Banana

Виклик через форму + URL зображення

Виклик через форму + локальний файл

Асинхронний зворотний виклик

Основне використання

Асинхронний зворотний виклик

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

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

Висновок

​Процес заявки

​Модель GPT-Image-2

​Варіанти маршруту (:official / :reverse)

​Підтримувані значення size

​Спосіб виклику 1: JSON + URL зображення (рекомендується)

​Спосіб виклику 2: JSON + кілька зображень для посилання

​Приклад сценарію: змінити стиль + зберегти структуру

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

​Моделі серії Nano Banana

​Виклик через форму + URL зображення

​Виклик через форму + локальний файл

​Асинхронний зворотний виклик

​Основне використання

​Асинхронний зворотний виклик

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

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

​Висновок

Процес заявки

Модель GPT-Image-2

Варіанти маршруту (`:official` / `:reverse`)

Підтримувані значення `size`

Спосіб виклику 1: JSON + URL зображення (рекомендується)

Спосіб виклику 2: JSON + кілька зображень для посилання

Приклад сценарію: змінити стиль + зберегти структуру

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

Моделі серії Nano Banana

Виклик через форму + URL зображення

Виклик через форму + локальний файл

Асинхронний зворотний виклик

Основне використання

Асинхронний зворотний виклик

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

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

Висновок