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

Сервіс редагування зображень 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.

Співвідношення	1K (стандартна ціна)	2K рекомендоване (×1.5)	4K рекомендоване (×1.5)
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 зображення, тарифікується як «інші»; при 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:

Ми хочемо змінити кольорову схему на «нічний режим». Виклик:

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/v1/openai/images/edits"

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

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/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.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

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

Як видно, структура модулів, розподіл інформації, шрифти збережені, змінено лише кольорову схему на темну.

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

Варіант виклику 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.xhuoapi.ai/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="Convert this image to dark mode while keeping the layout intact."
)

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.xhuoapi.ai/v1/openai та OPENAI_API_KEY у значення отриманого токена:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

Серія моделей Nano Banana

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

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

Важливо: підтримувані параметри 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 зображення

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Відповідь:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

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

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

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

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

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

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

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

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

Базове використання

Далі можна викликати API кодом. Нижче приклад через 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.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

При першому використанні потрібно вказати щонайменше чотири параметри: authorization (вибирається зі списку), model (модель OpenAI, тут доступна одна — див. таблицю моделей), prompt (текстова підказка для генерації зображення), image (шлях до зображення для редагування). Приклад зображення:

Еквівалентний приклад на Python:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

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.xhuoapi.ai/v1/openai та OPENAI_API_KEY зі значенням токена:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token} 

Після виклику у поточній директорії з’явиться файл 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:

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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"
}

Через деякий час на webhook.site з’явиться результат редагування:

{
  "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 з результатом редагування, що дозволяє зв’язати завдання за ID.

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

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

Documentation Index

​Процес отримання доступу

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

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

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

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

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

​Варіант виклику 3: multipart/form-data (сумісність з OpenAI SDK)

​Серія моделей Nano Banana

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

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

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

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

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

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

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

​Висновок

Процес отримання доступу

Модель GPT-Image-2

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

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

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

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

Варіант виклику 3: multipart/form-data (сумісність з OpenAI SDK)

Серія моделей Nano Banana

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

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

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

Базове використання

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

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

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

Висновок