Skip to main content
POST
Nano Banana 2.1 是谷歌的图片模型,模型 ID 为 gemini-nano-banana-2.1。便利店按 Gemini 原生接口提供:POST https://code.heihuzi.ai/v1beta/models/gemini-nano-banana-2.1:generateContent。验证日期:2026-10-08。 旧模型 ID gemini-3.1-flash-image 仍可调用,会自动转到 Nano Banana 2.1:实测用旧 ID 请求,响应里的 modelVersion 为 gemini-nano-banana-2.1,按 2.1 计费。新接入请直接使用 gemini-nano-banana-2.1。 请使用绑定「Nano Banana 2.1 画图」分组的 API Key。这个分组不支持 OpenAI Images 接口:用 /v1/images/generations 请求本模型实测返回 404(Images API is not supported for this platform),请按本页使用原生接口。
请求把完整响应保存到 generation.json。运行前设置环境变量 HEIHUZI_API_KEY。鉴权头 x-goog-api-key 与 Authorization: Bearer <Key> 均已验证可用。 响应中的图片是 base64 编码的 JPEG。下面的命令从 generation.json 取出图片,保存为 generation.jpg:

请求参数

object[]
required
对话内容。生成图片时放一条 role: "user" 消息,parts 里写提示词。缺少 contents 实测返回 400。带参考图的写法见图像编辑。
object
生成设置。比例和清晰度写在 generationConfig.imageConfig 里,思考档位写在 generationConfig.thinkingConfig 里。

已验证的比例与尺寸

每行都是一次真实的生产请求:请求结构与上方示例相同,imageSize 为 1K、thinkingLevel 为 minimal,只改 aspectRatio。返回图片均为 JPEG,尺寸为解码后的实际像素。 1:4、4:1、1:8、8:1 的实际像素与谷歌文档的尺寸表略有出入,表中为实测值。 更高清晰度已验证:16:9 + 2K 返回 2752×1536;9:16 + 4K 返回 3072×5504。单张图片一次请求,生成 1K 实测约 10–20 秒(个别请求 30–41 秒),2K 约 18 秒,4K 约 31 秒;偶尔会慢很多,请把客户端超时设为 10 分钟以上。以上是实测耗时,不是响应时间承诺。

真实响应节选

下面是上方示例(16:9、1K、不填思考档位)一次真实响应的节选:图片和 thoughtSignature 的长内容已省略,responseId、turnToken 等字段未列出;token 数和签名大小每次请求都不同。
  • 图片在 candidates[].content.parts[].inlineData:mimeType 本次均为 image/jpeg,data 是 base64。保存图片时跳过带 "thought": true 的部分(模型思考过程中的草图)。本次测试的响应里没有出现这类部分,示例保留跳过逻辑以防上游返回。
  • thoughtSignature 是模型的思考签名,单次生成用不到,可以忽略。它和图片一起返回,所以响应体较大:1K 实测约 1.5~2.4 MB(1:8、8:1 实测 3.1 MB、5.4 MB),2K 约 5.8 MB,4K 约 18 MB,14 张参考图约 7 MB;请按 20 MB 以上预留内存,并设置足够的超时。
  • usageMetadata.candidatesTokensDetails 里 IMAGE 的 token 数,本次 1K 为 1120、2K 为 1680、4K 为 3780。thoughtsTokenCount 是思考 token 数,填 thinkingLevel: "minimal" 时不出现。
费用以便利店当前分组配置和用量明细为准:图片按张计费,提示词、参考图和思考、文字输出按用量计费。

错误响应

出错时 HTTP 状态码不是 2xx,响应体是 JSON,都带 error.message(错误说明)。其余字段因出错环节不同而不同:有的 code 是数字、有的是字符串,有的带 status、有的带 type。判断成败请看 HTTP 状态码,向用户展示原因请读 error.message。下表为 2026-10-08 实测: aspectRatio: "5:3" 的完整响应体:

Python 生成并保存图片

这段完整代码已用 requests==2.32.5 真实执行,返回并保存一张 1376×768 JPEG 到 generated-1.jpg。

使用 Google GenAI SDK

谷歌官方 Python SDK 只需把地址改为便利店,并填便利店 Key。官方工具包从 google-genai 1.49.0 起才有 image_size 参数,1.47.0 实测会报错。这段代码已用 google-genai==2.28.0(需要 Python 3.10 及以上)真实执行,保存一张 2752×1536 JPEG 到 nano-banana-1.jpg。
HttpOptions 的 timeout 单位是毫秒。SDK 会自动使用 x-goog-api-key 鉴权并请求 /v1beta/models/...:generateContent。 成功处理应检查 HTTP 状态、响应是否含 error,并确认 parts 里有可解码的图片。错误响应的格式见上方错误响应。