Skip to main content
POST
Image Edit: edit or fuse reference images by instruction
Интерактивная песочница справа поддерживает прямую локальную загрузку изображений. Введите свой API Key в Authorization (формат: Bearer sk-xxx), выберите файлы изображения / маски, заполните prompt и model, и отправьте.
Сценарий использования: Эта страница предназначена для «edit / fuse / inpaint based on one or more reference images». Формат запроса — multipart/form-data. Для чистого text-to-image используйте эндпоинт Text-to-Image.
🖥️ Ограничение браузерной песочницы (важно)Этот endpoint возвращает в ответе сырую base64-строку (обычно размером в несколько MB). Из-за ограничений рендеринга браузера песочница справа может показать 请求时发生错误: unable to complete request после получения ответа — запрос на самом деле успешно выполнен; браузер просто не может отобразить такую длинную base64-строку.Рекомендуемый рабочий процесс (подходит для новичков):
  • Скопируйте приведенный ниже пример на Python / Node.js / cURL и запустите его локально. Код автоматически base64.b64decodes ответ и записывает изображение в файл.
  • Если вам все же нужно использовать встроенную в браузер песочницу, используйте крошечное референсное изображение (< 50KB), установите size на самый низкий уровень (например, 1024x1024), и quality на low.
⚠️ Ключевые отличия (при переходе с gpt-image-1.5)
  • Не передавайте input_fidelitygpt-image-2 принудительно включает high-fidelity; при передаче этого параметра возвращается 400
  • У запросов на редактирование заметно больше input tokens — референсы превращаются в большое число tokens через тарификацию Vision; закладывайте это в бюджет
  • background: transparent не поддерживается — используйте opaque или выполните постобработку
  • Слияние нескольких изображений: максимум 16 — повторяйте поле image[]; при количестве больше 16 возвращается ошибка
📎 Порядок слияния нескольких изображений имеет значениеПоле image[] принимает несколько референсных изображений. Порядок загрузки соответствует ссылкам на «изображение 1 / изображение 2 / изображение 3» в prompt. Ссылайтесь на них явно:
Поместите объект из изображения 1 в сцену из изображения 2, используя цветовой стиль изображения 3
Ограничение на файл: менее 50MB для каждого (multipart file upload), форматы: png / jpg / webp; на практике перед загрузкой сжимайте до не более 1.5MB (см. «Ограничения размера загрузки» ниже).

Примеры кода

Python (OpenAI SDK · редактирование одного изображения)

Python (OpenAI SDK · объединение нескольких изображений)

cURL (объединение нескольких изображений)

cURL (дорисовка по маске)

Node.js (Native fetch + FormData · объединение нескольких изображений)

Справочник параметров

Не передавайте устаревшие значения DALL·E standard / hd для quality. Принимаются только четыре официальных значения enum low / medium / high / auto. Устаревшие значения ведут себя непоследовательно в разных backend-каналах: иногда они сразу завершаются с 400 (invalid_value), а иногда тихо игнорируются, и запрос выполняется с auto (непредсказуемая стоимость). Всегда явно передавайте одно из четырех официальных значений.

Ограничения на размер загрузки

Не заполняйте общий размер запроса до максимума: хотя лимит на одно изображение составляет 50MB и можно загрузить до 16 изображений, несколько изображений почти у верхней границы делают тело одного запроса огромным и повышают вероятность сбоев шлюз / CDN / timeout. На практике сжимайте каждое изображение до 1.5MB (JPEG quality 80-90) — вероятность успеха и скорость генерации заметно повышаются, а качество результата не зависит от размера исходного файла.

Требования к формату эталонного изображения и предварительная обработка

/v1/images/edits принимает только стандартные форматы png / jpg / webp. Если вы получаете эту ошибку 400:
эталонное изображение, скорее всего, не является стандартным JPEG/PNG. Самая частая ловушка — это формат MPO (Multi-Picture Object, многокадровый контейнер JPEG) из камер смартфонов: файлы .jpg, полученные прямо с телефонов серии Huawei Mate, содержат вложенный подкадр HDR gain-map и на самом деле являются MPO. Эти файлы начинаются с того же заголовка FFD8расширение и команда file оба сообщают JPEG — поэтому их невозможно распознать визуально; определить это может только разбор с учетом кадров (например, Pillow). «изображение 1» в сообщении об ошибке относится к N-му эталонному изображению (нумерация с 1), поэтому используйте индекс, чтобы найти проблемный файл.
Проверено в июле 2026: файлы MPO завершались ошибкой 400 во всех 5/5 загрузках; те же изображения, перекодированные в стандартный JPEG/PNG, успешно проходили при полном исходном разрешении 3072×4096 — проблема в формате, а не в размерах или объеме файла. Ошибка возвращается быстро (~4s) на этапе проверки входных данных и не тарифицируется.
Обнаружение и исправление: если Image.open(f).format возвращает "MPO", файл нужно конвертировать. Один шаг повторного кодирования в вашем пайплайне загрузки также покрывает HEIC и другие форматы смартфонов:
Если ваш продукт принимает фотографии, снятые пользователями (рендеры интерьеров, фотографии товаров и т. д.), выполняйте повторное кодирование единообразно на стороне сервера вместо отладки изображений по одному — HDR-фото со смартфонов будут продолжать появляться. Дополнительные советы по обработке входных данных: Основы Image API и лучшие практики.

Требования к Mask Inpainting

  • Тот же размер, что и у оригинала, формат PNG, меньше 4MB
  • Обязательно наличие alpha channel: прозрачные области (alpha=0) = область inpaint, непрозрачные = сохранять
  • Маска применяется только к первому изображению
  • Маска — это «мягкая подсказка»: модель может расширять или сужать область вокруг замаскированного региона
Итерация в несколько шагов: передавайте предыдущий результат обратно как image[] следующего вызова с новой инструкцией для постепенной доработки. Каждый раунд тарифицируется отдельно по tokens — следите за совокупной стоимостью.

Формат ответа

b64_json — это необработанный base64, без префикса data:image/...;base64, — в отличие от gpt-image-2-all. Декодируйте его на стороне клиента, чтобы записать файл, или добавьте префикс для отображения в браузере.
input_tokens у запросов на редактирование обычно значительно выше, чем у генерации изображений по тексту при том же размере, поскольку опорные изображения тарифицируются по правилам тарификации Vision — точная сумма доступна напрямую в usage.input_tokens_details.image_tokens и учитывается отдельно от текстовой части (text_tokens). Объединение нескольких изображений увеличивает image_tokens строго линейно с каждым дополнительным опорным изображением (проверено в июле 2026: 4 × 1024² изображений = 4 × 1024 tokens) — см. Как несколько входных изображений влияют на стоимость для таблицы измерений. См. Как проверить фактическое количество token для каждого вызова на странице обзора для полной справки по полям.

Авторизации

Authorization
string
header
обязательно

API Key obtained from APIYI Console

Тело

multipart/form-data
model
enum<string>
по умолчанию:gpt-image-2
обязательно

Model name, fixed as gpt-image-2

Доступные опции:
gpt-image-2
prompt
string
обязательно

Edit/fusion instruction. For multi-image, use 'image 1 / image 2 / image 3' to reference upload order

Пример:

"Place subject from image 1 into scene from image 2, using color style from image 3"

image
file[]
обязательно

Reference images. For a single image, send the field once; for multiple images, repeat the same image field (e.g., -F [email protected] -F [email protected], max 16) — upload order maps to image 1 / image 2 / ... in the prompt. multipart file upload: each under 50MB, formats: png/jpg/webp; compress to within 1.5MB in practice

mask
file

Mask image (optional, only applies to first image). Requirements:

  • Same size as original
  • PNG format, under 4MB
  • Must have alpha channel (alpha=0 = inpaint area, opaque = preserve)
size
string
по умолчанию:auto

Output size (same as text-to-image). Preset or constraint-satisfying custom size

Пример:

"1536x1024"

quality
enum<string>
по умолчанию:auto

Quality tier

Доступные опции:
auto,
low,
medium,
high
output_format
enum<string>
по умолчанию:png

Output format

Доступные опции:
png,
jpeg,
webp
output_compression
integer

Output compression (0–100), only effective for jpeg/webp

Требуемый диапазон: 0 <= x <= 100
background
enum<string>
по умолчанию:auto

Background mode. auto or opaque. Not supported: transparent

Доступные опции:
auto,
opaque

Ответ

Image generated successfully

created
integer
Пример:

1776832476

data
object[]

Generation results (this model returns 1 image per call)

usage
object

Token usage for this call