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 и запросить вывод в 2K или 4K через параметр size, модель одновременно выполнит редактирование и масштабирование.

Поддерживаемые значения `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 изображение согласно инструкции и будет тарифицироваться по уровню «другие»; при size 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 поддерживает передачу массива URL, например "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 любое из значений из таблицы ниже.

Модель	Стоимость (кредиты за запрос)	Сценарии использования
`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,... для апстрима), либо как 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.

Основное использование

Далее пример вызова через 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 SDK необходимо задать два переменных окружения: OPENAI_BASE_URL в https://api.xhuoapi.ai/v1/openai и OPENAI_API_KEY — полученный токен. В macOS это можно сделать так:

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

После вызова в текущей директории появится файл gift-basket.png с результатом:

Таким образом, мы завершили операцию редактирования изображения. В настоящее время Edits API поддерживает три модели: dall-e-2, gpt-image-1 и gpt-image-2. Рекомендуется использовать gpt-image-2, подробнее в разделе Модель GPT-Image-2.

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

Поскольку время редактирования изображения может быть значительным, при длительном отсутствии ответа API HTTP-соединение остаётся открытым, что приводит к дополнительным затратам ресурсов. Поэтому API поддерживает асинхронные callback. Общий процесс: клиент при запросе дополнительно указывает поле callback_url. API сразу возвращает ответ с полем task_id — идентификатором задачи. После завершения обработки результат редактирования отправляется POST-запросом в формате JSON на указанный callback_url, включая task_id для связи с задачей. Рассмотрим пример. Webhook callback — это HTTP-сервис, который должен принимать запросы. Разработчик должен заменить URL на свой сервер. Для демонстрации можно использовать публичный сервис https://webhook.site/, где можно получить URL webhook, например:

Скопируйте 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 можно увидеть результат:

{
  "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 возвращает соответствующий код и сообщение, например:

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

Обработка ошибок

Пример ответа с ошибкой

Заключение