> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Правка и объединение изображений через gemini-3-pro-image в LaoZhang API: до 14 референсов, передача изображения по публичному URL, нативный и OpenAI-совместимый формат и рабочий код.

Nano Banana Pro (`gemini-3-pro-image`) по текстовой инструкции меняет деталь, переводит фотографию в другой стиль или собирает из нескольких изображений новое. Каждая правка стоит одну фиксированную цену за вызов при любом размере вывода.

| Параметр | Значение |
| - | - |
| ID модели | `gemini-3-pro-image` |
| Эндпоинты | Нативный `generateContent` позволяет задать соотношение сторон и размер; OpenAI-совместимый chat completions принимает те же правки без настроек размера |
| Референсы | До 14 изображений за запрос |
| Входные изображения | `inlineData` в Base64 или публичный URL в `fileData` |
| Размер вывода | `1K` (по умолчанию), `2K` или `4K` |
| Соотношения сторон | 10, задаются через `aspectRatio` |
| Выход | Изображение в Base64 в ответе, которое нужно декодировать и сохранить |
| Маска | Нет; опишите изменяемую область словами |
| Цена | \$0.09 за вызов при любом размере (публичные цены на 24 сентября 2026 года, см. [Цены на API моделей ИИ](https://docs.laozhang.ai/ru/models.md)) |
| Оплата | Каждый ответ HTTP 200 тарифицируется как один вызов, даже без изображения; см. [правила оплаты](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md) |

Генерация изображений только по тексту описана на странице [Nano Banana Pro](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-pro-image.md).

## Подготовка

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

В разделе [Управление токенами](https://api.laozhang.ai/token) откройте диалог создания токена (创建令牌), в поле **Режим оплаты** (计费模式) выберите **«сначала по использованию»** (按量优先, рекомендуется) или **«оплата за вызов»** (按次计费) и нажмите **Создать** (创建). У Nano Banana Pro есть только цена за вызов, поэтому ключ с режимом «оплата по использованию» (按量计费) её вызвать не может; когда запрос тарифицируется, описано в [правилах оплаты](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md).

![Диалог создания токена в консоли LaoZhang API с режимом оплаты «оплата за вызов» (按次计费)](https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max\&auto=format\&n=_loZ0Jy0ZI__xJ9z\&q=85\&s=1fdceb804bb3ad50f83a21ec65b4d807)

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

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

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

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

```bash theme={null}
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`.

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

Отправьте запрос на `POST https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent`. Поставьте в `parts` сначала инструкцию, а за ней изображения. Каждый локальный файл передаётся частью `inlineData` с `mimeType`, соответствующим файлу.

> [tab] Python
>
> Сохраните скрипт как `nano_banana_pro_edit.py`. Он отправляет инструкцию с 1–14 локальными изображениями и сохраняет все изображения из ответа:
>
> ```python theme={null}
> """Редактирование и объединение изображений через 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)
> ```
>
> Добавьте шляпу коту на фотографии, вывод 2K:
>
> ```bash theme={null}
> python nano_banana_pro_edit.py "Надень на кота маленькую синюю шляпу волшебника. Позу, шерсть и фон не меняй." cat.jpg --size 2K --out pro-cat-hat
> ```

> [tab] cURL
>
> Закодируйте файл и соберите тело через `jq`, чтобы большое изображение не превысило лимиты аргументов shell. `mimeType` должен соответствовать файлу (`image/jpeg` для этого JPEG):
>
> ```bash theme={null}
> 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
> ```

Оба примера не передают `aspectRatio`, поэтому результат по умолчанию Google повторяет размер входного изображения. Чтобы изменить форму, добавьте `aspectRatio` (или `--ratio`); размеры в пикселях для каждого соотношения и размера приведены в разделе «Размеры вывода» на странице [Nano Banana Pro](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-pro-image.md). Правка в 4K занимает больше времени, чем в 1K, поэтому оставьте в клиенте большой таймаут; в примерах он равен 300 секундам.

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

Перечислите до 14 файлов после инструкции в том порядке, в котором вы на них ссылаетесь, и назовите в промпте роль каждого изображения:

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

Google делит 14 референсов по назначению. В одном запросе Nano Banana Pro принимает не больше:

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

В запросе нет поля для роли изображения, поэтому укажите в инструкции, как использовать каждое из них.

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

Нативный маршрут Gemini может принять изображение и по URL — частью `fileData` вместо Base64:

```bash theme={null}
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
```

Замените `fileUri` публичным HTTPS-адресом своего изображения и укажите соответствующий `mimeType`. Изображение скачивается по этому адресу во время запроса, поэтому оно должно открываться без входа, cookie и проверок на ботов. Если скачать его не удаётся, загрузите файл к себе и отправьте его как `inlineData`.

* **Переходите на URL, если запрос превысит 20 МБ.** Всё тело запроса должно быть меньше 20 МБ; изображения в `inlineData` в сумме должны занимать около 15 МБ или меньше, поэтому более крупные передавайте в `fileData` или сначала уменьшайте.
* `robots.txt` сайта не должен запрещать краулерам путь к изображению, а подписанный URL должен оставаться действительным не меньше 30 минут с учётом очереди и повторов.
* Части `fileData` и `inlineData` могут находиться в одном массиве `parts` в порядке референсов. Полные условия описаны в разделе «Большие изображения и URL» [обзора Nano Banana](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md).

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

Если приложение уже использует OpenAI SDK, отправляйте правки через chat completions. Поместите инструкцию и изображения в одно сообщение пользователя частями `image_url`: локальный файл — как data URL, либо публичный HTTPS-адрес.

На этом маршруте нет настроек соотношения сторон и размера; для 2K, 4K или фиксированного соотношения используйте нативный маршрут Gemini. Изображение приходит как data URL в Base64 внутри `message.content`. Сохраните скрипт как `nano_banana_pro_chat_edit.py`:

```python theme={null}
"""Редактирование и объединение изображений через 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)
```

Перенесите стиль одного изображения на другое:

```bash theme={null}
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 — текст ответа. Частые причины — блокировка проверкой безопасности или инструкция, на которую модель ответила только текстом.

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

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

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

Передавайте значения, которые принимает Pro:

| Поле | Допустимые значения | Pro не принимает |
| - | - | - |
| `aspectRatio` | Одно из 10 соотношений сторон | `1:4`, `4:1`, `1:8`, `8:1` |
| `imageSize` | `1K`, `2K` или `4K`, с заглавной K | `512` |

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

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

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

Нет. Правки Nano Banana Pro идут через нативный эндпоинт Gemini `generateContent` или OpenAI-совместимый `/v1/chat/completions`, а не через эндпоинт редактирования Images API.

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

Да, описав её словами: поля маски нет. Google называет это семантической маской — назовите элемент, который нужно изменить, и скажите, что всё остальное должно остаться прежним, например: «Замени только синий диван на коричневый кожаный. Остальную комнату, планировку и освещение не меняй». Больше приёмов — в разделе «Советы по промптам для правки».

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

По умолчанию Google повторяет размер входного изображения, поэтому без `aspectRatio` исходная форма сохраняется; так работают примеры из раздела «Правка локального изображения». Задавайте `aspectRatio`, только если нужна другая форма, а `imageSize` оставьте для выбора 1K, 2K или 4K.

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

* [Nano Banana Pro](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-pro-image.md) — генерация по тексту, размеры вывода по соотношениям сторон и привязка к поиску Google
* [Nano Banana 2](https://docs.laozhang.ai/ru/api-capabilities/nano-banana2-image.md) — более дешёвая генерация и правка до 4K
* [Обзор Nano Banana](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md) — сравнение пяти моделей, двух форматов запроса и правил оплаты
* [Редактирование Standard](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image-edit.md) — правка через `gemini-2.5-flash-image` и переход с неё
* [Журнал вызовов](https://docs.laozhang.ai/en/faq/call-logs.md) — статус и списание по запросу
* [Google: Nano Banana image generation](https://ai.google.dev/gemini-api/docs/image-generation) — промпты для правки, лимиты референсов и рассуждение
* [Google: справочник generateContent](https://ai.google.dev/api/generate-content) — поля `imageConfig`
* [Google: способы передачи файлов](https://ai.google.dev/gemini-api/docs/file-input-methods) — встроенные данные и публичные URL


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.