Nano Banana 2图像生成实战：用JSON提示词实现精准可控出图

Nano Banana 2 在中文社区通常指谷歌新一代图像生成模型（对应 Gemini 系列中的图像生成模型迭代），很多带中文字幕的讲解视频会直接用一段 JSON 提示词来控制画面细节。JSON 在这里不只是配置文件的格式，它本质上是一份“可编程的视觉需求说明书”。把语言描述拆成字段，再交给模型执行，出图稳定性和可复用性都会明显提高。这篇内容会从模型概念讲起，给出完整的环境准备、JSON 提示词模板、Python 调用示例、存储传输方案、常见排错和最佳实践，适合想在图片生成工作流里引入结构化提示词的开发者参考。

1. 先理解 Nano Banana 2 与 JSON 提示词之间的关系

很多人第一次看到“Nano Banana 2”这个名称时，会误以为它是一个独立的软件工具。实际上，这是社区对谷歌图像生成模型的昵称，官方 API 中的模型名通常是gemini-2.5-flash-image之类。这个模型的核心能力是：根据一段文本描述生成或编辑图像，并且能比较准确地理解物体关系、画面构图和风格化指令。

为什么要专门用 JSON 提示词？因为自然语言提示词虽然方便，但存在几个实际问题：字段边界模糊，模型可能把“主体”和“背景”混在一起；同样一句话在不同图片上执行结果差异很大；一旦需要批量生成，后续无法做参数对比和版本管理。JSON 提示词把需求结构化，相当于给模型一张明确的“需求表单”。

1.1 Nano Banana 类图像模型的底层能力范围

图像生成模型并不是一个简单的“文生图”工具。以 Gemini 图像生成模型为例，它支持图像编辑、局部重绘、多轮对话式改图，也能理解用户上传的参考图。也就是说，提示词不仅能描述“画什么”，还能描述“在上一张图的基础上改哪里、改成什么样”。

这种能力给提示词设计带来了新的要求。如果提示词只是一句“画一只戴眼镜的香蕉”，模型虽然能出图，但细节完全不可控。换成 JSON 提示词后，可以把主体、动作、场景、镜头、风格、色彩、文本内容甚至负面要求拆开写，模型按字段逐项落实。

1.2 为什么结构化提示词比一句自然语言更可控

自然语言提示词本质上是一段连续文本。模型要从整段文本里做意图解析，而意图解析常常有歧义。比如“一个穿着校服的男孩在教室里看着电脑，屏幕上有 JSON 代码，画面偏蓝色调”这句话，模型可能侧重人物，忽略屏幕内容；也可能把“偏蓝色调”理解成整体环境光，而不是画面后期风格。

JSON 提示词将信息分割成 key-value 结构后，模型更容易把每个字段当作一个独立约束。下面用一个对比表说明差异：

当然，JSON 提示词不是银弹。模型最终理解的是文本语义，而不是真的在读取数据结构。但实践表明，结构化表达能显著减少歧义，尤其适合生成细节较多的图片场景。

1.3 读这篇文章需要什么基础

这篇文章默认读者具备以下基础：

• 会使用 Python，能安装 pip 包并运行脚本。
• 了解 JSON 的基本语法，比如对象、数组、字符串和嵌套结构。
• 有谷歌 AI Studio 或 Gemini API 的访问权限，并准备了一个 API Key。

如果完全没接触过 API，建议先跑通官方文档里的最小示例，再回来学习 JSON 提示词的写法。下面从环境准备开始。

2. 准备运行环境：API Key、SDK 与最小请求

图像生成 API 的调试链路比普通文本接口长，因为涉及模型名、提示词、图像输出格式和二进制内容解析。环境没准备好时，后面所有 JSON 提示词都无从验证。

2.1 需要准备的资源清单

先明确需要的东西：

注意：API Key 属于敏感凭据，不要把它写死在代码里，也不要提交到 Git 仓库。建议使用环境变量或本地密钥文件管理。

2.2 安装 google-genai SDK

google-genai 是官方的 Python SDK。安装命令如下：

pip install google-genai

如果是在已有虚拟环境中安装，建议先创建虚拟环境，避免污染全局 Python：

python -m venv .venv source .venv/bin/activate # Windows 下执行 .venv\Scripts\activate pip install --upgrade pip pip install google-genai pillow

这里还安装了 Pillow，用于后续把返回的二进制图像数据保存成 PNG 文件。安装完成后，可以用下面的命令确认版本号：

pip show google-genai

如果网络环境有限制，可以先配置 pip 镜像源，再继续安装。

2.3 用环境变量配置 API Key

在项目目录下创建.env文件不是必须的，但推荐使用环境变量。这里在终端中直接导出：

export GEMINI_API_KEY="你的 API Key"

在 Windows PowerShell 中：

$env:GEMINI_API_KEY = "你的 API Key"

Python 代码里通过os.environ读取：

import os api_key = os.environ.get("GEMINI_API_KEY") if not api_key: raise RuntimeError("请先设置 GEMINI_API_KEY 环境变量")

这样做的核心目的是防止凭据泄露，同时也方便在不同环境中切换 Key。

2.4 发送第一个图像生成请求

完成环境准备后，先发送一个最简单的文本提示词请求，验证链路是否通畅：

import os from google import genai from google.genai import types client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY")) response = client.models.generate_images( model="gemini-2.5-flash-image", prompt="a yellow banana wearing glasses, cartoon style", config=types.GenerateImagesConfig( number_of_images=1, aspect_ratio="1:1", output_mime_type="image/png", ), ) image_bytes = response.generated_images[0].image.image_bytes with open("first_test.png", "wb") as f: f.write(image_bytes) print("image saved to first_test.png")

检查点：

• 脚本没有报认证错误，说明 API Key 有效。
• 本地生成了first_test.png，说明图像输出链路正常。
• 如果能正常出图，再开始替换成 JSON 提示词。

这里要注意，实际项目里model名称要以官方文档当时公布的模型为准。社区可能称它为 Nano Banana 2，但代码中应使用可运行的模型标识符。

3. 构造一份可复用的 JSON 提示词模板

基础请求跑通后，核心工作就变成了“设计提示词结构”。JSON 提示词的设计质量，直接影响出图效果。

3.1 JSON 提示词里的核心字段如何划分

图像生成类提示词通常可以分为几组：

• 任务描述：告诉模型要生成新图，还是编辑已有图。
• 主体信息：谁出现在画面里，长什么样子。
• 场景与背景：发生在什么地方，前后景如何安排。
• 风格与质感：写实、卡通、3D、水彩、赛博朋克等。
• 构图与镜头：景别、角度、主体位置、镜头焦距。
• 色彩与光影：整体色调、光源方向、氛围。
• 画面文字：需要出现哪些文本，必须逐字写清。
• 负面描述：不想要什么元素。

把这些信息组织成 JSON 对象时，字段名最好清晰一致。下面是一个可用的模板：

{ "task": "generate", "metadata": { "scene_id": "scene_001", "version": "1.0" }, "subject": { "name": "a small banana character", "attributes": ["wearing round glasses", "holding a tiny laptop"], "expression": "focused and curious" }, "scene": { "location": "on a wooden desk beside a coffee cup", "background": "blurred bookshelf and warm window light", "props": ["laptop screen showing JSON code", "a small notebook"] }, "style": { "base": "3D render", "lighting": "soft studio lighting", "color_palette": "warm yellow and brown tones" }, "composition": { "camera_angle": "slightly high angle", "framing": "medium close-up, subject centered", "depth_of_field": "shallow" }, "text_on_image": { "content": "JSON", "position": "on laptop screen", "language": "English" }, "negative_prompt": "blurry, distorted hands, watermark, low resolution" }

这份模板不是固定标准，而是一个思考框架。实际项目中完全可以删减或增加字段，但要注意，模型未必认识所有自定义字段。因此建议至少保留subject、scene、style这三个核心项，其余字段作为补充描述。

3.2 为什么字段不能随意使用大写字母

JSON 本身区分大小写，字段名和枚举值的大小写不同，语义就可能不同。比如"style": {"base": "3D render"}里的3D写成3d，模型通常能理解，但换成"Style"就可能导致解析歧义。更严重的是，有些语言或框架在对象属性名首字母大写时，序列化行为会发生变化。

这在实际集成中很常见。比如 Java 后端定义了一个ImagePrompt类，字段名是Scene，使用某些 JSON 库序列化后，输出可能是"scene"，也可能是"Scene"，取决于库的命名策略。如果下游模型只识别小写字段，而接口传过去的是大写开头，就可能解析失败。

统一约定：JSON 提示词字段全部使用小写驼峰或者小写下划线，比如camera_angle、color_palette。这样在 Python、Java、Go 之间传递时不容易出现大小写不一致问题。

3.3 用 JSON 数组管理多个画面版本

有时一次需要生成多个风格变体。这时可以把提示词组织成 JSON 数组，每个元素代表一个版本：

[ { "version": "cartoon", "style": {"base": "2D cartoon", "color_palette": "bright primary colors"} }, { "version": "realistic", "style": {"base": "photorealistic", "color_palette": "natural colors"} }, { "version": "cyberpunk", "style": {"base": "neon cyberpunk", "color_palette": "pink and blue"} } ]

在调用时，把整个数组序列化成字符串传给prompt字段，并在提示词里加上“请根据每个版本生成一张图”。这种写法的好处是，后续可以在代码里遍历数组，把每次请求的 JSON 原样记录下来，方便对比不同风格的效果。

3.4 提示词模板与模型返回 JSON 的配合方式

图像生成接口返回的数据中，除了图片二进制内容，还包含元信息字段。后续处理时需要把这些信息一并保存。返回结构类似：

{ "generated_images": [ { "image": { "image_bytes": "...", "mime_type": "image/png" }, "metadata": { "model_version": "gemini-2.5-flash-image", "token_count": 128 } } ] }

具体字段名以 SDK 版本为准。实际开发中，比较重要的做法是：把请求时使用的提示词 JSON 和返回的响应 JSON 一起持久化，这样将来排查“为什么这张图效果不对”时，能完整还原生成现场。

4. 用 Python 调用生成接口并保存 JSON 结果

模板确定后，就可以写一段完整脚本，把提示词 JSON 作为输入，生成图像，并把运行结果保存到本地文件和 SQLite 数据库。

4.1 从 JSON 文件读取提示词

先把提示词模板保存为prompt.json，这样提示词和代码分离，后续修改提示词不需要改代码。读取方式：

import json with open("prompt.json", "r", encoding="utf-8") as f: prompt_obj = json.load(f)

注意，这里使用encoding="utf-8"是为了防止中文注释或中文字段出现乱码。如果提示词中包含中文文本，序列化时也需要设置为ensure_ascii=False，否则中文会被转成\uXXXX，既不美观，也不利于日志排查。

4.2 发送请求并保存返回图片

完整调用代码如下：

import json import logging import os from datetime import datetime from google import genai from google.genai import types logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") logger = logging.getLogger(__name__) api_key = os.environ.get("GEMINI_API_KEY") client = genai.Client(api_key=api_key) def load_prompt(path: str) -> dict: with open(path, "r", encoding="utf-8") as f: return json.load(f) def generate_image(prompt_obj: dict, output_dir: str = "output") -> dict: os.makedirs(output_dir, exist_ok=True) prompt_str = json.dumps(prompt_obj, ensure_ascii=False, indent=2) logger.info("start generating with prompt: %s", prompt_str) response = client.models.generate_images( model="gemini-2.5-flash-image", prompt=prompt_str, config=types.GenerateImagesConfig( number_of_images=1, aspect_ratio="16:9", output_mime_type="image/png", ), ) image_bytes = response.generated_images[0].image.image_bytes timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") image_path = os.path.join(output_dir, f"output_{timestamp}.png") with open(image_path, "wb") as f: f.write(image_bytes) result = { "status": "success", "image_path": image_path, "prompt_used": prompt_obj, "created_at": timestamp, } with open(os.path.join(output_dir, f"result_{timestamp}.json"), "w", encoding="utf-8") as f: json.dump(result, f, ensure_ascii=False, indent=2) logger.info("image saved to %s", image_path) return result if __name__ == "__main__": prompt = load_prompt("prompt.json") result = generate_image(prompt) print(json.dumps(result, ensure_ascii=False, indent=2))

关键点：

• json.dumps(..., ensure_ascii=False)会保留中文，方便在日志和结果文件中阅读。
• 每次生成都记录prompt_used，保证可回溯。
• 图片和 JSON 结果使用同一个时间戳命名，便于关联。
• number_of_images=1控制单次返回图片数量，数量越大消耗额度越多。

4.3 把 JSON 结果写入 SQLite

当生成任务变多后，文件式管理会混乱，需要把任务信息写入 SQLite。先建表：

CREATE TABLE IF NOT EXISTS image_task ( id INTEGER PRIMARY KEY AUTOINCREMENT, task_name TEXT NOT NULL, prompt_json TEXT NOT NULL, result_path TEXT, status TEXT DEFAULT 'pending', error_message TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP, updated_at TEXT DEFAULT CURRENT_TIMESTAMP );

Python 写入逻辑：

import sqlite3 def insert_task(task_name: str, prompt_obj: dict): conn = sqlite3.connect("image_task.db") cursor = conn.cursor() cursor.execute( """ INSERT INTO image_task (task_name, prompt_json, status) VALUES (?, ?, ?) """, (task_name, json.dumps(prompt_obj, ensure_ascii=False), "pending"), ) conn.commit() task_id = cursor.lastrowid conn.close() return task_id def update_task_result(task_id: int, image_path: str): conn = sqlite3.connect("image_task.db") cursor = conn.cursor() cursor.execute( """ UPDATE image_task SET result_path = ?, status = 'success', updated_at = CURRENT_TIMESTAMP WHERE id = ? """, (image_path, task_id), ) conn.commit() conn.close()

这里的prompt_json字段直接存储文本型 JSON，查询时可用json_extract做简单筛选。比如查询所有包含"task": "generate"的记录：

SELECT id, task_name FROM image_task WHERE json_extract(prompt_json, '$.task') = 'generate';

SQLite 的 JSON 函数在较新版本中默认可用，非常适合做提示词任务的中转存储。

4.4 Java 等其他语言遇到的大小写序列化问题

很多团队的后端不是 Python，而是 Java。Java 中如果 Bean 属性名是大写字母开头，序列化成 JSON 时可能出现字段名变化。比如SceneName属性可能被序列化成scenename或SceneName，取决于 Jackson、Gson 的配置。

推荐的规避方式：

• 与前后端、模型侧约定统一的字段命名规范。
• Java Bean 属性使用小写驼峰，例如sceneName、colorPalette。
• 如果必须保留特殊字段名，可以使用@JsonProperty("scene_name")指定序列化名称。
• 不要依赖框架默认规则，关键字段全部显式指定。

如果原始项目中已经存在大写字段问题，可以在序列化后统一做一次字段名映射转换，但更深层的做法是重构 Bean 命名。

5. 从 Demo 到工程化：JSON 提示词的存储、传输与版本管理

单机脚本能出图后，下一步要考虑的是：提示词从哪里来、如何传输、如何落库、如何做多版本管理。

5.1 不要把提示词硬编码在业务代码里

常见错误是直接把 JSON 字符串写在 Python 文件或 Java 类里。这种写法的坏处：

• 提示词更新需要重新发版。
• 不同业务场景无法复用同一套代码。
• 日志和参数无法分离。

推荐做法是把提示词文件放在独立目录，例如：

config/ prompts/ product_shot.json character_design.json scene_edit.json

代码中通过配置中心或本地配置目录加载。若团队已经使用配置中心，可以把提示词 JSON 作为配置项下发给服务，运行时动态读取。

5.2 用 SQLite 管理任务状态时的字段设计

工程化任务表不应该只存提示词和结果路径，还应包含任务状态机，常见状态有pending、processing、success、failed。状态更新时，错误信息要单独保存，便于事后分析。

一个更完整的表结构：

CREATE TABLE image_task ( id INTEGER PRIMARY KEY AUTOINCREMENT, scene_id TEXT NOT NULL, prompt_version TEXT, prompt_json TEXT NOT NULL, model_name TEXT, image_path TEXT, status TEXT NOT NULL DEFAULT 'pending', error_code TEXT, error_message TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP, started_at TEXT, finished_at TEXT ); CREATE INDEX idx_image_task_status ON image_task(status); CREATE INDEX idx_image_task_scene_id ON image_task(scene_id);

增加索引和常用时间字段，后续统计每日生成量、失败率时会很方便。

5.3 通过 RabbitMQ 传输 JSON 提示词的实践

当图片生成不是同步接口，而是异步任务时，可以使用消息队列分发任务。生产端把 JSON 提示词作为消息体发送，消费端接收后调用模型并更新结果。

生产端示例：

import json import pika connection = pika.BlockingConnection(pika.ConnectionParameters("localhost")) channel = connection.channel() queue_name = "image_task_queue" channel.queue_declare(queue=queue_name, durable=True) task = { "task_id": "TASK-0001", "scene_id": "scene_001", "prompt": prompt_obj, "model": "gemini-2.5-flash-image" } channel.basic_publish( exchange="", routing_key=queue_name, body=json.dumps(task, ensure_ascii=False), properties=pika.BasicProperties( delivery_mode=2, content_type="application/json" ) ) print("task published") connection.close()

消费端核心逻辑：

import json import pika def callback(ch, method, properties, body): task = json.loads(body) print(f"receive task: {task['task_id']}") # 调用图像生成接口，保存图片，更新数据库 ch.basic_ack(delivery_tag=method.delivery_tag) connection = pika.BlockingConnection(pika.ConnectionParameters("localhost")) channel = connection.channel() channel.queue_declare(queue="image_task_queue", durable=True) channel.basic_qos(prefetch_count=1) channel.basic_consume(queue="image_task_queue", on_message_callback=callback) print("waiting for tasks...") channel.start_consuming()

这里使用basic_ack确认消息消费成功，失败时不能确认，以保证消息不丢失。生产环境还需要考虑死信队列和重试策略。

5.4 与 DataX 等数据同步工具配合时的 JSON 字段映射

DataX 是一个数据同步工具，它本身使用 JSON 配置 job。如果需要把 SQLite 或 MySQL 中的提示词任务同步到其他存储，可以在 DataX 的job配置里定义 reader 和 writer。例如从 MySQL 读取提示词任务，写入 JSON 文件：

{ "job": { "content": [ { "reader": { "name": "mysqlreader", "parameter": { "username": "root", "password": "****", "column": ["id", "scene_id", "prompt_json"], "splitPk": "id", "connection": [ { "table": ["image_task"], "jdbcUrl": ["jdbc:mysql://localhost:3306/image_db"] } ] } }, "writer": { "name": "jsonfilewriter", "parameter": { "path": "/data/output", "fileName": "image_task.json", "writeMode": "truncate" } } } ], "setting": { "speed": { "channel": 2 } } } }

关键点：DataX 本身只负责搬移数据，不负责解析提示词内容。因此字段类型尽量保持为字符串，不要在中途做 JSON 格式化，避免数据变形。

6. 常见报错与排查路径

JSON 提示词接入图像生成接口后，报错类型通常集中在 JSON 解析、字段格式、接口参数、内容安全、返回结果不匹配这几个方面。

6.1 问题现象与处理方案速查表

6.2 JSON 解析失败要从哪一层查起

出现invalid JSON时，先确认是哪一个 JSON 出问题：

1. 本地prompt.json是否有语法错误。
2. 代码中json.dumps序列化后的字符串是否符合预期。
3. 传输到服务端前，是否被日志系统截断或转义。
4. 服务端返回的错误信息里，是否包含具体行号和字符位置。

可以在 Python 中快速校验：

python -m json.tool prompt.json

如果没有输出任何错误，说明 JSON 语法没问题，问题可能出在后续字段内容或接口兼容性上。

6.3 生成结果与提示词不一致的排查思路

如果 JSON 完全合法，但图片和预期差距很大，优先怀疑语义冲突。比如subject里写“一只戴眼镜的香蕉”，scene里又写“房间里有一个人”，模型可能把人与香蕉同时放进画面。

排查顺序：

1. 只保留subject字段，去掉其他字段，看主体是否正确。
2. 单独加入scene字段，看场景是否按预期变化。
3. 最后加style和composition，逐步逼近目标画面。

这个方法类似二分排查，能快速定位是哪个字段干扰了结果。

6.4 在 JMeter 或 LabVIEW 中调试 JSON 提示词的思路

部分开发者在接口测试或自动化工具中处理 JSON。JMeter 里常用 JSON Extractor 提取响应字段。比如接口返回的任务编号task_id，可以通过 JSON Path 表达式$.taskId提取，传递给下一个请求。注意 JSON Path 表达式直接依赖字段名大小写，接口返回taskId时，提取taskId；如果返回task_id，则写$.task_id。

LabVIEW 场景中，先读取 JSON 文件，用 LabVIEW 的 JSON 库解析成对应的键值对，再拼接到 API 请求头或请求体中。这里的常见问题是：LabVIEW 的字符串转义规则和 Python 不同，拼接 JSON 时容易把双引号丢掉。建议在 LabVIEW 中直接使用字节流方式读取文件，避免多次转义。

7. 最佳实践：搭建一套稳定的 JSON 提示词工作流

有了代码和排错能力后，更关键的是建立一套可持续使用的工作流。只有提示词、任务、结果三者形成闭环，后续优化才有数据支撑。

7.1 提示词组织方式的三种推荐模式

建议从“JSON 文件加版本号”开始，比如prompt_v1.0.json、prompt_v1.1.json。等任务规模上来，再迁到数据库。

7.2 用 JSON Schema 做前置校验

为了防止错误提示词进入模型调用，可以在发送前用 JSON Schema 做一次结构校验。示例：

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["subject", "scene", "style"], "properties": { "subject": { "type": "object", "required": ["name"], "properties": { "name": {"type": "string"}, "attributes": {"type": "array", "items": {"type": "string"}} } }, "scene": {"type": "object"}, "style": {"type": "object"} }, "additionalProperties": true }

Python 中可以使用jsonschema库校验：

pip install jsonschema

import json import jsonschema from jsonschema import Draft7Validator schema = json.load(open("prompt_schema.json", encoding="utf-8")) prompt = json.load(open("prompt.json", encoding="utf-8")) validator = Draft7Validator(schema) errors = sorted(validator.iter_errors(prompt), key=lambda e: e.path) if errors: for err in errors: print(f"字段 {list(err.path)}: {err.message}") else: print("prompt schema check passed")

前置校验能拦截大部分字段缺失问题，避免浪费 API 额度。

7.3 生产环境发布前的检查清单

生产环境接入 JSON 提示词图像生成服务时，至少检查以下项：

• [ ] API Key 是否通过环境变量或密钥服务注入，而不是写死在代码里。
• [ ] 模型名称是否与当前账号权限匹配。
• [ ] 是否存在超时重试、指数退避机制。
• [ ] 是否记录完整的请求 JSON、响应 JSON 和失败原因。
• [ ] 是否把生成的图片保存到对象存储，而不是只放在本地磁盘。
• [ ] 是否对用户输入的提示词做长度限制和敏感词校验。
• [ ] 数据库中的任务状态是否具备人工重跑能力。
• [ ] 是否设定每日调用额度和告警阈值。
• [ ] 是否保留原始提示词的版本记录，方便对比效果。
• [ ] 是否存在队列积压监控，消费进程挂掉后能否自动恢复。

7.4 下一步可以扩展的方向

JSON 提示词只是结构化生成的第一步。后续可以继续探索：

• 用程序批量生成一批提示词，自动跑出多张候选图，再人工筛选。
• 把生成的图片和提示词关联起来，构造属于自己团队的数据集，用于后续模型微调或效果评估。
• 在提示词中加入随机种子或风格权重字段，实现半自动化的风格探索。
• 将提示词模板交给配置平台管理，业务人员不需要改代码就能调整画面效果。

真正的价值不在于“写出一条完美的 JSON 提示词”，而在于建立一套“改参数、跑任务、看结果、记数据”的循环。只要每次生成都能留下结构化记录，图生效果的优化就不会是拍脑袋。建议从小场景开始，先跑通一份 JSON 提示词模板，再把存储、传输、状态管理和排查路径逐个补齐，最终沉淀成团队内部可复用的图像生成工具链。