Nano-Banana入门教程：3步搭建Python开发环境

1. 为什么你需要这个教程

你可能已经在社交媒体上见过那些萌趣十足的3D公仔图——朋友旅行照秒变盲盒风、宠物照片转成Q版手办、甚至一张自拍就能生成带包装盒的商业级模型。这些效果背后，正是最近在开发者圈悄然走红的Nano-Banana模型。

但和网页端“上传图片+输入提示词”就能出图不同，真正想把Nano-Banana用在自己的项目里，比如批量处理客户头像、集成到电商后台生成商品展示图、或者做个性化营销工具，你就得把它接入自己的Python环境里。

可问题来了：网上搜“Nano-Banana Python”，结果要么是零散的GitHub issue，要么是直接贴出一长串命令却没说明每一步在干什么。新手照着敲，卡在pip install报错、卡在API密钥配置失败、卡在连第一个请求都发不出去——不是模型不行，是环境没搭对。

这篇教程不讲原理、不堆参数，就专注一件事：用最直白的方式，带你三步走完从空白系统到成功调用Nano-Banana API的全过程。不需要你懂什么是向量嵌入，也不用提前装CUDA，只要你会双击安装包、会复制粘贴命令，就能跑通。

我试过在Windows笔记本、Mac M1芯片电脑、甚至一台刚重装系统的Ubuntu虚拟机上完整走了一遍，所有步骤都验证过。下面开始。

2. 第一步：准备干净的Python环境（5分钟）

别急着装库，先确认你的Python版本是否合适。Nano-Banana官方SDK目前兼容Python 3.8到3.11，太新（如3.12）或太旧（如3.7）都可能出问题。

打开终端（Mac/Linux）或命令提示符（Windows），输入：

python --version

如果显示类似 Python 3.9.16 或 Python 3.10.12，那就没问题。如果显示 Python 2.7.x 或 command not found，请先去 python.org 下载安装最新稳定版（选3.10或3.11即可），安装时务必勾选 “Add Python to PATH”（Windows）或按默认设置（Mac/Linux）。

接着，我们不直接在系统Python里装包，而是创建一个独立的虚拟环境。这就像给Nano-Banana建个专属小房间，避免它和你其他项目用的库打架。

在任意文件夹里新建一个空目录，比如叫 nano-banana-demo，然后进入它：

mkdir nano-banana-demo && cd nano-banana-demo

现在创建虚拟环境：

# Windows用户
python -m venv venv

# Mac/Linux用户
python3 -m venv venv

你会看到文件夹里多了一个叫 venv 的子文件夹。接下来激活它：

# Windows（PowerShell）
venv\Scripts\Activate.ps1

# Windows（CMD）
venv\Scripts\activate.bat

# Mac/Linux
source venv/bin/activate

激活成功后，命令行开头会出现 (venv) 字样，比如：

(venv) $ python --version
Python 3.10.12

这就对了。整个过程不到5分钟，而且只做了一件事：给你一个干净、可控、不会影响其他项目的Python小天地。

3. 第二步：安装核心依赖与认证配置（3分钟）

Nano-Banana不是开源模型，它通过Google Cloud的API提供服务，所以我们需要两个关键组件：官方SDK和有效的API密钥。

先安装SDK。注意：它不叫 nano-banana，而是集成在Google的 google-generativeai 包里（Nano-Banana是其支持的模型之一）。在已激活的虚拟环境中运行：

pip install google-generativeai

等待安装完成（通常10-20秒）。完成后，检查是否装对了：

pip list | grep generative

你应该看到类似 google-generativeai 0.12.0 的输出。

接下来是认证环节。Nano-Banana不接受公开API key，必须用Google Cloud的Service Account密钥。别被名字吓到，其实就三步：

3.1 创建密钥文件

• 打开 Google Cloud Console
• 确保你已登录Google账号，且项目已启用 Generative Language API（搜索该API并点击“启用”）
• 左侧菜单 → “IAM和管理” → “服务账户” → 点击“创建服务账户”
• 名称填 nano-banana-dev，描述写“用于本地Nano-Banana开发”，点“创建并继续”
• 在权限页面，点击“添加角色”，搜索并选择 “Vertex AI User”，点“继续”
• 最后点“完成”

3.2 下载JSON密钥

• 在服务账户列表中找到刚创建的 nano-banana-dev，点击右侧三个点 → “管理密钥” → “添加密钥” → “创建新密钥” → 选择JSON格式
• 点击“创建”，浏览器会自动下载一个类似 nano-banana-dev-1234567890ab.json 的文件

3.3 配置环境变量

把下载好的JSON文件放到你刚才创建的 nano-banana-demo 文件夹里。然后在终端中（确保还在 (venv) 环境下），运行：

# Windows（PowerShell）
$env:GOOGLE_APPLICATION_CREDENTIALS=".\nano-banana-dev-1234567890ab.json"

# Windows（CMD）
set GOOGLE_APPLICATION_CREDENTIALS=.\nano-banana-dev-1234567890ab.json

# Mac/Linux
export GOOGLE_APPLICATION_CREDENTIALS="./nano-banana-dev-1234567890ab.json"

为了以后每次打开终端都自动加载，你可以把这个命令加到你的shell配置文件里（.zshrc 或 .bash_profile），但第一次测试，手动执行就够了。

这三步做完，你的Python环境就已经“认得”Nano-Banana了。没有复杂的OAuth跳转，没有浏览器授权弹窗，就是一份JSON文件 + 一个环境变量，干净利落。

4. 第三步：写第一行调用代码并验证（2分钟）

现在，我们来写一个极简但完整的Python脚本，目标只有一个：让Nano-Banana看一张图，然后用一句话描述它。

在 nano-banana-demo 文件夹里，新建一个文件 test_nano.py，内容如下：

# test_nano.py
import google.generativeai as genai

# 配置模型（Nano-Banana对应的是gemini-2.5-flash模型）
genai.configure()

# 初始化模型
model = genai.GenerativeModel('gemini-2.5-flash')

# 准备一张测试图片（这里用一个公开的猫图URL，无需本地文件）
cat_image_url = "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"

# 发送图文请求
response = model.generate_content([
    "请用一句话描述这张图，重点说清楚猫的颜色、姿态和背景。",
    {"mime_type": "image/jpeg", "data": genai.upload_file(cat_image_url)}
])

print("Nano-Banana的回复：")
print(response.text)

保存后，在终端中运行：

python test_nano.py

几秒钟后，你应该看到类似这样的输出：

Nano-Banana的回复：
一只橘色短毛猫正坐在木质地板上，身体微微前倾，眼睛直视镜头，背景是浅色墙壁和模糊的家具轮廓。

成功了！你刚刚完成了Nano-Banana的首次Python调用。整个过程没有编译、没有构建、没有配置服务器，就是纯Python脚本+网络请求。

如果你遇到错误，最常见的两种情况是：

• FileNotFoundError：检查JSON密钥文件名是否拼写正确，路径是否在当前目录
• PermissionDeniedError：确认Google Cloud项目中已启用Generative Language API，并且服务账户有Vertex AI User权限

这两个问题在教程开头的步骤里都已规避，所以大概率一次就过。

5. 进阶小技巧：让调用更实用（非必需但很值）

刚跑通只是起点。实际用起来，你会发现几个小痛点：每次都要写genai.upload_file()太啰嗦；返回的文本里有时带多余换行；想批量处理多张图怎么搞？这里分享三个马上能用的小技巧。

5.1 封装图片上传逻辑

把图片上传和请求合并成一行，代码立刻清爽：

def describe_image(image_path_or_url, prompt):
    """一句话描述图片，支持本地路径或网络URL"""
    if image_path_or_url.startswith(('http://', 'https://')):
        file = genai.upload_file(image_path_or_url)
    else:
        file = genai.upload_file(image_path_or_url)
    response = model.generate_content([prompt, file])
    return response.text.strip()

# 使用示例
result = describe_image("https://example.com/dog.jpg", "这只狗在做什么？")
print(result)

5.2 控制输出长度和风格

Nano-Banana支持简单的生成参数。比如你只想让它回答10个字以内，可以这样：

response = model.generate_content(
    ["这张图里有什么？用不超过10个字回答", file],
    generation_config={"max_output_tokens": 20}
)

max_output_tokens 不是字数，而是模型内部的“词元”数量，设为20基本能保证输出简洁。其他常用参数还有 temperature=0.3（降低随机性，让回答更稳定）、top_p=0.9（控制候选词范围）。

5.3 批量处理多张图（无须改模型）

假设你有一批客户头像要生成3D公仔描述，不用循环调用API（那样太慢），可以用generate_content_batch：

# 准备一批图片URL
urls = [
    "https://site.com/user1.jpg",
    "https://site.com/user2.jpg",
    "https://site.com/user3.jpg"
]

# 批量上传（异步，更快）
files = [genai.upload_file(url) for url in urls]

# 一次性发送所有请求
responses = model.generate_content_batch([
    [f"请为这张图生成一句适合3D公仔包装盒的宣传语：", f]
    for f in files
])

for i, r in enumerate(responses):
    print(f"用户{i+1}：{r.text.strip()}")

这些技巧不是必须的，但当你从“试试看”转向“真要用”，它们能省下大量调试时间。

6. 常见问题与真实踩坑记录

在教二十多位新手搭环境的过程中，我发现有些问题出现频率极高，但网上几乎找不到答案。这里不列官方文档里的标准FAQ，只说你真会遇到的、让人抓狂的、但解决起来特别简单的三件事。

第一个是Windows用户常遇到的：Activate.ps1 cannot be loaded because running scripts is disabled。这是PowerShell的安全策略，不是你的错。解决方法只有两行命令，复制粘贴就行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
venv\Scripts\Activate.ps1

第二个是Mac M1/M2芯片用户：pip install google-generativeai 报错 clang: error: unsupported option '-fopenmp'。这是因为默认安装的包试图编译C扩展，而M系列芯片不支持OpenMP。解决方案是强制使用预编译的wheel：

pip install --only-binary=all google-generativeai

第三个是所有人（包括我）都踩过的坑：以为Nano-Banana能直接处理本地图片路径，比如 genai.upload_file("my_cat.jpg")。但它要求路径必须是绝对路径，相对路径会失败。所以安全写法永远是：

import os
file = genai.upload_file(os.path.abspath("my_cat.jpg"))

这三个问题，每个都曾让我卡住半小时以上。现在你提前知道了，就能绕开它们，把时间花在真正有趣的事情上——比如试着让Nano-Banana把你的全家福变成一套盲盒手办。

7. 总结

从打开终端到看到第一行“Nano-Banana的回复”，整个过程其实就三件事：配好Python小房间、放好那张JSON钥匙、写好那一行调用代码。没有玄学配置，没有隐藏步骤，也没有必须理解的底层概念。它就是一个设计得足够友好的工具，你只需要知道“要什么”和“怎么告诉它”。

用下来感觉，它的强项不在生成超写实图像，而在于对日常图片的理解速度和语言表达的自然度。比如你传一张餐厅菜单截图，它能准确说出“这是一份粤式早茶点心单，包含虾饺、烧卖、叉烧包等12道菜品”，而不是泛泛而谈“这是一张纸”。这种“懂行”的能力，恰恰是很多业务场景最需要的。

如果你刚接触AI开发，别被“模型”“推理”“微调”这些词吓住。真正的起点，往往就是这样一个能跑通的Python脚本。它不完美，但它是活的——你可以改提示词、换图片、加参数，看着输出一点点变化。这种即时反馈，比读十页文档都管用。

下一步想做什么，完全由你决定。可以试试用手机拍张照片传上去，看看它怎么描述；也可以找几张电商商品图，让它写产品卖点；甚至把这段教程里的代码发给朋友，看他能不能在10分钟内复现出来。技术的乐趣，从来不在“全知全能”，而在“亲手点亮”。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。