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:
Мы хотим изменить цветовую схему на «ночной режим». Запрос будет таким:
Совет: поле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:
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:
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:
task_id и поле data с результатом редактирования, аналогично синхронному вызову. По task_id можно связать задачу и результат.
Обработка ошибок
При ошибках API возвращает соответствующий код и сообщение, например:400 token_mismatched: неверный запрос, возможно, отсутствуют или некорректны параметры.400 api_not_implemented: неверный запрос, возможно, отсутствуют или некорректны параметры.401 invalid_token: неавторизован, неверный или отсутствующий токен.429 too_many_requests: превышен лимит запросов.500 api_error: внутренняя ошибка сервера.

