Запуск бота в Telegram на базе Nano Banana: практическое руководство

Архитектура своего Telegram-бота с генерацией картинок через Gemini API: от токена в BotFather до сервера, бюджета и защиты ключа — с минимальным кодом на Python.

Запуск бота в Telegram на базе Nano Banana: практическое руководство

Свой Telegram-бот на Nano Banana устроен просто: Telegram передаёт сообщение пользователя на ваш сервер, сервер вызывает Gemini API с моделью изображений Google и отправляет готовую картинку обратно в чат. Для запуска нужны токен бота от @BotFather, API-ключ Gemini с платным уровнем, сервер в стране, где Gemini API поддерживается, и сотня строк кода. Основная модель на ноябрь 2026 года — Nano Banana 2.1 (gemini-nano-banana-2.1), картинка 1K стоит $0.0336.

Это руководство для тех, кто хочет сделать бота сам — для себя, команды или клиентов. Если вам нужно просто генерировать картинки в Telegram, писать код не обязательно: готовые боты и агрегаторы разобраны в статье как подключить Nano Banana в Telegram.

Архитектура бота

Минимальная схема из четырёх частей:

Компонент Что делает Что выбрать
Бот в Telegram принимает текст и фото, отправляет картинки создаётся в @BotFather
Сервер с кодом получает обновления, вызывает модель, следит за лимитами VPS или облако в поддерживаемой стране
Gemini API генерирует и редактирует изображения модель Nano Banana 2.1, 2 Lite или Pro
Хранилище лимиты пользователей, история, оплаты SQLite или Redis на старте

Как бот получает сообщения:

  • Long polling — бот сам опрашивает Telegram. Проще всего для старта, не нужен домен и HTTPS.
  • Webhook — Telegram присылает обновления на ваш адрес. Нужен HTTPS, зато лучше для нагрузки.

Для первой версии хватит polling. Генерация занимает секунды, поэтому код должен быть асинхронным: пока один пользователь ждёт картинку, бот отвечает остальным.

Шаг 1. Регистрация бота в BotFather

  1. Откройте @BotFather в Telegram. Это официальный бот Telegram для создания и настройки ботов.
  2. Отправьте команду /newbot. Укажите отображаемое имя, а затем username — он должен заканчиваться на «bot».
  3. Сохраните токен. BotFather пришлёт токен доступа. Это пароль от вашего бота: не публикуйте его и не храните в коде.
  4. Настройте описание и команды. Через BotFather добавьте описание, аватар и список команд, например /start и /help, чтобы пользователи понимали, как пользоваться ботом.

Шаг 2. Ключ Gemini API и выбор модели

API-ключ создаётся в Google AI Studio, а для моделей изображений проекту нужен платный уровень: бесплатного уровня API для них нет. Подробно процесс описан в статье о Nano Banana API, а попробовать модели вручную перед разработкой можно в Google AI Studio.

Какую модель поставить в бота:

Модель model id Цена 1K Когда брать
Nano Banana 2.1 gemini-nano-banana-2.1 $0.0336 по умолчанию: качество, текст, многошаговая правка
Nano Banana 2 Lite gemini-3.1-flash-lite-image $0.0336 быстрые ответы меньше чем за 2 секунды, только 1K
Nano Banana Pro gemini-3-pro-image $0.134 премиум-режим: инфографика, сложные сцены, 4K за $0.24

Старые инструкции по подключению «Gemini 2.5 Flash Image к Telegram» используют первую Nano Banana — gemini-2.5-flash-image. Она ещё работает, но устарела и будет отключена в API 15.03.2027. Модель Nano Banana 2 (gemini-3.1-flash-image) тоже помечена как deprecated — для нового бота её брать не стоит.

Шаг 3. Сервер и регион

Здесь главное ограничение для разработчиков из России. Gemini API официально не работает в РФ: страны нет в списке поддерживаемых регионов. Поэтому законная схема такая: сервер, проект Google Cloud и биллинг находятся в поддерживаемой стране и принадлежат человеку или компании, которые вправе там работать. Размещать бота на сервере внутри России и «прокидывать» запросы в обход ограничений — нарушение условий Google, которое ставит под удар и проект, и аккаунт.

Требования к серверу скромные: генерацию выполняет Google, сервер только пересылает данные. Для старта хватит небольшого VPS с Python 3.10+ и стабильным интернетом. Если ожидается много пользователей, добавьте очередь задач, чтобы не упираться в ограничения скорости API.

Шаг 4. Минимальный код на Python

Пример использует библиотеку python-telegram-bot (версии 20 и новее) и httpx для асинхронного запроса к REST API Gemini. Запрос повторяет формат generateContent из документации: текст в parts и responseModalities с IMAGE.

import base64
import os

import httpx
from telegram import Update
from telegram.ext import Application, ContextTypes, MessageHandler, filters

BOT_TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
GEMINI_KEY = os.environ["GEMINI_API_KEY"]
MODEL = "gemini-nano-banana-2.1"
URL = f"https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:generateContent"


async def generate(prompt: str) -> bytes | None:
    body = {
        "contents": [{"parts": [{"text": prompt}]}],
        "generationConfig": {"responseModalities": ["IMAGE"]},
    }
    async with httpx.AsyncClient(timeout=180) as client:
        r = await client.post(URL, headers={"x-goog-api-key": GEMINI_KEY}, json=body)
    r.raise_for_status()
    candidates = r.json().get("candidates") or []
    parts = candidates[0].get("content", {}).get("parts", []) if candidates else []
    for part in parts:
        if "inlineData" in part:
            return base64.b64decode(part["inlineData"]["data"])
    return None


async def on_text(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Рисую, это может занять до минуты…")
    try:
        image = await generate(update.message.text)
    except httpx.HTTPError:
        image = None
    if image:
        await update.message.reply_photo(photo=image)
    else:
        await update.message.reply_text("Не получилось. Попробуйте описать картинку иначе.")


def main() -> None:
    app = Application.builder().token(BOT_TOKEN).build()
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_text))
    app.run_polling()


if __name__ == "__main__":
    main()

Установка зависимостей: pip install python-telegram-bot httpx. Токены задаются переменными окружения TELEGRAM_BOT_TOKEN и GEMINI_API_KEY.

Что добавить, чтобы бот правил фото, а не только рисовал по тексту: обработчик сообщений с фотографией скачивает самое крупное изображение из update.message.photo, кодирует его в base64 и добавляет в parts объект inlineData с mimeType и data рядом с текстом из подписи к фото. Формат такой же, как в примере правки на Python в статье про API.

Шаг 5. Хранение ключей и безопасность

Ключ Gemini привязан к вашему биллингу, токен бота — к самому боту. Утечка любого из них стоит денег или репутации.

  • Только переменные окружения или менеджер секретов. Никаких ключей в коде, в Git и в скриншотах.
  • Отдельный проект Google Cloud под бота с бюджетом и оповещениями о расходах.
  • Регулярная смена ключей и немедленный отзыв при подозрении на утечку.
  • Белый список администраторов для служебных команд вроде статистики и рассылки.
  • Логи без персональных данных. Не храните фото пользователей дольше, чем нужно для ответа, и предупредите в /start, что изображения передаются в Google для обработки.

Не забывайте и о правилах содержания: фильтры Google работают в API так же, как в Gemini, а за то, что бот делает с фото людей, отвечаете вы. Подробнее о границах допустимого — в статье о блокировках content blocked.

Шаг 6. Лимиты и стоимость

Каждая картинка через API оплачивается, поэтому лимиты на стороне бота обязательны — иначе один активный пользователь или скрипт съест бюджет за вечер.

Что внедрить с первого дня:

  • дневной лимит на пользователя — например, несколько бесплатных генераций, дальше по оплате или приглашению;
  • очередь и ограничение параллельных запросов — API имеет ограничения скорости, которые зависят от уровня вашего проекта;
  • разрешение по умолчанию 1K — 4K у Nano Banana 2.1 стоит $0.113, в три с лишним раза дороже;
  • Pro только по явному выбору — у неё картинка 1K стоит $0.134, вчетверо дороже 2.1.

Пример бюджета на месяц:

Сценарий Модель и разрешение Картинок Стоимость генераций
Личный бот Nano Banana 2.1, 1K 300 около $10
Бот для команды Nano Banana 2.1, 1K 3 000 около $101
Открытый бот с премиумом 2.1 1K + Pro 2K 10 000 + 1 000 около $336 + $134

К этому добавляется стоимость сервера. Если планируете брать оплату с пользователей, заранее изучите правила Telegram для продажи цифровых товаров в ботах.

Типичные проблемы при запуске

  • Ошибка о неподдерживаемом регионе. Сервер или проект находятся вне списка поддерживаемых стран Gemini API.
  • Ответ без картинки. Не указан responseModalities с IMAGE, запрос заблокирован фильтром или неверный model id — превью-идентификаторы с суффиксом -preview отключены 25.06.2026.
  • Бот «зависает». Синхронный HTTP-запрос блокирует обработку остальных сообщений — используйте асинхронный клиент, как в примере.
  • Размытые надписи. Слабость модели на 1K: для текста на картинке берите 2K или Nano Banana Pro.

Если на этапе прототипа хочется сначала проверить, какие запросы вообще понравятся пользователям, можно протестировать модели Nano Banana в готовом агрегаторе с русским интерфейсом и только потом писать собственного бота.

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

Можно ли подключить Nano Banana к Telegram-боту?
Да. Бот получает сообщение, ваш сервер отправляет запрос в Gemini API с model id нужной модели, например gemini-nano-banana-2.1, и возвращает картинку в чат. Нужны токен от BotFather, API-ключ Gemini и сервер.
Сколько стоит содержать бота на Nano Banana?
Основной расход — генерации: у Nano Banana 2.1 картинка 1K стоит $0.0336, то есть 1 000 картинок обойдутся в $33.6. Плюс стоимость сервера. Бесплатного уровня API для изображений нет.
Можно ли запустить такого бота на сервере в России?
Россия не входит в список поддерживаемых регионов Gemini API, поэтому сервер, проект Google Cloud и биллинг должны находиться в поддерживаемой стране.
Можно ли сделать бота на старой модели Gemini 2.5 Flash Image?
Технически да, её id gemini-2.5-flash-image ещё работает, но модель устарела и будет отключена в API 15.03.2027. Для нового проекта лучше сразу брать Nano Banana 2.1 или 2 Lite.

Читайте дальше