В эпоху генеративного искусственного интеллекта граница между созданием нового контента и редактированием существующего становится всё более размытой. Однако для разработчиков и инженеров, работающих с AI-интеграциями, критически важно понимать разницу между генерацией «с нуля» и точечным редактированием. В этой статье мы подробно разберем, как использовать API OpenRouter для выполнения задач по редактированию изображений с помощью мощных моделей Google Gemini, известных в сообществе под прозвищем «Nano Banana». Это не просто краткая инструкция, а глубокое погружение в технические детали, архитектуру запросов и стратегии оптимизации, которые позволят вам эффективно внедрить AI-редактуру в свои проекты.
Термин «Nano Banana» — это неофициальное, но широко принятое в индустрии название для семейства моделей изображений Google Gemini. В данном руководстве мы фокусируемся на модели google/gemini-3.1-flash-image, которая является текущим стандартом скорости и качества в этой линейке. Преимущество использования OpenRouter заключается в унификации: вы отправляете запрос через единый интерфейс, но можете легко переключаться между различными моделями (от самых быстрых до самых качественных), изменяя всего одну строку в коде. Это дает гибкость, необходимую для балансировки между стоимостью, скоростью обработки и визуальным результатом.
Важно сразу провести четкую границу: редактирование изображения (image editing) подразумевает наличие исходного файла, который мы модифицируем согласно текстовой инструкции. Генерация изображения (image generation), напротив, создает новый пиксельный массив исключительно на основе текстового описания. Данное руководство посвящено исключительно редактированию, поэтому каждый пример запроса будет включать ссылку на исходное изображение. Если же ваша задача — создать изображение с нуля, вам следует обратиться к соответствующей документации по генерации.
01Подготовка к работе: необходимые компоненты
Для начала работы с API редактирования изображений через OpenRouter вам потребуется подготовить три ключевых компонента. Это базовая инфраструктура, без которой взаимодействие с моделью невозможно.
Во-первых, необходим API-ключ. Его можно получить на странице управления ключами в личном кабинете OpenRouter. Этот ключ будет использоваться для аутентификации каждого запроса. Во-вторых, вам нужен HTTP-клиент. В примерах ниже мы будем использовать библиотеку requests для Python и нативный fetch для TypeScript, так как они наиболее распространены. Однако подойдет любой клиент, способный отправлять POST-запросы с заголовком Authorization и телом в формате JSON. Также можно использовать утилиту curl или официальный SDK OpenRouter.
В-третьих, требуется исходное изображение. Оно может быть локальным файлом на вашем компьютере или публичным URL-адресом, размещенным на сервере. Форматы, поддерживаемые моделями Gemini, включают image/png, image/jpeg, image/webp, а также image/heic и image/heif (форматы Apple). Однако поддержка конкретных форматов может варьироваться в зависимости от выбранной модели, поэтому всегда рекомендуется проверять страницу конкретной модели перед отправкой сложных файлов.
export OPENROUTER_API_KEY="sk-or-...", а в Windows — через настройки системы или файл .env. Это предотвратит случайную утечку ключей при публикации кода в репозитории.02Выбор модели: что такое «Nano Banana»?
Семейство моделей Google для работы с изображениями, часто называемое «Nano Banana», включает несколько версий, каждая из которых оптимизирована под разные задачи. Понимание их различий поможет вам выбрать оптимальный инструмент для вашего проекта.
Основной моделью в этом руководстве является google/gemini-3.1-flash-image (Nano Banana 2). Это универсальный вариант, предлагающий отличный баланс между скоростью обработки и качеством результата. Он является дефолтным выбором для большинства задач редактирования. Если вам критически важна минимальная задержка и самая низкая стоимость, стоит обратить внимание на google/gemini-3.1-flash-lite-image (Nano Banana 2 Lite). Это самая быстрая и дешевая модель, хотя качество может быть немного ниже.
Для задач, требующих высокой детализации и художественной точности, существует google/gemini-3-pro-image (Nano Banana Pro). Эта модель работает медленнее и стоит дороже, но предоставляет более высокое качество рендеринга. Также доступна оригинальная модель google/gemini-2.5-flash-image, с которой началось распространение прозвища «Nano Banana». Хотя она все еще работает, новые версии предлагают улучшенные возможности и эффективность.
Каталог моделей постоянно меняется: появляются новые версии, старые устаревают, а цены корректируются. Поэтому, прежде чем строить серьезный продукт на базе конкретной модели, убедитесь, что она поддерживает ввод изображений и необходимые вам функции редактирования. Актуальный список моделей, поддерживающих редактирование, можно найти в коллекции моделей изображений на сайте OpenRouter.
03Ваш первый запрос на редактирование
Процесс редактирования через API интуитивно прост: вы отправляете исходное изображение и текстовую инструкцию в одном запросе, а в ответ получаете отредактированное изображение. Давайте разберем рабочий пример на Python, который кодирует локальный файл и отправляет его в API.
import base64, os, requests
api_key = os.environ["OPENROUTER_API_KEY"]
# Кодируем локальное исходное изображение в формат base64 data URL.
with open("portrait.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode()
source = f"data:image/jpeg;base64,{encoded}"
resp = requests.post(
"https://openrouter.ai/api/v1/images",
headers={
"Authorization": f"Bearer {api_key}",
},
json={
"model": "google/gemini-3.1-flash-image",
"prompt": "Add a red wool scarf around the person's neck. Keep everything else the same.",
"input_references": [
{
"type": "image_url",
"image_url": { "url": source }
}
],
},
)
resp.raise_for_status()Аналогичный запрос на TypeScript выглядит следующим образом:
import { readFileSync } from "node:fs";
const apiKey = process.env.OPENROUTER_API_KEY;
const encoded = readFileSync("portrait.jpg").toString("base64");
const source = `data:image/jpeg;base64,${encoded}`;
const resp = await fetch("https://openrouter.ai/api/v1/images", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "google/gemini-3.1-flash-image",
prompt: "Add a red wool scarf around the person's neck. Keep everything else the same.",
input_references: [{ type: "image_url", image_url: { url: source } }],
}),
});Обратите внимание на структуру тела запроса. Ключевым полем является input_references, куда помещается ссылка на исходное изображение. Инструкция по редактированию передается в поле prompt. Это и есть весь необходимый запрос. Тело запроса идентично для обоих языков программирования, что упрощает портирование кода.
04Форматирование входных данных: URL или Base64?
Поле input_references принимает либо data URL в формате base64, либо обычный HTTP(S) URL. Выбор зависит от того, где хранится ваше изображение.
Если изображение находится в открытом доступе и доступно по ссылке, лучше всего передать этот URL напрямую. Это значительно уменьшает размер тела запроса, так как не нужно кодировать весь файл в строку base64. Пример использования URL:
"input_references": [
{
"type": "image_url",
"image_url": { "url": "https://example.com/portrait.jpg" }
}
]С другой стороны, если вы работаете с локальными файлами или приватными изображениями, которые не имеют публичного доступа, необходимо закодировать файл в base64. Это обеспечивает безопасность и позволяет обрабатывать файлы, которые не могут быть загружены по прямой ссылке. Gemini поддерживает ввод в форматах image/png, image/jpeg, image/webp, image/heic и image/heif. Однако, как упоминалось ранее, поддержка может варьироваться, поэтому всегда проверяйте спецификации модели.
05Получение и сохранение результата
После успешного выполнения запроса API возвращает отредактированное изображение в виде base64-строки внутри массива data. Вам нужно извлечь значение поля b64_json и декодировать его обратно в бинарный формат для сохранения на диск.
На Python это делается так:
data = resp.json()["data"][0]
with open("edited.png", "wb") as out:
out.write(base64.b64decode(data["b64_json"]))На TypeScript код будет выглядеть следующим образом:
const data = await resp.json();
writeFileSync("edited.png", Buffer.from(data[0].b64_json, "base64"));Откройте файл edited.png, чтобы увидеть результат. Если вы предпочитаете использовать типизированный клиент вместо сырых HTTP-запросов, вы можете использовать официальный SDK OpenRouter. Он предоставляет удобный метод client.images.generate(), который скрывает детали низкоуровневого взаимодействия, но использует тот же самый endpoint.
06Написание эффективных промптов для редактирования
Качество результата напрямую зависит от того, как вы формулируете инструкцию. В отличие от промптов для генерации, где вы описываете целое изображение с нуля, промпт для редактирования должен четко указывать, что нужно изменить, а что оставить без изменений. Лучшая практика — сначала описать изменение, а затем перечислить элементы, которые должны остаться неизменными.
Рассмотрим несколько типовых сценариев:
- Замена объекта: «Замените кофейную чашку на стакан апельсинового сока. Сохраните положение руки и фон без изменений.»
- Изменение фона: «Измените фон на заснеженную улицу ночью. Сохраните объект (персонажа) в точности таким, какой он есть.»
- Стилистический перенос: «Отрисуйте эту фотографию в стиле акварельной живописи. Сохраните композицию и позу субъекта.»
- Исправление текста: «Измените текст на вывеске на „OPEN“. Совместите оригинальный шрифт и цвет.»
Для более сложных задач можно использовать структуру JSON внутри текстового промпта. Хотя API воспринимает это как обычный текст, такая структура помогает модели лучше разделить инструкции по изменению и сохранению элементов. Пример:
"prompt": "{\"edit\": \"add sunglasses\", \"preserve\": [\"face\", \"hair\", \"lighting\"], \"style\": \"photorealistic\"}"Рекомендуется тестировать оба формата (предложение и JSON) на ваших собственных изображениях и выбирать тот, который дает более стабильный результат в вашем конкретном кейсе.
07Итеративное редактирование: пошаговый подход
Одного запроса часто недостаточно для достижения идеального результата. ИИ может интерпретировать инструкцию не так, как вы ожидали, или внести нежелательные артефакты. В таких случаях полезно использовать итеративный подход: отправлять результат предыдущего запроса обратно в API в качестве исходного изображения для следующего шага.
Это позволяет накапливать изменения постепенно. Например, сначала вы добавляете шарф, затем меняете его цвет, а затем корректируете освещение. Каждый шаг должен содержать только одну инструкцию. Это упрощает отладку: если результат на третьем шаге неудовлетворителен, вы можете откатиться ко второму шагу и попробовать другую инструкцию, не теряя проделанную работу.
Важно помнить, что модель не «помнит» ваши предыдущие промпты. Она видит только текущее изображение и текущую инструкцию. Поэтому в каждом новом промпте необходимо повторять, какие элементы должны остаться неизменными. Если вы хотите, чтобы фон остался прежним, явно укажите это в промпте, даже если он уже был таким в предыдущем шаге.
08Смена модели редактирования
Одним из главных преимуществ использования OpenRouter является возможность легко переключаться между моделями. Чтобы отправить тот же самый запрос на редактирование другой модели, вам нужно изменить только значение поля model. Остальная часть запроса, включая исходное изображение, промпт и код обработки ответа, остается неизменной.
Например, чтобы использовать модель от OpenAI (если она поддерживает редактирование), вы просто меняете строку:
"model": "openai/gpt-5-image" // было google/gemini-3.1-flash-imageИспользуйте google/gemini-3.1-flash-image как стандартный выбор для скорости. Используйте google/gemini-3.1-flash-lite-image для минимизации затрат. Используйте google/gemini-3-pro-image, когда качество важнее скорости. Если вы хотите сравнить качество, стоимость или скорость разных провайдеров, просто меняйте slug модели. Однако помните, что эта техника работает только для моделей, которые принимают ввод изображений и поддерживают ту же структуру input_references. Всегда проверяйте, что выбранная модель способна на редактирование.
Для более продвинутого управления конфигурацией вы можете использовать Presets в OpenRouter. Это позволяет задать модель и её параметры для разных сред (разработка, продакшн) без изменения кода.
09Ошибки и стоимость
При работе с API важно планировать возможные сбои. Вот типичные ошибки:
- Неподдерживаемый формат: Модель может отклонить изображение, если формат файла не поддерживается, или URL, к которому нет доступа. Проверяйте тип файла и доступность ссылки перед отправкой.
- Слишком большие изображения: Большие файлы могут вызывать таймауты или ошибки. Сжимайте изображения перед отправкой. Для большинства задач редактирования не требуется исходное разрешение в 40 мегапикселей.
- Текст вместо изображения: Если вы зададите вопрос вроде «Что изображено на этом фото?», модель может ответить текстом, а не сгенерировать изображение. В этом случае API вернет ошибку 400 с сообщением вроде «Gemini could not generate an image (STOP)». Всегда формулируйте инструкции как приказы, а не вопросы, и проверяйте HTTP-статус ответа перед декодированием.
API сообщает стоимость каждого запроса в долларах США в поле usage. Рекомендуется логировать эту информацию для контроля расходов. Для пакетных заданий соблюдайте лимиты скорости (rate limits). Используйте экспоненциальную задержку при повторных попытках (retry) в случае ошибок 429 или 5xx. Сохраняйте каждый полученный результат на диск перед началом следующего шага редактирования, чтобы избежать потери данных при сбое сети.
10Что это значит на практике
Интеграция AI-редактирования изображений через API OpenRouter открывает широкие возможности для автоматизации визуального контента. От автоматической замены фона в каталогах товаров до стилизации пользовательских фотографий — эти технологии позволяют создавать сложные пайплайны обработки медиа. Ключ к успеху лежит в понимании того, что редактирование — это итеративный процесс. Не ждите идеального результата с первого раза. Разбивайте сложные задачи на маленькие, четкие шаги, используйте правильные промпты для фиксации неизменных элементов и выбирайте модель, которая лучше всего подходит под ваши требования к скорости и качеству. Благодаря унифицированному интерфейсу OpenRouter, вы можете экспериментировать с разными моделями, не переписывая основную логику приложения, что значительно ускоряет разработку и оптимизацию затрат.
11Часто задаваемые вопросы
Могу ли я редактировать изображения с помощью API Gemini?
Да. Отправьте исходное изображение и текстовую инструкцию в одном запросе на google/gemini-3.1-flash-image через API OpenRouter. Модель вернет отредактированное изображение в формате base64. Полный запрос помещается на один экран экрана, и его можно запустить в Python, TypeScript или curl.
В чем разница между генерацией и редактированием изображений?
Редактирование изменяет существующее изображение. Генерация создает новое изображение из текста. Каждый запрос на редактирование включает исходное изображение в input_references и инструкцию, указывающую, что изменить и что сохранить. Если в запросе нет исходного изображения и работает только текстовый промпт, это генерация.
Как отправить изображение в API: URL или base64?
Поле input_references принимает data URL в формате base64 для локальных или приватных файлов, или обычный HTTP(S) URL для публичных изображений. Используйте URL, чтобы уменьшить размер запроса, если изображение уже доступно в сети. Используйте base64, если файл находится на вашем компьютере. Gemini поддерживает png, jpeg, webp, heic и heif (image/png, image/jpeg, image/webp, image/heic, image/heif). Поддержка форматов варьируется, поэтому проверяйте страницу модели перед отправкой.
Могу ли использовать модель не от Gemini для редактирования?
Да. Измените поле model и оставьте остальную часть запроса без изменений. Сначала проверьте коллекцию моделей изображений, так как поддержка редактирования, цена и скорость варьируются в зависимости от модели.
Как составить промпт для AI-модели, чтобы она отредактировала изображение?
Опишите изменение первым, затем перечислите, что нужно сохранить. Например: «Измените фон на заснеженную улицу ночью. Сохраните объект в точности таким, какой он есть». Лучше всего работает одна инструкция на запрос. Для точных результатов редактируйте небольшими шагами и отправляйте каждый полученный результат обратно в качестве источника для следующего промпта.
12Ссылки
- Ключи API OpenRouter: Создание и управление ключом, используемым в каждом запросе.
- Коллекция моделей изображений: Полный набор моделей, поддерживающих редактирование, и их возможности ввода.
- Документация по генерации изображений: Сопутствующее руководство по созданию изображений из текста.
- Руководство по Presets: Закрепление модели и её параметров для среды вместо установки их в коде.
Источник: OpenRouter ↗