Nano Banana Pro API 和在 Gemini 应用里用的是同一个模型，只是入口从表单换成了 HTTP。整件事的价值就在这一句：编辑器变成了流水线里的一个环节。
第一个小时里最容易卡住的是两件事。model id 猜不出来，返回体里装的也不是链接，而是图像字节。
Nano Banana Pro API 能做什么
人在界面里能做的事，脚本都能批量做：按提示词生成、对已有图片做编辑、在一批任务里让参考图保持一致。官方公告里写的是多语言文字渲染、1K/2K/4K 输出，以及单次构图最多 14 张输入图，具体数量随使用界面不同。
如果还没用过这个模型，先读怎么用 Nano Banana Pro。写提示词的习惯可以直接搬过来，而从队列里发出去的坏提示词，依然是坏提示词。
API 还顺带解决了可追溯问题：提示词、参数和产出都在同一条请求记录里。
拿到 API key 与选 model id
key 放在哪里
key 在 Google 面向 Gemini API 的开发者控制台里签发，不是从任何第三方封装里拿。拿到之后放进环境变量，不要写进代码——提交进仓库的 key 就是一把必须轮换的 key。下面两条请求都从环境变量读。
model id 该从哪里拿
这里必须说实话。我们核对这篇文章的日期是 2026-09-13，当天官方那页图像生成 API 文档没能打开，所以我们不会把某个 model id 当成已确认的字符串印出来。第三方笔记里流传的那个预览版写法，照抄成事实比不写还糟——id 写错，第一条请求就是 400。
所以下面的示例都从环境变量取 id。你从官方模型列表里复制当前字符串，导出到环境变量，之后 id 变了代码也不用改。
第一次请求：curl 示例
先用最小的一条请求把链路跑通：一个文本 part，一个图像模态，别的都不要。记得先在 shell 里设好 GEMINI_API_KEY 和 GEMINI_IMAGE_MODEL。
curl -s "https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_IMAGE_MODEL}:generateContent" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{ "text": "A ceramic mug on a matte grey studio surface, soft key light from the upper left, 85mm product photography, no text, no watermark." }
]
}
],
"generationConfig": { "responseModalities": ["IMAGE"] }
}' > out.json有三处要先看清楚。key 走请求头而不是 URL，这样它不会留在 shell 历史和代理日志里。提示词放在 parts 数组里，后面参考图也是放这里。返回体落盘成文件，因为图像不会以链接的形式回来，浏览器打不开。
读这个文件要用 JSON 解析器，别用眼睛——base64 很长。返回结构里，图像挂在第一个 candidate 的某个 part 上，带媒体类型和一段 base64；被拒或说明类的信息则以文本 part 的形式出现在同一个数组里。遍历 parts，留下带内联图像数据的那些，解码，写盘。在往上叠业务之前，请拿官方 API 参考核对一次字段名，因为那页我们没能核对。
用参考图生成：Python 示例
多图输入才是 API 真正值钱的地方。官方公告允许单次构图最多 14 张参考图，而每一张都要说明自己的角色，否则模型只能猜它在模仿哪一张。
import base64
import json
import os
import pathlib
import urllib.request
api_key = os.environ["GEMINI_API_KEY"]
model_id = os.environ["GEMINI_IMAGE_MODEL"]
url = f"https://generativelanguage.googleapis.com/v1beta/models/{model_id}:generateContent"
def inline_image(path: str) -> dict:
data = pathlib.Path(path).read_bytes()
return {
"inlineData": {
"mimeType": "image/png",
"data": base64.b64encode(data).decode("ascii"),
}
}
body = {
"contents": [
{
"parts": [
{
"text": (
"Reference 1 is the product: keep the object, its proportions "
"and its glaze unchanged. Reference 2 is the background style "
"only, do not copy its subject. Place the product on a light oak "
"surface with morning light from a window on the right."
)
},
inline_image("product.png"),
inline_image("background.png"),
]
}
]
}
request = urllib.request.Request(
url,
data=json.dumps(body).encode("utf-8"),
headers={"x-goog-api-key": api_key, "Content-Type": "application/json"},
)
with urllib.request.urlopen(request) as response:
payload = json.load(response)
for part in payload["candidates"][0]["content"]["parts"]:
if "inlineData" in part:
pathlib.Path("out.png").write_bytes(
base64.b64decode(part["inlineData"]["data"])
)这段代码里真正承重的是提示词。每张参考图都标了用途，物体被点名为固定，这才是一批图之间不漂移的原因。只改一处时，传一张参考图，然后只描述那处改动。
两个习惯能让它活到生产环境。第一，遇到没有内联图像的 candidate，把整个返回体记进日志，原因通常在文本 part 里。第二，把 model id 当配置而不是常量，这样改名只是改环境变量，不是发一次版本。
计费与配额：哪些是官方公布的
官方公布、而且对排期有用的部分是：1K/2K/4K 输出档位、单次构图最多 14 张输入图、单个流程里最多 5 个人物与 14 个物体的保持一致，以及输出带 SynthID 水印。这些是容量数字，用来估算一批任务要跑多久。
我们核对过的来源里没有公布的是：单张价格、免费额度、速率限制。本文对这三项都不给数字，因为 Google 尚未在本文列出的页面上公布它们；从聚合站抄来的数字，是那家网站对自己服务的报价。定预算之前，请自己看官方 Gemini API 定价页。
如果你是在几个模型之间做选型，可以看这份与 GPT Image 的对比，它按任务类型给结论。
常见错误与排查
第一条请求就 400，几乎都是 model id 或请求体的问题。先拿 id 去官方列表核对，再去看别的地方——你从博客里抄来的示例，可能带着一个已经过期的字符串。
返回里有文字却没有图像，通常不是程序 bug，而是内容判定。先读文本 part 再决定要不要重试，不要拿同一句提示词反复撞。
base64 解码失败，多半是你正在解码一个文本 part。要按内联数据字段过滤，而不是直接取数组里的第一个元素。
429 说明你发得比配额允许的更快。既然公开的限制我们这里拿不到，唯一的办法是测量：把每条响应记下来，找到能跑通的那条速率线，然后停在它下面。
不要把 key 放进前端代码。浏览器能看到的 key，就是一把公开的 key。
常见问题
API 和 Gemini 应用要用两个账号吗？ key 是在面向 Gemini API 的开发者控制台里签发的。你现有的方案是否覆盖 API 用量，属于计费问题，我们无法从公开来源回答，请以官方定价页为准。
能在同一条请求里既传参考图又传提示词吗？ 能，而且这就是编辑任务的常规写法。文本 part 放前面，写清哪些不能变，并给每张图标注角色。
怎么让角色在多条请求之间保持一致？ 每次都传同一张已经确认过的参考图，把身份描述原样重复，不要改写。完整流程写在 Nano Banana Pro 使用教程里。
图像在返回体里的哪里？ 在第一个 candidate 的某个 part 上，以 base64 内联返回。要自己解码落盘，因为没有可长期保存的链接。
先把一条请求接上，把整个返回体记下来，把 model id 留在配置里。这三件事做完，就足以判断 API 适不适合你的流水线。