Skip to main content
OpenAI 图片编辑服务,可以传入图片和指令,输出修改之后的图片。GPT Image 系列模型最多可同时传入 16 张参考图。目前接口同时支持 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 为准。例如,low1024x1024 通常约为 0.0505 Credits 的图片输出费用,另加少量输入 Token;使用 auto 时模型可能选择更高质量,预授权额度会按较高档位保守检查。

支持的 size 取值

编辑接口对 size 的格式校验与生成接口一致——gpt-image-2 只需要 sizeauto、空,或者符合 WIDTHxHEIGHT 格式,任何其他形态会返回 400。默认 gpt-image-2:reverse 按单张统一扣费;:official 会同时计算文字输入、参考图输入与图片输出 Token,原图、尺寸和质量都可能影响最终费用。 尺寸限制:自定义尺寸须满足宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400,超出会返回 4xx。
例如:原图是 1024x1024size2048x2048 时,模型会按编辑指令重绘并输出 2K 图;size3840x2160 时输出 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:

Мы хотим изменить его на цветовую схему “ночного режима”. Можно вызвать так:
Или на Python:
Результат будет следующим:
Отредактированное изображение выглядит так:

Можно увидеть, что структура модулей, разделение информации и типографика были строго сохранены, только цветовая схема была инвертирована в темную тему.
Подсказка: Поле 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):

Можно увидеть, что стиль и окружение были полностью заменены в соответствии с подсказкой, но количество книг на каждом уровне (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, 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.

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

Таким образом, мы завершили редактирование изображения. В настоящее время интерфейс Edits поддерживает две модели: 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 и заполнить соответствующие параметры, как показано в следующем коде:
После вызова можно сразу получить результат, как показано ниже:
Через некоторое время мы можем наблюдать результат редактирования изображения по 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: Внутренняя ошибка сервера, что-то пошло не так на сервере.

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

Заключение

С помощью этого документа вы узнали, как легко использовать функции редактирования изображений OpenAI Images Edits API. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.