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还额外支持以 JSON 方式传入图片 URL,无需先把图片下载到本地,非常适合服务端流水线接入。 - 支持 base64 直传:和官方一致,
image字段也可以直接传 base64(data:image/png;base64,...或裸 base64),本地图片无需先上传到图床即可编辑。 - 支持高分辨率重绘:可以传入一张 1K 原图,通过
size参数请求 2K / 4K 输出,模型会在编辑过程中同时完成放大。
线路变体(:official / :reverse)
gpt-image-2 默认走标准线路。通过模型名后缀可以显式选择线路:
gpt-image-2:official:官方通道,稳定合规。费用由文字输入 Token、编辑时的图片输入 Token 和图片输出 Token 共同决定,最终按响应中的实际用量结算;页面显示的质量/尺寸价格仅用于估算;按最大 Usage 套餐折算,客户价格约为 OpenAI 官方标准价的 8 折。服务会在可用通道间自动容错,能力与费用以实际返回结果为准。gpt-image-2:reverse:与默认gpt-image-2完全等价,性价比更高,价格不变。
:official计费公式 最终费用 = 文字输入 Token + 图片输入 Token(仅编辑)+ 图片输出 Token。页面展示的quality × size价格是请求前估算,实际扣费以成功响应的usage为准。例如,low、1024x1024通常约为 0.0505 Credits 的图片输出费用,另加少量输入 Token;使用auto时模型可能选择更高质量,预授权额度会按较高档位保守检查。
支持的 size 取值
编辑接口对 size 的格式校验与生成接口一致——gpt-image-2 只需要 size 为 auto、空,或者符合 WIDTHxHEIGHT 格式,任何其他形态会返回 400。默认 gpt-image-2 与 :reverse 按单张统一扣费;:official 会同时计算文字输入、参考图输入与图片输出 Token,原图、尺寸和质量都可能影响最终费用。
尺寸限制:自定义尺寸须满足宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400,超出会返回 4xx。
例如:原图是Ниже приведены два различных примера, чтобы почувствовать возможности редактирования1024x1024,size传2048x2048时,模型会按编辑指令重绘并输出 2K 图;size传3840x2160时输出 4K 横屏图。默认gpt-image-2与:reverse的三种尺寸计费一致;:official以实际 Token 用量为准。 省略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:


Подсказка: Полеimageтакже поддерживает передачу массива, например,"image": ["url1", "url2", "url3"], можно одновременно передать до 16 ссылок на изображения, чтобы модель могла учитывать несколько изображений при редактировании.
Прямой ввод base64:image(и каждый элемент массива) может быть не только URL, но и base64 —data:image/png;base64,...или чистый base64, что подходит для локальных изображений, которые не нужно загружать на хостинг. Например:
Способ вызова 2: JSON + несколько ссылок на изображения
gpt-image-2 поддерживает одновременное использование нескольких изображений для генерации конечного результата, например, объединение нескольких фотографий продуктов в одну корзину подарков:
Пример сценария: смена стиля + сохранение структуры
Вот еще один пример, где деревянная полка заменяется на современную плавающую полку, но строго сохраняется количество и расположение книг на каждом уровне. Оригинальное изображение (деревянная полка, сгенерированная с помощьюgpt-image-2):

task_id: e9544dba-727e-44a2-81e1-223d49869380):

Способ вызова 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,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 изображения

Вызов через форму + локальный файл
Асинхронный обратный вызов
Механизм асинхронного обратного вызоваcallback_url также работает для nano-banana, процесс вызова полностью аналогичен другим моделям, см. раздел Асинхронный обратный вызов.
Основное использование
Теперь вы можете использовать код для вызова, ниже приведен пример вызова через CURL:authorization, которое можно выбрать из выпадающего списка. Другой параметр — это model, model — это категория модели OpenAI, которую мы выбираем, здесь у нас в основном 1 модель, подробности можно посмотреть в предоставленной модели. Еще один параметр — это prompt, prompt — это подсказка, которую мы вводим для генерации изображения. Последний параметр — это image, этот параметр указывает путь к изображению, которое нужно отредактировать, как показано на рисунке ниже:
Подсказка:image[]может повторяться несколько раз для загрузки нескольких изображений, например-F "image[]=@a.png" -F "image[]=@b.png", модели серии GPT Image поддерживают до 16 изображений (каждое не более 50 МБ, форматы png/webp/jpg). Превышение количества приведет к ошибке 400.

OPENAI_BASE_URL, которую можно установить на https://api.acedata.cloud/openai, и другую переменную для использования токена OPENAI_API_KEY, это значение получается из authorization, в Mac OS можно установить переменные окружения следующей командой:
gift-basket.png, конкретный результат будет следующим:

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

