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

Примеры кода

Python

Node.js

cURL

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

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

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

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

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

Многоходовое разговорное редактирование

Nano Banana 2 (gemini-3.1-flash-image-preview) поддерживает настоящее разговорное многоходовое редактирование: добавляйте изображение, сгенерированное на каждом ходе, обратно в contents как role: "model" inlineData, затем отправляйте следующую инструкцию пользователя. Модель редактирует на основе полной истории разговора и накапливает изменения (например, сначала перекрасьте диван, затем добавьте аксессуар — предыдущее изменение сохраняется).
Это отличается от reverse image models: нативный формат Gemini действительно считывает изображения из ходов истории с ролью model. Для согласованности между ходами и пошаговой доработки используйте приведенный ниже шаблон backfill по истории.
Начните многоходовое редактирование с существующего изображения: поместите inlineData (ваше собственное изображение) и инструкцию в первое сообщение пользователя, чтобы отредактировать существующую фотографию, затем продолжайте backfill вывода модели в contents на каждом ходе.
Два стиля многоходовой работы:
  • Backfill по истории (выше, рекомендуется): contents сохраняет чередующуюся историю user/model — накапливает изменения между ходами с лучшей согласованностью.
  • Повторная подача (проще): каждый ход отправляет одно сообщение пользователя (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