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. Все размеры (1K / 2K / 4K / пользовательские) тарифицируются одинаково за каждое изображение, независимо от исходного разрешения и запрошенного size. Действуют жёсткие ограничения сверху: ширина и высота должны быть кратны 16, максимальная длина стороны — 3840, максимальное количество пикселей — 8 294 400.
Например: исходное изображение 1024x1024. При size = 2048x2048 модель перерисует изображение согласно инструкции и выдаст 2K. При size = 3840x2160 — 4K горизонтальное изображение. При auto или отсутствии параметра модель выберет размер самостоятельно. Стоимость всех трёх вариантов одинакова.
О параметре n В интерфейсе редактирования gpt-image-2 не поддерживается n > 1: этот параметр игнорируется, и независимо от значения (n=1 или n=10) возвращается только одно изображение и тарифицируется как одно. Если нужно получить несколько вариантов, необходимо самостоятельно параллельно отправлять несколько запросов. Это ограничение также распространяется на 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 интегрирован через адаптер OpenAI протокола и поддерживает только параметры: 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).

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

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

Аналогичный пример на Python:
Для работы с Python необходимо задать два переменных окружения: OPENAI_BASE_URL со значением https://api.acedata.cloud/openai и OPENAI_API_KEY с токеном из authorization. В 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 может быть достаточно долгим, при отсутствии ответа 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. Далее отправим запрос с указанием 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. Если у вас возникнут вопросы, обращайтесь в нашу техническую поддержку.