Перейти к основному содержанию
POST
Image Editing: Edit an existing image with text instructions
Интерактивная Песочница справа поддерживает выбор параметров из выпадающих списков. Введите свой API Key в поле Authorization (формат: Bearer sk-xxx), чтобы отправлять тестовые запросы одним щелчком.
Область действия: эта страница посвящена редактированию изображений. Необходимо предоставить входное изображение (закодированное в base64) вместе с инструкциями по редактированию. Чтобы создать новое изображение только по тексту, используйте эндпоинт преобразования текста в изображение.
🖥️ Ограничение Песочницы в браузере (важно)Этот эндпоинт возвращает изображение в кодировке base64 (inlineData.data, обычно несколько МБ). Из-за ограничений браузера на отображение Песочница справа после получения ответа может показать 请求时发生错误: unable to complete request — запрос на самом деле выполнен успешно; браузер просто не может отобразить такую длинную строку base64.Рекомендуемый порядок действий (подходит для начинающих):
  • Скопируйте приведённый ниже пример для Python / Node.js / cURL и запустите его локально. Код автоматически base64.b64decode ответ и сохраняет изображение в файл.
  • Если вам необходимо использовать Песочницу в браузере, возьмите крошечное исходное изображение (< 50KB) и установите для imageSize минимальный уровень (например, 512 / 1K).
⚠️ Структура массива parts (важно — прочитайте, если редактируете несколько изображений)Каждый part должен быть либо text, либо inlineData, но не обоими одновременно. Это соответствует официальному контракту Google для gemini-3.1-flash-image.Правильно: одна текстовая часть (инструкция) + N частей inlineData (по одной на изображение):
Неправильно (каждая часть содержит и text, и inlineData — это приводит к неопределённому поведению):
🖼️ О поле inlineData.dataЭтот эндпоинт использует формат JSON (а не загрузку файла в формате multipart), поэтому в Песочнице нельзя напрямую выбрать локальные файлы. Сначала необходимо преобразовать изображение в строку Base64, а затем вставить её в поле ввода data.Команда в одну строку: преобразование и копирование в буфер обмена:
После запуска просто Cmd+V / Ctrl+V вставьте строку в поле data в Песочнице. Также не забудьте установить для mimeType соответствующее значение image/jpeg или image/png.Рекомендация: для тестирования используйте небольшие изображения (< 200KB), чтобы избежать задержек браузера при обработке длинных строк base64. Если вы часто тестируете редактирование изображений, используйте приведённые ниже примеры кода и запускайте их локально.

Примеры кода

Python

Node.js

cURL

Редактирование нескольких изображений

При объединении или сравнении нескольких входных изображений используйте одну часть text (инструкцию), за которой следуют несколько частей inlineData (по одной на каждое изображение).

Python (несколько изображений)

cURL (несколько изображений, соответствует официальному формату Google)

Краткая справка по параметрам

Многошаговое диалоговое редактирование

Nano Banana 2 (gemini-3.1-flash-image) поддерживает полноценное диалоговое редактирование в несколько шагов: добавляйте сгенерированное на каждом шаге изображение обратно в contents как role: "model" inlineData, а затем отправляйте следующую инструкцию пользователя. Модель редактирует изображение с учётом полной истории диалога и накапливает изменения (например, сначала перекрашивает диван, затем добавляет аксессуар, сохраняя предыдущее изменение).
Это отличается от моделей обратного преобразования изображений: нативный формат Gemini действительно считывает изображения из предыдущих сообщений истории с ролью model. Для согласованности между шагами и последовательного уточнения используйте описанный ниже шаблон обратного заполнения истории.
Начните многошаговое редактирование с существующего изображения: добавьте inlineData (собственное изображение) и инструкцию в первое сообщение пользователя с просьбой отредактировать существующую фотографию, а затем на каждом шаге добавляйте вывод модели обратно в contents.
Два способа многошагового редактирования:
  • Обратное заполнение истории (рекомендуется, как показано выше): contents сохраняет чередование сообщений пользователя и модели, накапливая изменения между шагами и обеспечивая лучшую согласованность.
  • Повторная отправка (проще): на каждом шаге отправляется одно сообщение пользователя (text + inlineData предыдущего изображения) для однократного редактирования без сохранения предыдущего контекста.

Авторизации

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

API Key obtained from APIYI Console

Тело

application/json
contents
object[]
обязательно

Content array containing edit instructions and the image to edit

generationConfig
object
обязательно

Ответ

Successfully edited image

candidates
object[]

Generation results array

usageMetadata
object