Nano Banana в Claude Code: подключение через скилл или MCP

Claude сам растровые изображения не рисует: он пишет код и SVG, а картинку создаёт Nano Banana, то есть модели Gemini. Задача Claude Code в этой связке — вызвать модель, передать промпт и референсы и положить готовый файл в нужную папку проекта. Подключить её можно двумя способами: скилл (skill) — папка с SKILL.md и скриптом, который Claude запускает сам, или MCP-сервер — отдельный процесс, чьи инструменты Claude вызывает напрямую. Для одиночного разработчика проще скилл: один файл на Python и одна переменная с ключом. MCP удобнее, если сервер уже установлен для Gemini CLI или нужны готовые команды вроде иконок и диаграмм.

По состоянию на 24 сентября 2026 года в Gemini API работают три идентификатора: gemini-3.1-flash-image (Nano Banana 2), gemini-3-pro-image (Nano Banana Pro) и gemini-3.1-flash-lite-image (Nano Banana 2 Lite). Версии gemini-3.1-flash-image-preview и gemini-3-pro-image-preview отключены 25 июня 2026 года, а gemini-2.5-flash-image отключается 2 октября 2026 года (график Google). Поэтому связка, настроенная весной по видео, сегодня чаще всего ломается не из-за Claude, а из-за ID модели в настройках. Одна картинка Nano Banana 2 в 1K стоит около $0,067, бесплатного уровня у моделей изображений в API нет — нужен ключ с включённым биллингом.

Скилл или MCP: что подойдёт вам

Оба варианта дают одинаковый результат: файл изображения появляется в проекте после обычной просьбы в чате Claude Code. Разница в том, кто и как обращается к Gemini.

Если выбирать с нуля, начинайте со скилла: его код короткий, его легко прочитать целиком и закоммитить в .claude/skills/, а устаревший ID он просто не пропустит. MCP-сервер Google функциональнее, но его значение по умолчанию сейчас указывает на отключённую модель, и без одной переменной он работать не будет (подробнее ниже).

Ни один из вариантов не работает в обычном чате claude.ai: там у Claude нет доступа к вашей файловой системе и переменным окружения, и визуальная часть ограничена SVG, диаграммами и кодом (об этом — в статье «Может ли Claude генерировать изображения?»). Про Cowork и облачные сессии — в отдельном разделе ниже.

Какие ID моделей Nano Banana работают сейчас

Данные из документации Gemini API и страницы отключений, по состоянию на 24 сентября 2026 года:

На всех сгенерированных изображениях стоит невидимый водяной знак SynthID. Даты относятся только к Gemini API с ключом из AI Studio: в Vertex AI график другой (preview-версии там отключены 17 июля 2026 года, gemini-2.5-flash-image работает до 15 марта 2027 года), он разобран в статье «Nano Banana API в Vertex AI: рабочие модели, настройка и цена». Как выбрать между Lite, 2 и Pro под конкретную задачу, подробно описано в материале «Nano Banana 2 Lite, 2 или Pro: выбор по задаче».

Почему связка из весеннего видео перестала работать

До 28 мая 2026 года Nano Banana 2 и Pro существовали только в preview-версиях, поэтому настройки, собранные в феврале–апреле, указывают именно на них. Ниже — какую модель вызывают без правок распространённые варианты и что в них поменять.

Вывод про расширение nanobanana следует из его исходного кода, а не из опубликованного сообщения об ошибке: в imageGenerator.ts модель берётся как process.env.NANOBANANA_MODEL || DEFAULT_MODEL, где DEFAULT_MODEL = 'gemini-3.1-flash-image-preview', а последний коммит в ветке main датирован 7 марта 2026 года. Значит, без переменной запрос уходит к модели, отключённой 25 июня, и генерация должна завершаться ошибкой. Проверки допустимых значений у переменной нет: сервер примет и опечатку, и отключённый ID, а ошибку вернёт уже Google.

Чтобы найти, где в вашей системе ещё прописан старый ID, достаточно одного поиска:

grep -rn "image-preview\|2.5-flash-image" \
  ~/.claude.json ~/.claude/skills .claude .mcp.json \
  ~/.gemini ~/.zshrc ~/.bashrc 2>/dev/null

Каждое найденное место замените на GA-идентификатор из таблицы выше, затем перезапустите Claude Code (или Gemini CLI), чтобы процесс подхватил новые переменные. Если модель правильная, запрос проходит, а картинки всё равно нет, причина уже в ответе API: о блокировках, finishReason и пустых ответах — в статье «Nano Banana не генерирует изображение в API: как найти причину».

Вариант 1: свой скилл со скриптом

Скилл в Claude Code — это папка с файлом SKILL.md: в YAML-шапке описано, когда его применять, ниже — инструкции, рядом могут лежать скрипты. Имя папки становится командой: скилл в nano-banana/ можно вызвать как /nano-banana, но Claude подключит его и сам, если просьба совпадает с описанием. Где хранить папку, решает, где скилл будет доступен:

• .claude/skills/nano-banana/ в корне проекта — только в этом репозитории; после коммита скилл получит вся команда, и его подхватят облачные сессии;
• ~/.claude/skills/nano-banana/ — во всех ваших проектах на этой машине, но не в Cowork и не в облачных сессиях.

Общая логика установки скиллов и примеры других полезных вариантов собраны в подборке «Лучшие skills для Claude Code, которые стоит ставить первыми в 2026 году».

Шаг 1. Ключ и библиотека

Ключ создаётся в Google AI Studio, и у его проекта должен быть включён биллинг (почему — в разделе о цене). Затем в терминале:

pip install "google-genai>=2.25.0"
export GEMINI_API_KEY="ваш-ключ"   # или добавьте эту строку в ~/.zshrc
claude

Переменную нужно задать до запуска claude: скрипт унаследует её от Claude Code. Не вставляйте ключ в чат и не просите Claude записать его в файл проекта — всё, что вы отправили в сессию, остаётся в её истории. Если ключ уже побывал в переписке, отзовите его в AI Studio и создайте новый.

Шаг 2. Файл SKILL.md

Структура папки:

.claude/skills/nano-banana/
├── SKILL.md
└── scripts/
    └── generate.py

.claude/skills/nano-banana/SKILL.md:

---
name: nano-banana
description: Создаёт и редактирует растровые изображения (обложки статей, превью, иконки, иллюстрации для лендингов) через Nano Banana в Gemini API и сохраняет файл в проект. Используй, когда просят сгенерировать, нарисовать или изменить картинку.
---

# Nano Banana

1. Если путь к файлу не назван, сохраняй в `images/` в корне проекта и сообщи путь.
2. Запускай:
   `python .claude/skills/nano-banana/scripts/generate.py "<промпт>" --out <путь.png> [--aspect 16:9] [--size 2K] [--model <ID>] [--input <референс>]`
3. Модели:
   - `gemini-3.1-flash-image` — по умолчанию;
   - `gemini-3-pro-image` — сложная композиция, текст на изображении, 4K;
   - `gemini-3.1-flash-lite-image` — черновики, только `--size 1K`, без нескольких референсов и пошаговой правки.
4. Чтобы изменить существующую картинку, передай её через `--input` и опиши только то, что нужно поменять.
5. Код выхода 2 — ошибка настройки (нет ключа или неверный ID модели): покажи пользователю текст ошибки и не пытайся подставить ключ сам. Код 1 — изображение не вернулось: покажи blockReason и finishReason.
6. Никогда не проси прислать API-ключ в чат.

Если скилл лежит в ~/.claude/skills/, поменяйте путь к скрипту в пункте 2 на ~/.claude/skills/nano-banana/scripts/generate.py.

Шаг 3. Скрипт generate.py

.claude/skills/nano-banana/scripts/generate.py:

#!/usr/bin/env python3
"""Создаёт или редактирует одно изображение через Nano Banana (Gemini API).

Пример:
  python generate.py "промпт" --out images/hero.png [--model gemini-3.1-flash-image]
                     [--aspect 16:9] [--size 2K] [--input ref.png ...]
Ключ берётся из GEMINI_API_KEY, а не из командной строки.
"""
import argparse
import os
import pathlib
import sys

from google import genai
from google.genai import types

MODELS = {
    "gemini-3.1-flash-lite-image",  # Nano Banana 2 Lite, только 1K
    "gemini-3.1-flash-image",       # Nano Banana 2: 512 / 1K / 2K / 4K
    "gemini-3-pro-image",           # Nano Banana Pro: 1K / 2K / 4K
}

def main() -> int:
    p = argparse.ArgumentParser()
    p.add_argument("prompt")
    p.add_argument("--out", required=True)
    p.add_argument("--model", default="gemini-3.1-flash-image")
    p.add_argument("--aspect", default="1:1")
    p.add_argument("--size", default="1K")
    p.add_argument("--input", action="append", default=[])
    a = p.parse_args()

    if a.model not in MODELS:
        print(f"Unknown or retired model id: {a.model}. Use one of {sorted(MODELS)}", file=sys.stderr)
        return 2
    if not os.environ.get("GEMINI_API_KEY"):
        print("GEMINI_API_KEY is not set", file=sys.stderr)
        return 2

    contents = [a.prompt]
    for path in a.input:
        data = pathlib.Path(path).read_bytes()
        mime = "image/png" if path.lower().endswith(".png") else "image/jpeg"
        contents.append(types.Part.from_bytes(data=data, mime_type=mime))

    # Необязательно: Gemini-совместимый шлюз, например GEMINI_BASE_URL=https://api.laozhang.ai
    base_url = os.environ.get("GEMINI_BASE_URL")
    client = genai.Client(http_options=types.HttpOptions(base_url=base_url)) if base_url else genai.Client()
    resp = client.models.generate_content(
        model=a.model,
        contents=contents,
        config=types.GenerateContentConfig(
            response_modalities=["IMAGE"],
            image_config=types.ImageConfig(aspect_ratio=a.aspect, image_size=a.size),
        ),
    )

    for cand in resp.candidates or []:
        for part in (cand.content.parts if cand.content else []) or []:
            if part.inline_data and part.inline_data.data:
                out = pathlib.Path(a.out)
                out.parent.mkdir(parents=True, exist_ok=True)
                out.write_bytes(part.inline_data.data)
                print(f"saved {out} ({len(part.inline_data.data)} bytes)")
                return 0

    fb = getattr(resp, "prompt_feedback", None)
    reason = resp.candidates[0].finish_reason if resp.candidates else None
    print(f"No image returned. blockReason={getattr(fb, 'block_reason', None)} finishReason={reason}", file=sys.stderr)
    return 1

if __name__ == "__main__":
    sys.exit(main())

Скрипт использует generate_content с response_modalities=["IMAGE"], чтобы модель вернула только изображение, и ImageConfig для соотношения сторон и размера. В документации Google теперь первым показан Interactions API (client.interactions.create), но generateContent по-прежнему поддерживается, и именно этот формат принимают Gemini-совместимые шлюзы. Сообщения об ошибках оставлены на английском: Claude их прочитает без перевода, а вам будет проще искать их текст.

Как ведёт себя скрипт, известно из офлайн-проверки на google-genai 2.25.0 и Python 3.12: без ключа он завершается с кодом 2 и сообщением GEMINI_API_KEY is not set; с gemini-3-pro-image-preview отказывает ещё до запроса и перечисляет три рабочих ID; с фиктивным ключом и GA-моделью запрос доходит до generativelanguage.googleapis.com и возвращается 400 INVALID_ARGUMENT с причиной API_KEY_INVALID. Настоящее изображение в этой проверке не создавалось, поэтому о скорости и качестве генерации она ничего не говорит.

Шаг 4. Как просить Claude

Достаточно описать задачу обычными словами:

Сделай обложку 16:9 в 2K для статьи о миграции на PostgreSQL 18: слон из синих кубов на тёмном фоне, без текста. Сохрани в public/images/pg18-cover.png.

Claude найдёт скилл по описанию, запустит примерно такую команду (при первом запуске Claude Code, как обычно, спросит разрешение на выполнение):

python .claude/skills/nano-banana/scripts/generate.py \
  "Isometric elephant made of blue cubes on a dark background, no text" \
  --out public/images/pg18-cover.png --aspect 16:9 --size 2K

Для правки по референсу передайте исходник: «Возьми public/images/pg18-cover.png и замени фон на светло-серый» — Claude добавит --input public/images/pg18-cover.png. Nano Banana 2 принимает до 14 референсов в одном запросе, Lite на несколько референсов не рассчитана. Как формулировать сам промпт, чтобы результат был предсказуемым, разобрано в руководстве «Как писать промпты для Nano Banana».

Вариант 2: MCP-сервер nanobanana от Google

Расширение gemini-cli-extensions/nanobanana написано для Gemini CLI, но внутри это обычный MCP-сервер на @modelcontextprotocol/sdk, который общается через stdio. Поэтому Claude Code может запустить его напрямую, без Gemini CLI. Нужен Node.js 20 или новее: в package.json указан минимум 18, но README расширения требует 20+, и безопаснее ориентироваться на него.

git clone https://github.com/gemini-cli-extensions/nanobanana ~/tools/nanobanana
cd ~/tools/nanobanana
npm install

Собранного сервера в репозитории нет: папка mcp-server/dist/ не закоммичена, поэтому после клонирования без сборки запускать нечего. npm install в корне репозитория ставит зависимости и сразу собирает сервер (это делает скрипт postinstall), после чего он появляется в mcp-server/dist/index.js. Подключите его к Claude Code, обязательно указав модель:

claude mcp add --env NANOBANANA_API_KEY="ваш-ключ" \
  --env NANOBANANA_MODEL=gemini-3.1-flash-image \
  --transport stdio nanobanana \
  -- node ~/tools/nanobanana/mcp-server/dist/index.js

Порядок аргументов важен. Всё после -- передаётся серверу без изменений. Сразу после --env не может стоять имя сервера — CLI примет его за ещё одну пару KEY=value, поэтому между ними стоит --transport stdio. Проверка: claude mcp list должен показать у nanobanana статус ✔ Connected, внутри сессии то же видно в /mcp.

Без --scope сервер записывается в локальную область: он доступен только в текущем проекте, а конфигурация вместе с ключом хранится в ~/.claude.json в домашнем каталоге. --scope user делает сервер доступным во всех ваших проектах и хранит его там же. С --scope project Claude Code пишет .mcp.json в корень репозитория, который обычно коммитят, поэтому ключ туда вписывать нельзя. Для общей настройки команды используйте подстановку из переменной окружения:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["${NANOBANANA_DIR}/mcp-server/dist/index.js"],
      "env": {
        "NANOBANANA_API_KEY": "${GEMINI_API_KEY}",
        "NANOBANANA_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

Если переменная не задана, Claude Code всё равно загрузит сервер, но покажет предупреждение с её именем в claude mcp list и /mcp. Ключ сервер ищет в таком порядке: NANOBANANA_API_KEY, NANOBANANA_GEMINI_API_KEY, NANOBANANA_GOOGLE_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY.

В сессии Claude получает инструменты generate_image, edit_image, restore_image, generate_icon, generate_pattern, generate_story и generate_diagram. Файлы сохраняются в nanobanana-output/ внутри рабочего каталога процесса сервера, а в ответе инструмента приходит текст со списком путей, так что Claude знает, где лежит результат, и может перенести его в нужную папку. Исходные изображения для правки сервер ищет в текущем каталоге, в images/, input/, nanobanana-output/, а также в ~/Downloads/ и ~/Desktop/. Изображение в base64 этот сервер в ответе не возвращает, поэтому лимит Claude Code на вывод MCP-инструмента (предупреждение после 10 000 токенов, по умолчанию не больше 25 000) его не касается. Для других серверов, которые отдают картинку прямо в ответе, этот лимит может стать проблемой; поднять его можно переменной MAX_MCP_OUTPUT_TOKENS.

Какие ещё MCP-серверы стоит держать в Claude Code, собрано в обзоре «Лучшие MCP для Claude Code, которые стоит подключать первыми в 2026 году».

Если вы пользуетесь cc-nano-banana через Gemini CLI

Скилл cc-nano-banana не обращается к Gemini сам: он поручает работу Gemini CLI с тем же расширением. Цепочка длиннее (Claude Code → Gemini CLI → MCP-сервер → Gemini API), но исправление то же — export NANOBANANA_MODEL=gemini-3.1-flash-image в оболочке, где запускается gemini, плюс ключ в NANOBANANA_GEMINI_API_KEY. Если Gemini CLI вам больше ни для чего не нужен, проще подключить сервер к Claude Code напрямую, как описано выше, или перейти на скилл со скриптом.

Сколько стоит одна картинка и нужен ли биллинг

Цены платного уровня Gemini API на 24 сентября 2026 года, в долларах за одно сгенерированное изображение (прайс Google):

В пакетном режиме (Batch) цена вдвое ниже: $0,0168 за картинку Lite и $0,034 за картинку Nano Banana 2 в 1K.

Каждое входное изображение-референс добавляет около $0,0011, текстовые токены промпта стоят ещё меньше. Считается просто: число картинок × цена за размер. Например, 30 обложек Nano Banana 2 в 2K — это 30 × $0,101 ≈ $3,03, а если для черновиков сначала прогнать 30 вариантов в Lite (30 × $0,0336 ≈ $1,01) и затем довести в Pro пять лучших в 2K (5 × $0,134 = $0,67), выйдет около $1,68 без учёта референсов. Batch для интерактивной работы в Claude Code не подходит: он нужен, когда результат можно ждать. Подробный разбор тарифов и Batch — в статье «Цены Nano Banana API: Lite, Nano Banana 2, Pro и Batch».

Бесплатного уровня для всех трёх моделей изображений в Gemini API нет: в прайсе у них стоит «Not available». Ключ из AI Studio без привязанного платёжного аккаунта не подходит, и никакой скилл или MCP это не обойдёт. Данные запросов на платном уровне, по условиям Google, для улучшения продуктов не используются.

Отдельное условие для читателей из России: России нет в списке регионов, где доступен Gemini API, а Google Cloud с 10 марта 2022 года приостановил регистрацию новых аккаунтов для пользователей в России. Стандартный путь из этой статьи рассчитан на то, что ваш аккаунт Google и платёжный профиль относятся к поддерживаемой стране. Если это не так, официального варианта с ключом Google нет.

Сторонние сервисы с Gemini-совместимым API подключаются к тому же скрипту без правок кода: достаточно задать GEMINI_BASE_URL и положить в GEMINI_API_KEY ключ этого сервиса. Например, laozhang.ai по состоянию на 24 сентября 2026 года продаёт вызовы gemini-3.1-flash-lite-image по $0,025, gemini-3.1-flash-image по $0,055 и gemini-3-pro-image по $0,09 за запрос независимо от разрешения (документация) и принимает запросы в формате Gemini generateContent. В офлайн-проверке запрос из скрипта с GEMINI_BASE_URL=https://api.laozhang.ai и фиктивным ключом дошёл до шлюза и получил 401 Invalid token, то есть маршрут настраивается, но реальная генерация через него не проверялась. Это не Google: на такой сервис не распространяются условия обработки данных и SLA Google, действуют правила самого провайдера, и допустимость его использования в вашей ситуации нужно оценивать по этим правилам, а не считать его способом обойти региональные ограничения.

То же касается хостинговых MCP-серверов и каталогов скиллов, которые предлагают подключить Nano Banana «в один клик». Через чужой сервер проходят ваши промпты, исходные изображения и часто сам ключ Google. Если код сервера нельзя прочитать и запустить у себя, это вопрос доверия к конкретному провайдеру, а не к Nano Banana.

Claude Desktop, Cowork и claude.ai: где это не работает

• Терминальный Claude Code — работают оба варианта.
• Вкладка Code в Claude Desktop в локальной сессии берёт MCP-серверы из того же ~/.claude.json, что и терминал, и работает с файлами на вашей машине.
• Cowork не читает ~/.claude/skills/. В его сессиях доступны только скиллы, включённые для вашего аккаунта claude.ai (раздел Customize в боковой панели Desktop). Личный скилл из этой статьи туда нужно добавить отдельно, а скрипту в той среде тоже понадобятся ключ и библиотека.
• Облачные сессии и routines тоже не видят ~/.claude/skills/, но загружают скиллы, закоммиченные в .claude/skills/ репозитория. Поэтому для них проектный вариант скилла удобнее личного; переменная с ключом должна быть задана в облачном окружении.
• Чат claude.ai не запускает ваши скрипты и локальные MCP-серверы. Там Claude может нарисовать SVG или диаграмму, но не вызвать Nano Banana из ваших настроек.

Если Claude Code ещё не установлен, начните с руководства «Как установить Claude Code: полное руководство для всех платформ».

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

Есть ли Nano Banana в Claude по умолчанию?

Нет. Ни Claude Code, ни приложения Claude не содержат Nano Banana и не создают растровые изображения сами. Модель подключается снаружи — скиллом со скриптом или MCP-сервером, и платите вы за неё Google (или стороннему провайдеру), а не Anthropic.

Как добавить скилл в Claude Code?

Создайте папку .claude/skills/<имя>/ в проекте или ~/.claude/skills/<имя>/ в домашнем каталоге и положите в неё SKILL.md с YAML-шапкой (name, description) и инструкциями. Claude Code подключит скилл, когда запрос совпадёт с описанием, либо по команде /<имя>. Готовый пример для Nano Banana приведён выше.

Хватит ли бесплатного ключа из AI Studio?

Для генерации изображений — нет. У gemini-3.1-flash-image, gemini-3-pro-image и gemini-3.1-flash-lite-image бесплатного уровня в Gemini API нет, нужен ключ проекта с включённым биллингом.

Какой ID модели указать, чтобы через месяц не пришлось переделывать?

gemini-3.1-flash-image для основной работы и gemini-3-pro-image для сложных сцен: обе модели вышли в GA 28 мая 2026 года, дата отключения для них не объявлена. Не указывайте ID с суффиксом -preview и не рассчитывайте на gemini-2.5-flash-image — в Gemini API он отключается 2 октября 2026 года.