Skip to main content
POST
Image Edit: edit or fuse reference images by instruction
Интерактивная площадка Playground справа поддерживает прямую локальную загрузку изображений. Укажите свой API Key в поле Authorization (формат: Bearer sk-xxx), выберите файлы изображения / маски, заполните prompt и model и отправьте запрос.
Сценарий использования: эта страница предназначена для «редактирования / объединения / дорисовки на основе одного или нескольких эталонных изображений». Формат запроса: multipart/form-data. Для обычной генерации изображений по тексту используйте эндпоинт генерации изображений по тексту.
🖥️ Ограничение браузерной площадки Playground (важно)Этот эндпоинт возвращает необработанную строку base64 (обычно размером в несколько МБ) в ответе. Из-за ограничений браузера на отображение площадка Playground справа может показать 请求时发生错误: unable to complete request после получения ответа — запрос фактически выполнен успешно; браузер просто не может отобразить настолько длинную строку base64.Рекомендуемый рабочий процесс (подходит начинающим):
  • Скопируйте приведённый ниже пример на Python / Node.js / cURL и запустите его локально. Код автоматически выполняет base64.b64decode для ответа и записывает изображение в файл.
  • Если необходимо использовать браузерную площадку Playground, используйте небольшое эталонное изображение (< 50 КБ), установите size на минимальный уровень (например, 1024x1024), а quality — на low.
⚠️ Ключевые отличия (при переходе с gpt-image-1.5)
  • Не передавайте input_fidelity — все три модели принудительно используют высокую точность; его передача приводит к ошибке 400 (проверено на версии 2.5 2026-09-09)
  • Запросы на редактирование требуют заметно больше входных token — эталонные изображения преобразуются в большое количество token по тарифам Vision; учитывайте это при планировании бюджета
  • Объединение нескольких изображений: максимум 16 — повторяйте поле image[]; при превышении 16 запрос завершается ошибкой
📎 Порядок объединения нескольких изображений имеет значениеПоле image[] принимает несколько эталонных изображений. Порядок загрузки определяет соответствие эталонных изображений «изображение 1 / изображение 2 / изображение 3» в промпте. Явно ссылайтесь на них:
Поместите объект с изображения 1 в сцену с изображения 2, используя цветовой стиль изображения 3
Ограничение для каждого файла: менее 50 МБ (загрузка файлов multipart), форматы: png / jpg / webp; на практике перед загрузкой сожмите файлы до размера не более 1,5 МБ (см. раздел «Ограничения размера загрузки» ниже).

Примеры кода

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

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

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

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

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

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

Не передавайте устаревшие значения DALL·E standard / hd для quality. Принимаются только шесть официальных значений перечисления low / medium / high / xhigh / max / auto (xhigh / max — только двумя моделями 2.5). Устаревшие значения ведут себя непоследовательно в разных 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.5-sunburst
обязательно

Model name. gpt-image-2.5-flare (speed-first) / gpt-image-2.5-sunburst (quality- and editing-first) / gpt-image-2 (previous generation) share the same price and parameters; pin a dated snapshot in production

Доступные опции:
gpt-image-2.5-flare,
gpt-image-2.5-sunburst,
gpt-image-2,
gpt-image-2.5-flare-2026-09-08,
gpt-image-2.5-sunburst-2026-09-08
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. xhigh / max are new in 2.5 and rejected by gpt-image-2

Доступные опции:
auto,
low,
medium,
high,
xhigh,
max
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