Nano Banana Pro API: редактирование изображений до 4K

​

Подготовка

1

Создайте API-ключ

В разделе Управление токенами откройте диалог создания токена (创建令牌), в поле Режим оплаты (计费模式) выберите «сначала по использованию» (按量优先, рекомендуется) или «оплата за вызов» (按次计费) и нажмите Создать (创建). У Nano Banana Pro есть только цена за вызов, поэтому ключ с режимом «оплата по использованию» (按量计费) её вызвать не может; когда запрос тарифицируется, описано в правилах оплаты.

2

Задайте ключ и установите зависимости

export LAOZHANG_API_KEY="sk-..."  # замените на свой API-ключ LaoZhang API
python -m pip install openai requests

3

Добавьте функцию сохранения для cURL

Для примеров с cURL нужен jq. Определите эту shell-функцию: она сохраняет последнее изображение из нативного ответа Gemini (если вместе с результатом пришли промежуточные изображения, финальное — последнее) с расширением, которое соответствует mimeType:

save_image() {
  local image='[.candidates[]?.content.parts[]? | select(.inlineData and (.thought | not))][-1].inlineData'
  local ext
  case "$(jq -r "$image.mimeType" "$1")" in
    image/png) ext=png ;;
    image/jpeg) ext=jpg ;;
    image/webp) ext=webp ;;
    *) jq '{error, promptFeedback, finishReasons: [.candidates[]?.finishReason]}' "$1"; return 1 ;;
  esac
  jq -r "$image.data" "$1" | base64 --decode > "$2.$ext" && echo "Сохранено: $2.$ext"
}

Если в ответе нет изображения, функция выводит поля error, promptFeedback и finishReason.

​

Правка локального изображения

"""Редактирование и объединение изображений через Nano Banana Pro (gemini-3-pro-image) в нативном маршруте Gemini."""
import argparse
import base64
import os
import sys
from pathlib import Path

import requests

URL = "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent"
RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
EXTENSIONS = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}

parser = argparse.ArgumentParser(description="Отредактировать одно изображение или объединить до 14 референсов.")
parser.add_argument("prompt", help="инструкция для правки")
parser.add_argument("images", nargs="+", help="от 1 до 14 локальных файлов PNG, JPEG или WebP")
parser.add_argument("--ratio", choices=RATIOS, help="соотношение сторон результата; без него — как у входного изображения")
parser.add_argument("--size", default="1K", choices=["1K", "2K", "4K"])
parser.add_argument("--out", default="pro-edit", help="имя выходного файла без расширения")
args = parser.parse_args()
if len(args.images) > 14:
    sys.exit("Передайте не больше 14 референсных изображений.")

parts = [{"text": args.prompt}]
for path in args.images:
    mime = MIME_TYPES.get(Path(path).suffix.lower())
    if mime is None:
        sys.exit(f"Нужен файл PNG, JPEG или WebP: {path}")
    data = base64.b64encode(Path(path).read_bytes()).decode("ascii")
    parts.append({"inlineData": {"mimeType": mime, "data": data}})

image_config = {"imageSize": args.size}
if args.ratio:
    image_config["aspectRatio"] = args.ratio

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "contents": [{"role": "user", "parts": parts}],
        "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": image_config},
    },
    timeout=300,
)
if response.status_code != 200:
    sys.exit(f"HTTP {response.status_code}: {response.text[:500]}")

result = response.json()
images = [
    part["inlineData"]
    for candidate in result.get("candidates") or []
    for part in (candidate.get("content") or {}).get("parts") or []
    if "inlineData" in part and not part.get("thought")
]
if not images:
    reasons = [candidate.get("finishReason") for candidate in result.get("candidates") or []]
    sys.exit(f"Изображение не получено: {result.get('promptFeedback') or reasons}")
for number, image in enumerate(images, start=1):
    suffix = "" if number == 1 else f"-{number}"
    output = Path(f"{args.out}{suffix}.{EXTENSIONS.get(image['mimeType'], 'bin')}")
    output.write_bytes(base64.b64decode(image["data"]))
    print("Сохранено:", output)

python nano_banana_pro_edit.py "Надень на кота маленькую синюю шляпу волшебника. Позу, шерсть и фон не меняй." cat.jpg --size 2K --out pro-cat-hat

base64 < cat.jpg | tr -d '\n' > cat.b64
jq -n --rawfile image cat.b64 '{
  contents: [{
    role: "user",
    parts: [
      {text: "Надень на кота маленькую синюю шляпу волшебника. Позу, шерсть и фон не меняй."},
      {inlineData: {mimeType: "image/jpeg", data: $image}}
    ]
  }],
  generationConfig: {
    responseModalities: ["IMAGE"],
    imageConfig: {imageSize: "2K"}
  }
}' > pro-edit-request.json

curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @pro-edit-request.json \
  -o pro-edit-response.json

save_image pro-edit-response.json pro-cat-hat

​

Объединение референсных изображений

python nano_banana_pro_edit.py "Одень человека с первого изображения в куртку со второго изображения и поставь его на улицу с третьего изображения. Лицо и причёску человека не меняй." person.jpg jacket.png street.jpg --ratio 3:4 --size 2K --out pro-outfit

• 6 изображений объектов, которые должны точно появиться в результате, например товары или реквизит
• 5 изображений персонажей, которые сохраняют внешность людей в серии
• 3 изображений стиля, которые задают общий вид, например палитру или манеру мазка

​

Правка изображения по публичному URL

curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Добавь тёплый вечерний свет из окна. Мебель и планировку не меняй."},
        {"fileData": {"fileUri": "https://example.com/images/living-room.png", "mimeType": "image/png"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "3:2", "imageSize": "2K"}
    }
  }' \
  -o pro-url-edit-response.json

save_image pro-url-edit-response.json pro-living-room

• Переходите на URL, если запрос превысит 20 МБ. Всё тело запроса должно быть меньше 20 МБ; изображения в inlineData в сумме должны занимать около 15 МБ или меньше, поэтому более крупные передавайте в fileData или сначала уменьшайте.
• robots.txt сайта не должен запрещать краулерам путь к изображению, а подписанный URL должен оставаться действительным не меньше 30 минут с учётом очереди и повторов.
• Части fileData и inlineData могут находиться в одном массиве parts в порядке референсов. Полные условия описаны в разделе «Большие изображения и URL» обзора Nano Banana.

​

OpenAI-совместимый маршрут

"""Редактирование и объединение изображений через Nano Banana Pro по OpenAI-совместимому маршруту."""
import argparse
import base64
import os
import re
import sys
from pathlib import Path

from openai import OpenAI

MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
EXTENSIONS = {"png": "png", "jpeg": "jpg", "jpg": "jpg", "webp": "webp"}

parser = argparse.ArgumentParser(description="Отредактировать одно изображение или объединить несколько через chat completions.")
parser.add_argument("prompt", help="инструкция для правки")
parser.add_argument("images", nargs="+", help="локальные файлы PNG, JPEG или WebP либо публичные HTTPS-адреса")
parser.add_argument("--out", default="pro-chat-edit", help="имя выходного файла без расширения")
args = parser.parse_args()

content = [{"type": "text", "text": args.prompt}]
for source in args.images:
    if source.startswith("https://"):
        url = source  # публичный URL изображения отправляется как есть
    else:
        mime = MIME_TYPES.get(Path(source).suffix.lower())
        if mime is None:
            sys.exit(f"Нужен файл PNG, JPEG или WebP: {source}")
        url = f"data:{mime};base64," + base64.b64encode(Path(source).read_bytes()).decode("ascii")
    content.append({"type": "image_url", "image_url": {"url": url}})

# max_retries=0: автоповтор после таймаута мог бы сгенерировать и оплатить изображение дважды
client = OpenAI(api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api.laozhang.ai/v1", timeout=300, max_retries=0)
reply = client.chat.completions.create(
    model="gemini-3-pro-image",
    messages=[{"role": "user", "content": content}],
)
text = reply.choices[0].message.content or ""

found = re.findall(r"data:image/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)", text)
if not found:
    sys.exit(f"Изображение не получено: {text[:300]}")
for number, (kind, encoded) in enumerate(found, start=1):
    suffix = "" if number == 1 else f"-{number}"
    output = Path(f"{args.out}{suffix}.{EXTENSIONS[kind]}")
    output.write_bytes(base64.b64decode(encoded + "=" * (-len(encoded) % 4)))
    print("Сохранено:", output)

python nano_banana_pro_chat_edit.py "Перенеси палитру и манеру мазка первого изображения на сцену второго изображения." style.jpg photo.jpg --out pro-chat-restyle

​

Обработка ответа

• Нативный формат Gemini: каждое изображение — это часть inlineData в candidates[].content.parts[] с mimeType и данными data в Base64.
  • Пропускайте части с пометкой thought: true. Pro рассуждает перед отрисовкой, и при сложной правке вместе с результатом могут прийти промежуточные изображения; финальное — последнее.
  • Сохраняйте файл с расширением, соответствующим mimeType.
• Chat completions: изображение — это data URL вида data:image/png;base64,... внутри текста choices[0].message.content. Возьмите формат из префикса, уберите префикс и, если длина не кратна 4, добавьте выравнивание = перед декодированием.
• Нет изображения: в нативных ответах проверьте finishReason каждого кандидата и promptFeedback, если он есть, а в ответах chat — текст ответа. Частые причины — блокировка проверкой безопасности или инструкция, на которую модель ответила только текстом.

​

Советы по промптам для правки

• Укажите, что должно остаться прежним: лицо, этикетка товара или компоновка. Параметра маски нет, поэтому изменяемую область описывайте словами.
• Ссылайтесь на каждое изображение по порядку и роли, например «куртка со второго изображения».
• Чтобы сохранить лицо или логотип, подробно опишите его и прямо скажите, что его нельзя менять.
• Для текста на изображении возьмите точные слова в кавычки и назовите стиль шрифта.
• Разбивайте сложную правку на шаги и отправляйте каждый сохранённый результат на вход следующего запроса.

​

Ошибки и оплата

• Запрос может вернуть HTTP 200 без изображения, например если проверка безопасности блокирует результат. Правки тарифицируются так же, как генерация, поэтому вызов оплачивается. Проверьте finishReason (и promptFeedback, если он есть), затем измените инструкцию или референсы, прежде чем отправлять снова; см. раздел «Как не платить за пустые ответы» в обзоре Nano Banana.
• HTTP 401 означает неверный ключ или заголовок Authorization: Bearer; нативный маршрут Gemini принимает ключ и в x-goog-api-key. Ответы 429 и 5xx повторяйте с нарастающей задержкой, а перед повторной отправкой запроса с таймаутом сверьтесь с журналом вызовов.
• Если URL в fileData не скачивается, проверьте, что он открывается без входа и что robots.txt его разрешает, или отправьте изображение как inlineData.
• HTTP 413 означает слишком большое тело запроса. Передавайте большие изображения по URL или уменьшайте их, чтобы весь запрос был меньше 20 МБ.
• Base64 увеличивает файл примерно на треть, поэтому очень крупные фотографии уменьшайте перед кодированием.

​

Частые вопросы

​

Можно ли редактировать через /v1/images/edits?

​

Можно ли изменить только часть изображения?

​

Какой формы будет результат без aspectRatio?

​

Связанные материалы и источники

• Nano Banana Pro — генерация по тексту, размеры вывода по соотношениям сторон и привязка к поиску Google
• Nano Banana 2 — более дешёвая генерация и правка до 4K
• Обзор Nano Banana — сравнение пяти моделей, двух форматов запроса и правил оплаты
• Редактирование Standard — правка через gemini-2.5-flash-image и переход с неё
• Журнал вызовов — статус и списание по запросу
• Google: Nano Banana image generation — промпты для правки, лимиты референсов и рассуждение
• Google: справочник generateContent — поля imageConfig
• Google: способы передачи файлов — встроенные данные и публичные URL