Gemini Image 国内使用教程：从 API 申请到图片生成完整指南（2026）

截至 2026 年 10 月 8 日，用 API 生成 Gemini 图片，新项目直接调 gemini-nano-banana-2.1（Nano Banana 2.1，10 月 6 日正式发布）。Google 官方按 token 计费，1K 图约 $0.0336 一张，API 没有免费层；中国大陆不在 Gemini API 的可用地区内，国内团队可以经老张API 这类第三方服务调用，2.1 每次 $0.045，不分尺寸。3 月时常见的 gemini-3.1-flash-image-preview、imagen-4.0-fast-generate-001 等 ID 已在 Google 停用，旧代码要先改模型 ID。

现在调哪个模型：新项目用 gemini-nano-banana-2.1

Google 在 2026 年 10 月 6 日发布了 Nano Banana 2.1，模型页标为正式版（Stable）。它是 Nano Banana 2 的更新版，Google 的图片生成指南写明所有新项目都建议用 2.1，同一天 Nano Banana 2（gemini-3.1-flash-image）在 Gemini API 上被标为弃用，但没有公布停用日期（Gemini API 更新日志）。

2.1 的主要规格：

• 输出尺寸 1K、2K、4K 三档，没有 Nano Banana 2 的 0.5K（512）档。
• 14 种宽高比，包括新增的 1:4、4:1、1:8、8:1 长图比例。
• 最多 14 张参考图，其中物体图最多 10 张、人物图最多 4 张。
• 可以开启使用 Google 搜索建立依据（网页搜索和图片搜索）。
• 思考等级 minimal、medium（默认）、high。

什么时候不用 2.1：图里的文字必须一字不差时考虑 Nano Banana Pro（gemini-3-pro-image）；只要 1K、追求最低单价时考虑 Nano Banana 2 Lite（gemini-3.1-flash-lite-image）；必须输出 512 像素预览图时才留在 Nano Banana 2。选型依据见后面的「选哪个模型」一节。

Gemini 图片模型 ID、状态与每张价格（2026 年 10 月）

下表的官方价格是 Gemini API 标准档按输出 token 折算的每张价格，Vertex AI 上的标价相同（Gemini API 价格页）；老张API 一列是按次价格（老张API Nano Banana 文档），均截至 2026 年 10 月 8 日。

说明：laozhang.ai 是我们自己的服务，其价格是平台报价，不是独立比较的结论。

读这张表要注意三点：

• 官方价格只算图片输出。Google 另按 token 收输入和思考费用，2.1 是输入每百万 token $1.50、文本与思考每百万 token $7.50，所以实际单张会比表里略高，后面「每张多少钱」一节有实测 token 的折算。
• Batch 批量接口官方价减半，2.1 的 1K、2K、4K 分别是 $0.0168、$0.0252、$0.0567，但结果不是实时返回。
• Gemini API 的图片模型都没有免费层，价格页免费层一栏写的是 Not available。想先免费试，可以在 Gemini 应用里用 Nano Banana 2（免费），2.1 在 Gemini 应用里要 Google AI 付费方案。免费额度的细节见 Gemini 图片生成 API 免费吗：已无免费层，最低每张 $0.0336。

已停用和已弃用的旧模型 ID：3 月版代码要改什么

「弃用」和「停用」不是一回事：弃用（deprecated）是 Google 宣布不再推荐、建议迁移，模型暂时还能调用；停用（shut down）之后，请求这个 ID 会直接失败。下表是 Gemini API 弃用页上与图片生成有关的旧 ID（Gemini API 弃用模型列表，截至 2026 年 10 月 8 日）：

gemini-2.5-flash-image 的停用日期要单独说明：弃用页写的是 2027 年 3 月 15 日，价格页上却还挂着「将于 2026 年 10 月 2 日停用」的旧提示。两处都是 Google 自己的页面，无法判断哪处会被执行，还在用它的项目应尽快迁移，不要指望它撑到 2027 年。

Nano Banana 2.1 上线当天（10 月 6 日），Google 曾给 Nano Banana 2 列出 2026 年 10 月 29 日的停用日期，到 10 月 7 日已撤下，现在的正式说法是「未公布停用日期」。所以 gemini-3.1-flash-image 目前仍可调用，只是不再是推荐模型。

Vertex AI（Google 现在称为 Gemini Enterprise Agent Platform）的生命周期与 Gemini API 分开计算：Vertex 上 gemini-3.1-flash-image 和 gemini-3-pro-image 的退役时间是「2027 年 5 月 28 日或之后」，gemini-2.5-flash-image 是 2027 年 3 月 15 日（Vertex AI 模型版本与生命周期）。同一个 ID 在两个平台上的日期不能混用。

照 3 月版教程写的代码，最少要改两处：把 gemini-3.1-flash-image-preview 换成 gemini-nano-banana-2.1；如果原来在 imageSize 里写了 0.5K 或 512，改成 1K。第三方服务是否还接受旧 ID 以各自文档为准，老张API 文档列出的 5 个 Nano Banana 模型 ID 里没有任何带 -preview 后缀的。

国内为什么调不通 Gemini 图片生成 API

问题出在 Google 这一侧的两道限制，跟代码写法无关：

1. 地区：Gemini API 和 Google AI Studio 只在 Google 列出的可用地区开放，中国大陆不在列表里。API Key 的创建和计费账号都要在受支持地区完成。
2. 网络：Gemini API 的服务地址 generativelanguage.googleapis.com 在中国大陆无法直接访问，部署在国内的服务器发出的请求到不了 Google。

因此可行的路线只有两条。公司在受支持地区有主体和服务器、能开通 Google Cloud 计费账号的，直接用 Gemini API 或 Vertex AI，按官方价格结算，还能用 Batch 半价；没有这些条件、服务又要跑在国内的，用老张API 这类第三方 API 服务，它提供与 Google 原生格式一致的接口，按次计费。

老张API 走的是同一批 Google 模型 ID，请求体和返回结构与 Gemini 原生 generateContent 一致。2026 年 10 月 8 日经老张API 调用 2.1 的 8 次请求中，2K 16:9 输出 2752×1536、4K 16:9 输出 5504×3072，与 Google 公布的 2.1 尺寸表一致。

用老张API 生成第一张 Gemini 图片：3 步

下面两段 Python 代码据老张API 的 Nano Banana 2.1 文档整理（删去了命令行参数，提示词换成中文），这几段代码没有实际运行过。同一接口在 2026 年 10 月 8 日的 8 次调用结果见后文「每张多少钱」一节。

说明：laozhang.ai 是我们自己的服务，其价格是平台报价，不是独立比较的结论。

第一步：创建 API Key。 在老张API 的令牌管理页面新建令牌，分组选 default，计费模式选「按量优先」（推荐）或「按次计费」。计费模式是「按量计费」的令牌调不了 Nano Banana 2.1 这类按次计费的模型。

第二步：设置环境变量并安装依赖。

export LAOZHANG_API_KEY="sk-..."  # 换成你的老张API 令牌
python -m pip install requests openai

第三步：用 Gemini 原生接口生成图片。 原生接口能设置宽高比和尺寸，是首选写法。保存为 nb21.py 后运行 python nb21.py：

# 据老张API「Nano Banana 2.1」文档示例整理，未实际运行
import base64
import os
import sys
from pathlib import Path

import requests

URL = "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent"
EXTENSIONS = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}

body = {
    "contents": [{
        "role": "user",
        "parts": [{"text": "雨后黄昏的街角咖啡馆，湿漉漉的路面映着暖色灯光，霓虹招牌上写着 BANANA CAFE"}],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},  # 尺寸只能是 1K、2K、4K
    },
}

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json=body,
    timeout=300,
)
if response.status_code != 200:
    sys.exit(f"HTTP {response.status_code}: {response.text[:500]}")

result = response.json()
images = [
    part["inlineData"]
    for candidate in result.get("candidates") or []
    for part in (candidate.get("content") or {}).get("parts") or []
    if "inlineData" in part and not part.get("thought")
]
if not images:
    reasons = [candidate.get("finishReason") for candidate in result.get("candidates") or []]
    sys.exit(f"没有返回图片：{result.get('promptFeedback') or reasons}")

for number, image in enumerate(images, start=1):
    output = Path(f"nb21-cafe-{number}.{EXTENSIONS.get(image['mimeType'], 'bin')}")
    output.write_bytes(base64.b64decode(image["data"]))
    print("已保存", output)

图片以 Base64 放在 candidates[0].content.parts[].inlineData.data 里，格式看 mimeType，不要默认当成 PNG；10 月 8 日的 8 次调用在没有指定格式时返回的都是 JPEG。带 "thought": true 的部分是思考过程中的草图，代码已跳过。一次请求通常要 15 到 40 秒，4K 更久，所以超时设成 300 秒，前面如果有网关或代理，也要留出同样的时间。

已经在用 OpenAI SDK：改 base_url 即可，但只能出 1K

老张API 也提供 OpenAI 兼容的 Chat Completions 接口。把 base_url 指向 https://api.laozhang.ai/v1、model 写成 gemini-nano-banana-2.1 就能出图，但这条路不能设宽高比和尺寸：返回 1K 图，画幅由模型根据提示词决定，常常是 16:9。需要固定比例或 2K、4K 时用上面的原生接口。

# 据老张API「Nano Banana 2.1」文档示例整理，未实际运行
import base64
import os
import re

from openai import OpenAI

# max_retries=0：超时后自动重试可能让同一张图生成并扣费两次
client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=300,
    max_retries=0,
)
reply = client.chat.completions.create(
    model="gemini-nano-banana-2.1",
    messages=[{"role": "user", "content": "俯拍木桌上的一杯拿铁，奶泡拉花是一只猫"}],
)
text = reply.choices[0].message.content or ""

found = re.findall(r"data:image/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)", text)
if not found:
    raise SystemExit(f"没有返回图片：{text[:300]}")
kind, encoded = found[0]
with open(f"latte.{'jpg' if kind.startswith('jp') else kind}", "wb") as f:
    f.write(base64.b64decode(encoded + "=" * (-len(encoded) % 4)))

图片是 message.content 里的一段 Base64 data URL，通常包在 Markdown 图片语法里，所以用正则取出。3 月版教程里遍历 message.content 找 image_url 的写法拿不到这段文本，要换成上面的方式。

尺寸、比例、思考等级、参考图：generationConfig 怎么写

这些设置都只在 Gemini 原生接口上生效，写在 generationConfig 里。

宽高比与尺寸。 imageConfig.aspectRatio 可选 1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9；不写时由模型按提示词选。imageConfig.imageSize 只接受大写 K 的 1K、2K、4K。1:1 对应 1024×1024、2048×2048、4096×4096，16:9 的 1K 是 1376×768、2K 是 2752×1536。

不要给 2.1 传 512：10 月 7 日这样的请求还返回 HTTP 400 且不扣费，但 2026 年 10 月 8 日的两次实测里，512 都返回了一张 1024×1024 的图，并按 $0.045 扣费。接口行为在 10 月 7 日到 8 日之间变过，传了也拿不到 512 像素的图，只会多付一次钱。

思考等级。 在 generationConfig 里加 "thinkingConfig": {"thinkingLevel": "minimal"}，可选 minimal、medium（默认）、high。Nano Banana 2 默认是 minimal，从 2 迁移过来的代码不写这个参数，就会变成 medium。等级越高，排版和文字上花的功夫越多、耗时越长；10 月 8 日同一提示词的 2K 测试中，high 用了 34.8 秒，minimal 用了 24.7 秒（各测 1 次）。老张API 不论等级都是每次 $0.045，Google 官方则把思考 token 另行计费。

改图和多图合成。 在 parts 里先放文字指令，再按顺序放参考图，每张图是一个 inlineData：

# 据老张API「Nano Banana 2.1」文档示例整理，未实际运行；接在上面 nb21.py 的 body 定义之后
product = base64.b64encode(Path("product.png").read_bytes()).decode("ascii")
scene = base64.b64encode(Path("scene.jpg").read_bytes()).decode("ascii")
body["contents"][0]["parts"] = [
    {"text": "把第一张图里的商品放到第二张图的桌子上，光线与场景一致，商品标签保持清晰"},
    {"inlineData": {"mimeType": "image/png", "data": product}},
    {"inlineData": {"mimeType": "image/jpeg", "data": scene}},
]

提示词里用「第一张图」「第二张图」指代参考图，mimeType 要和文件真实格式一致。2.1 最多接受 14 张参考图（物体图最多 10 张、人物图最多 4 张）。需要精确控制时，写清哪些地方不能变，每次只改一处。

使用 Google 搜索建立依据。 图里要画真实地标或最新信息时，在请求顶层加 "tools": [{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}]。Google 官方每月有 5,000 次免费搜索（所有 Gemini 3.x 模型共用），之后每 1,000 次 $14；老张API 每次搜索加收 $0.014，一次请求搜了 2 次就是 $0.045 + 2 × $0.014 = $0.073。

Vertex AI 上的限制。 在 Vertex AI 调 2.1 时，区域要用 global；seed、topK、logprobs、temperature、topP 这几个参数会直接报错，2.1 也不支持 Flex 档（Vertex AI 的 Nano Banana 2.1 文档）。

每张多少钱：官方按 token 计费，老张API 每次 $0.045

官方价格表里的 $0.0336 只是 1K 图片输出的部分。2026 年 10 月 8 日经老张API 调 2.1 的 8 次请求，返回的用量里每次都带有思考 token（510 到 1,107 个）。按 Google 标准档单价（输入每百万 token $1.50，文本与思考 $7.50，图片 $30）折算：

以 1K 为例：1,120 × $30 ÷ 1,000,000 = $0.0336，(394 + 854) × $7.50 ÷ 1,000,000 ≈ $0.0094，输入 42 个 token 不到 $0.0001，合计约 $0.043。这个折算假设老张API 原样转发了 Google 返回的用量数据，没有拿 Google 账单核对过；每个设置只测了 1 次。

由此可以得出一条简单的选择规则：

• 只出 1K 图：两边价格接近。能直连 Google、又不需要实时返回时，Batch 的 1K 只要 $0.0168，比任何按次价格都低。
• 常出 2K、4K：老张API 的固定 $0.045 明显更省，4K 约是官方折算价的 38%（$0.045 ÷ $0.119）。
• 大批量 1K、对画质要求不高：老张API 的 Nano Banana 2 Lite 是每次 $0.025。

老张API 的计费规则还有两条要知道：HTTP 200 但没有图片的响应（例如提示词没要求出图、或被安全检查拦下）也按一次计费；客户端超时的请求也可能已经扣费，重发前先看调用日志。

选哪个模型：2.1、Pro、Lite 和 Nano Banana 2 各自什么时候用

Nano Banana 2 已被 2.1 取代，Imagen 4 已停用，按下面的规则选：

• 默认选 Nano Banana 2.1（gemini-nano-banana-2.1）。官方 1K、2K 都比 Nano Banana 2 便宜一半，Google 的模型卡（自家评测）称它在整体偏好、编辑和多角色一致性上都胜过 Nano Banana 2 和 Pro。Arena 文生图榜 10 月 6 日的更新里，2.1 暂列第 5（初步排名），Nano Banana 2 第 11、Lite 第 15。
• 图里文字必须准确时选 Nano Banana Pro（gemini-3-pro-image）。2026 年 10 月 8 日的 9 组同题测试（1K，每题生成 1 次）中，Pro 和 GPT Image 2.5 都保留了要求的文字，2.1 在 3 道文字题里改了措辞；三个模型都把「单」写成了日文字形「単」。完整结果见 Nano Banana 2.1 vs Pro vs GPT Image 2.5 对比：9 组同题实测。
• 只要 1K、量大选 Nano Banana 2 Lite（gemini-3.1-flash-lite-image）。官方 1K 输出价与 2.1 相同，但输入和思考单价低得多（输入每百万 token $0.25、思考 $1.50）；老张API 每次 $0.025。
• 只有需要 512 像素输出时才留在 Nano Banana 2（gemini-3.1-flash-image）。它已弃用，官方 1K 价是 2.1 的两倍，老张API 上每次 $0.055，也比 2.1 贵。迁移只需改模型 ID，请求和返回结构不变。
• 不再新接初代 Nano Banana（gemini-2.5-flash-image）。老张API 上它每次只要 $0.02，但它已弃用，停用日期又互相矛盾，新项目不值得为它写代码。

2.1 与 Nano Banana 2 在官方 1K、2K、4K 上各便宜多少，见 Nano Banana 2.1 价格与入口：1K/2K 比 NB2 便宜一半，4K 只省 25%；还在用 Nano Banana 2 的项目，价格细节见 Nano Banana 2 API 价格：每张 $0.045–$0.151，已弃用，2.1 更便宜。

安全拦截、空图和 429：调不出图时先查什么

返回 200 却没有图片。 先看 finishReason 和 promptFeedback，上面的代码在没取到图时会把它们打印出来。常见原因有两个：提示词只描述了画面，没有明确要求「生成一张图」或「返回修改后的图」，模型可能只回文字；或者内容被 Google 的安全过滤拦下，这时通常只返回一句文字拒绝，没有错误码。IMAGE_SAFETY 表示生成的图被判定违反安全规则，换更中性的描述再试；服装、商品类图片可以先描述商品本身，再描述人物。Google 的安全设置分两类：骚扰、仇恨言论、色情、危险内容这四类可以在 safetySettings 里调阈值；针对儿童安全等核心危害的保护始终生效，不能调整。blockReason: OTHER 在 Google 的 API 参考里只写了「原因未知」，没有对应的可调设置。

容易被拦的内容。 老张API 文档列出的常见触发项包括：色情、暴力、血腥、仇恨内容（含擦边内容）；要求去除图片水印；迪士尼、漫威、任天堂等知名版权角色；涉及未成年人的不当内容；名人、政治人物等公众人物；修改订单截图、收据、价签等金额信息；给真人换装或换脸。同样的内容重发通常还会被拦，而且每次都按一次计费，应先改提示词或参考图。另外，Nano Banana 生成的每张图都带有 Google 的 SynthID 隐形水印。

HTTP 400。 多半是参数不对：宽高比不在 14 种之内（如 7:3），或用了已停用的模型 ID。错误信息可能为空，先对照上文的比例表和 ID 表。

HTTP 429 和 5xx。 用指数退避重试；按老张API 文档，生成开始前就被 429 或 503 拒绝的请求通常不扣费。用 OpenAI SDK 时把 max_retries 设成 0、自己控制重试，避免超时后 SDK 自动重发导致同一张图扣两次钱。

Gemini 图片 API 常见问题：免费额度、国内申请与旧模型 ID

问：Gemini 图片生成 API 有免费额度吗？

没有。截至 2026 年 10 月 8 日，Gemini API 价格页上所有图片模型的免费层都是 Not available，调用就要开通计费。免费出图只剩 Gemini 应用：免费用户用的是 Nano Banana 2，2.1 需要 Google AI Pro、Plus 或 Ultra 方案，Google 没有公布各方案的每日张数。

问：在国内能直接申请 Gemini API Key 吗？

不能。中国大陆不在 Gemini API 的可用地区内，国内网络也无法直接访问 Google 的 API 地址。有海外主体和服务器的团队可以用官方 Gemini API 或 Vertex AI；服务跑在国内的，用老张API 这类第三方服务，令牌在其控制台创建。

问：3 月版教程里的 gemini-3.1-flash-image-preview 还能用吗？

在 Google 的 Gemini API 上不能，这个 ID 已于 2026 年 6 月 25 日停用。改成 gemini-nano-banana-2.1；如果原代码设了 0.5K 或 512 尺寸，同时改成 1K。

问：Nano Banana 2 是不是 10 月 29 日停用？

不是。Google 在 10 月 6 日短暂列出过 10 月 29 日，到 10 月 7 日已经撤下。截至 2026 年 10 月 8 日，gemini-3.1-flash-image 在 Gemini API 上的状态是「已弃用，未公布停用日期」，在 Vertex AI 上是「2027 年 5 月 28 日或之后」退役。

问：经老张API 调用和直接调 Google 出的图一样吗？

模型 ID 相同，请求和返回结构与 Gemini 原生接口一致，2026 年 10 月 8 日实测的输出尺寸与 Google 公布的一致。区别在计费：Google 按 token 计费、尺寸越大越贵，Batch 能减半；老张API 按次固定价格，2.1 每次 $0.045，不分尺寸和思考等级。

问：不写代码，只想在网页里用 Gemini 生成图片怎么办？

用 Gemini 应用或 Google 的其他入口即可，不需要 API。各入口的区别和额度见 Gemini 图片生成教程：入口、模型、额度与 API 调用。