Nano Banana Pro 报错排查：429、503、IMAGE_SAFETY 该不该重试

Nano Banana Pro（模型 ID gemini-3-pro-image）报错时，先看两样东西：HTTP 状态码，以及错误体里的状态名或错误码。429、500、503、504 是暂时性错误，用指数退避加随机抖动、设上限地重试；400、401、402、403、404 是请求、密钥、余额或模型 ID 的问题，重试多少次都不会成功，要改了再发。HTTP 200 却没有图片时，问题在响应字段：finishReason 是 IMAGE_SAFETY 要改提示词，是 SAFETY 才能看 safetyRatings 调阈值。下面按错误码给出含义、该不该重试和修法，内容截至 2026 年 10 月 8 日。

2026 年 10 月 8 日更新：免费层 RPM、旧模型 ID 和重试建议已改

下面几条旧说法已经不成立，如果你按旧版排查过，请逐条对照：

• 图片模型没有免费层。Gemini API 定价页上 Nano Banana Pro、Nano Banana 2、Nano Banana 2.1 和 Lite 的免费层一栏都是“不可用”。旧版里的“免费层 15 RPM”和按 Google AI Pro、Ultra 订阅给出的 RPM 都删掉了：Google 没有公布按层级的图片 RPM 表，实时限额只能在 AI Studio 里看，订阅也不增加 API 配额。
• 错误码按接口区分。Google 的 API 错误页列的是 Interactions API 的错误码（authentication、payment_required、model_not_found 等），经典的 generateContent 接口返回的是 INVALID_ARGUMENT、RESOURCE_EXHAUSTED 这类状态名。旧表把“API key not valid”写成 403，实际在 generateContent 上是 400。
• SDK 默认不一定会重试。Google 排错页说 Python SDK 默认自动重试，但 google-genai 的 generate_content 在默认客户端上只发一次请求；要重试得自己写循环或配置 HttpRetryOptions。
• 预览版模型 ID 已停用。gemini-3-pro-image-preview 和 gemini-3.1-flash-image-preview 已于 2026 年 6 月 25 日在 Gemini API 停用，继续用会返回 404。
• 备用模型换成 Nano Banana 2.1。gemini-nano-banana-2.1 已于 2026 年 10 月 6 日正式发布，是 Google 现在推荐的 Flash 档图片模型；Nano Banana 2（gemini-3.1-flash-image）在 Gemini API 已弃用，暂无停用日期。旧版写的“gemini-2.5-flash-image 已于 2026 年 10 月 2 日下线”不能当事实，Google 两个页面给的日期互相矛盾，见下文 404 一节。
• 新增 402：Prepay 余额用完时返回 402，不要重试。

先看报错来自哪个接口：Interactions API 和 generateContent 的错误码不同

同一个问题在两个接口上的写法不一样，查文档前先确认你的请求走的是哪一个：

• 经典 generateContent 接口（REST 路径以 :generateContent 结尾，google-genai 的 client.models.generate_content、多数第三方工具和 ComfyUI 节点都走它）：错误体是 {"error": {"code": 429, "message": "...", "status": "RESOURCE_EXHAUSTED"}}，code 是 HTTP 数字，status 是全大写的状态名。
• Interactions API（client.interactions.create）：错误体是 {"error": {"code": "quota_exceeded", "message": "..."}}，code 是小写加下划线的字符串，HTTP 状态码另外设置。流式请求的错误会作为 event_type 为 "error" 的事件出现在流里。

Gemini API 错误码文档（2026 年 9 月 20 日更新）列的是 Interactions API 的错误码。在 generateContent 上，同类问题以 Google API 通用的状态名返回，例如无效密钥是 400 INVALID_ARGUMENT（错误信息 API key not valid），限流是 429 RESOURCE_EXHAUSTED，过载是 503 UNAVAILABLE。2026 年 10 月 8 日用无效密钥请求 generateContent，返回的正是 400 和 API key not valid，而不是 401。

Nano Banana Pro 错误码速查：含义、能不能重试、怎么修

下表把两个接口的写法放在同一行。“重试”一栏依据 Gemini API 排错指南（2026 年 10 月 1 日更新）：只重试 429、408 和 5xx，不重试 400、402、403。

判断规则可以压成三句：4xx 先改请求、密钥或账户，再发；5xx 和 429 退避后有限次重试；200 没图先读 finishReason 和 promptFeedback.blockReason，不要把它当成功。更细的分步排查见 Nano Banana Pro 故障排除：每个错误代码的解决方案，较少见的错误码见 Nano Banana Pro 错误代码排错指南。

429 RESOURCE_EXHAUSTED：每分钟、每日还是 10 分钟花费上限

429 先分清撞的是哪一种上限，因为只有每分钟这一类等一会儿就能恢复。在 Interactions API 上错误码直接告诉你：rate_limit_exceeded 是每分钟或每秒的请求数、Token 数超限，too_many_requests 是短时间内请求太多，这两种按指数退避重试；quota_exceeded 是每日配额用完，要等重置或申请提额，退避重试没有用。在 generateContent 上三者都是 RESOURCE_EXHAUSTED，要读错误信息里的配额名称判断。

Gemini API 速率限制文档（2026 年 9 月 2 日更新）里和排查有关的规则：

• 限额按项目计算，不按 API 密钥。同一项目下多建几个 key 不会多出额度，旧版“把请求分散到多个 API 密钥”的建议不成立。
• 每日请求数（RPD）在太平洋时间午夜重置。
• 实时的 RPM、TPM 和 IPM 只在 AI Studio 里显示。IPM（每分钟图片数）只对图片模型计算。Google 没有公布各层级的图片 RPM 表，网上的数字请以你项目在 AI Studio 里的显示为准。
• 按花费的限速以滚动 10 分钟计：Tier 1 为 $10，Tier 2 为 $50，Tier 3 为 $200，是否对你的账户生效取决于结算历史，超出同样返回 429 RESOURCE_EXHAUSTED。按 Nano Banana Pro 标准价算，Tier 1 每 10 分钟大约能出 $10 ÷ $0.134 ≈ 74 张 1K 或 2K 图、$10 ÷ $0.24 ≈ 41 张 4K 图；思考 Token 另外计费，实际张数会少一些。
• 层级由结算账户的累计消费决定：Tier 1 是关联有效结算账户，Tier 2 是累计付款 $100 且首次付款满 3 天，Tier 3 是累计 $1,000 且满 30 天。

图片模型没有免费层。没有关联结算账户的项目调用 Nano Banana Pro 拿不到图，这时升级到 Tier 1 才是修法，而不是退避重试。原因判断、恢复代码和每种 429 的处理步骤，见 Nano Banana Pro RESOURCE_EXHAUSTED 429：排查与 Python、Node.js 恢复代码 和 Gemini 图片生成 429 速率限制：先分清每分钟、每日和花费上限；要提额，看 Nano Banana Pro API 配额提升：Tier 1 到 Tier 3 各能出多少张图。

还有一种上限不是按分钟算的。Gemini API 结算文档（2026 年 9 月 28 日更新）规定了每个结算账户的月度花费上限：Tier 1 为 $250，Tier 2 为 $2,000，Tier 3 为 $20,000 到 $100,000 以上。所有关联项目的花费累计到上限后，服务会暂停到下个月 1 日。你也可以在 AI Studio 的 Spend 页面给单个项目设月度上限，这项功能还在实验阶段，计费数据有约 10 分钟延迟，可能略微超出。

503、500、504：Google 侧的暂时性错误怎么重试

5xx 说明请求本身没问题，问题出在 Google 一侧。Google 排错指南给的做法是：只对 429、408 和 5xx 重试，第一次等约 1 秒，之后按 2、4、8 秒指数递增，加随机抖动，设最多重试次数，避免死循环。

503 UNAVAILABLE（Interactions API 为 service_unavailable）表示模型暂时过载或不可用，繁忙时段最常见。Google 没有公布 503 的出现比例，也没有公布恢复所需时间，别处给出的百分比和分钟数只能当经验。过载按模型区分，Pro 忙时，Flash 档模型可能仍然可用，但没有保证。需要立即出图时，可以在出现两次 503 后换到 gemini-nano-banana-2.1：它是 Google 现在推荐的 Flash 档模型，官方单价 1K 每张 $0.0336。代价是文字准确度，在 2026 年 10 月 8 日的 9 组同题测试里（1K，每题一张），2.1 在 3 道文字题里改了要求的字，Pro 没有，详见 Nano Banana 2.1 vs Pro vs GPT Image 2.5 对比：9 组同题实测。海报、菜单这类文字必须一字不差的任务，宁可排队等 Pro。

500 INTERNAL（Interactions API 为 api_error）是单个请求在服务端意外失败，同样的请求下一次可能就成功。Google 的建议是重试，持续出现再联系支持。502 Bad Gateway 不在 Google 的错误码列表里，按 5xx 的同一规则处理即可。

504 DEADLINE_EXCEEDED 表示请求没在截止时间内完成。Google 的建议是去掉客户端的截止时间设置，或者调大它，让服务器默认值生效。4K 出图和带多张参考图的请求更耗时，客户端超时设得太短会把本来能成功的请求截断。

多次 500 或 503 时，先看服务状态：Gemini API 和 AI Studio 用户看 Google AI Studio 状态页，Vertex AI 用户看 Google Cloud Service Health。怎么判断是全局故障还是只有你受影响，见 Nano Banana 2 宕机了吗？先查入口，再判断 429、503。如果报错出现在打开第三方工具返回的图片链接时，那是链接有效期的问题，不是 API 错误，见 Nano Banana 临时图片与 Bug 修复。

Python SDK 会不会自动重试：generate_content 默认不会

Google 排错指南写着 Python SDK 默认会对超时、429 和 5xx 自动重试最多四次。这句话只对一部分调用成立：

• client.models.generate_content：在默认客户端上不重试。2026 年 10 月 5 日用 google-genai 2.28.0 对一个只返回 429 的模拟服务测试，默认客户端只发了 1 次请求就抛错；2.29.0 的源码也一样，没设置 retry_options 时只尝试一次。
• client.interactions.create：默认会重试，同一测试里共发了 4 次请求。

所以用 generate_content 时，要么像下一节那样自己写重试循环，要么在客户端上打开 SDK 的重试：

from google import genai
from google.genai import types

client = genai.Client(
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(attempts=5)  # 含首次请求，共 5 次
    )
)

HttpRetryOptions 默认重试 408、429、500、502、503、504，初始等待 1 秒、最长 60 秒。两种办法选一种，不要同时开 SDK 重试又在外面套一层循环，那样一次失败最多会变成 25 次请求，429 也会拖得更久。

400、401、402、403：改请求、密钥或余额，不要重试

这一组错误重试不会自己好，每次重试还会占用速率额度。

400 INVALID_ARGUMENT 是请求本身有问题，错误信息一般会点名哪个字段。常见原因：

• 输入超限。Nano Banana Pro 的输入上限是 65,536 个 Token，多轮改图时整段对话历史都算在内，所以当前这句提示词很短也可能超限。按 Gemini API 文件输入文档（2026 年 10 月 7 日更新），内联数据每个请求最多 100 MB（PDF 为 50 MB），旧版的“约 20 MB”已经过时；更大的文件用 Files API 上传。
• imageSize 写了模型不支持的值。Pro 和 Nano Banana 2.1 只支持 1K、2K、4K，这几个模型里 512 只有 Nano Banana 2 支持。在老张API 上，10 月 7 日对 2.1 发 512 还返回 400 Image size 512 is not supported for this model，10 月 8 日同样的请求却返回了一张 1K 图并扣了一次费用，老张API 文档现已按后者更新。不管哪种结果，都不要给 2.1 发 512，改成 1K。
• Vertex AI 上调用 2.1 时带了采样参数。Google Cloud 的 Nano Banana 2.1 文档写明，seed、topK、logprobs、temperature、topP 在 2.1 上会返回 API 错误，从请求里删掉即可；从 Pro 或 Nano Banana 2 迁移过来的代码最容易漏。ComfyUI 的 Nano Banana 2.1 节点不会为 2.1 发送 temperature 和 top_p，但界面上仍有 seed，别指望在 2.1 上用固定种子复现同一张图。Vertex 的配置细节见 Vertex AI 调用 Nano Banana：正确配置与费用。

API key not valid 在 generateContent 上是 400，在 Interactions API 上是 401 authentication。先确认密钥没有复制错、没有多余空格，然后检查密钥类型。按 Gemini API 密钥文档（2026 年 10 月 6 日更新）：Gemini API 拒绝没有设置限制的标准密钥；从 2026 年 5 月 7 日起，长期闲置的无限制密钥会被封锁；从 2026 年 5 月 28 日起，AI Studio 新建的密钥默认是绑定服务账号的授权密钥。如果错误信息是 Your API key was reported as leaked. Please use another API key.，说明这个 key 被判定为泄露，已不能再用于 Gemini API，在 AI Studio 生成新 key，并检查代码仓库和前端有没有把 key 暴露出去。

402 Payment Required（Interactions API 为 payment_required）表示 Prepay 余额用完了。余额归零时，这个结算账户下所有项目的所有 API 密钥会同时停用，直到充值为止。Google 明确写了不要重试。在 AI Studio 的 Billing 页面充值（每次最少 $5，购买后 12 个月内有效），或者打开自动充值。如果错误是 400 FAILED_PRECONDITION 且提到结算，说明项目还没开通或关联结算。

403 PERMISSION_DENIED 表示密钥对这个资源或项目没有权限，常见于密钥设了 API 限制却没有包含 Gemini API，或者密钥和项目不对应。先用同一个 key 发一条最简单的纯文本请求，能通再查图片模型相关的设置，不能通就是密钥或项目的问题。

地区限制不靠改代码解决。Gemini API 可用地区列表（2026 年 4 月 28 日更新）不包括中国大陆、香港和俄罗斯，在这些地区 Google 不提供 Gemini API 服务。Google 的地区页没有写明这种情况返回哪个错误码；Google AI 论坛里关于“User location is not supported”的报错帖显示的是 400 FAILED_PRECONDITION 和 User location is not supported for the API use.。如果你确实在支持的地区却仍然收到这个错误，可以在 Google AI 论坛附上请求时间和错误原文请 Google 复核。

404 model_not_found：预览版模型 ID 已停用，换成哪个

404 最常见的原因是代码、ComfyUI 工作流或第三方工具里还写着已经停用的预览版 ID。Google 对 404 的建议是核对模型名，或者换到其他模型。按 Gemini API 弃用时间表：

Nano Banana Pro 的正式 ID 是 gemini-3-pro-image，Gemini API 上暂无停用日期。另外两个还能调用、但要尽早迁移的模型：

• Nano Banana 2（gemini-3.1-flash-image）：Gemini API 已弃用，暂无停用日期，Google 建议迁移到 gemini-nano-banana-2.1。2.1 发布当天页面上出现过“2026 年 10 月 29 日”，之后已被撤下，不要按这个日期安排。Vertex AI 上它的退役时间是“2027 年 5 月 28 日或之后”。
• 初代 Nano Banana（gemini-2.5-flash-image）：Google 的两个页面说法不一致。Gemini API 弃用时间表写的停用日期是 2027 年 3 月 15 日，替代是 gemini-3.1-flash-lite-image；Gemini API 定价页仍留着“将于 2026 年 10 月 2 日停用”的旧提示。Vertex AI 上是 2027 年 3 月 15 日。能不能继续调用请以你自己的请求结果为准，新代码不要再用它。

各模型 ID 的迁移对照和代码示例，见 Nano Banana API 教程：官方文档、模型选择与代码，默认用 2.1；2.1 的价格和入口见 Nano Banana 2.1 价格与入口；2、2.1、Pro 怎么选，见 Nano Banana 2、2.1、Pro 和 Lite 区别怎么选。

返回 200 却没有图：SAFETY、IMAGE_SAFETY、NO_IMAGE 与 blockReason OTHER

HTTP 200 只说明请求被处理了，不代表有图。安全拦截是 Nano Banana Pro 最让人困惑的错误，因为响应几乎不说原因。把 Google 写进文档的内容和开发者的猜测分开看会清楚很多：Google 没有公布“分层审核”架构或内部审核阶段，它公布的是 API 返回的字段名、枚举值，以及你能改的安全设置。错误处理围绕这些字段写就够了。Google 怎样区分内容拦截、限流和账号处置，以及各自怎么处理，见 Nano Banana Pro 风控：拦截、限流、封号各由什么触发，怎么处理。

Gemini API 安全设置文档（2026 年 9 月 17 日更新）是这样写的：可调的安全类别有骚扰、仇恨言论、色情内容和危险内容四类，阈值通过 safetySettings 设置；不设置时，Gemini 2.5 和 3 系列模型的默认阈值是 Off。另外，针对儿童安全等核心伤害的内置保护始终拦截，无法调整。响应会告诉你遇到的是哪种情况：

• 候选结果的 finishReason 可能是 SAFETY（看 safetyRatings）、IMAGE_SAFETY、IMAGE_PROHIBITED_CONTENT、IMAGE_RECITATION、IMAGE_OTHER、NO_IMAGE 或 OTHER。
• promptFeedback.blockReason 可能是 SAFETY、BLOCKLIST、PROHIBITED_CONTENT、IMAGE_SAFETY 或 OTHER，出现时提示词在生成前就被拦了。
• Interactions API 把这些写成小写错误码：image_safety、image_prohibited_content、image_recitation、image_other 属于“生成被拦截”，no_image 属于“生成错误”，含义是模型没能生成图片。

实际区别在于你能改什么。finishReason 是 SAFETY 时，safetyRatings 会告诉你是哪个类别，你可以调那个类别的阈值。把某个类别设为 BLOCK_NONE 只放宽这一类，不能指望它解除 OTHER 或始终拦截的内置保护（这是推断，与开发者反馈一致）。看到 finishReason: "IMAGE_SAFETY" 或信息 generated images may contain unsafe content，说明生成的图片因安全原因被拦，Google 没说触发了哪条规则，也没有可以关掉它的设置，只能改提示词。IMAGE_RECITATION 是图片可能与受版权保护的内容或训练数据过于相似，去掉具体作品、角色和品牌名再试。NO_IMAGE 是模型没有生成图片，一个常见原因是提示词没有明确要求出图、模型只回了文字，按 Nano Banana API 不出图：按返回字段逐项排查 逐项检查。

那 blockReason: OTHER 呢？ Google 的 API 参考只用一句话定义它：提示词因未知原因被拦截。排错指南补了一句：看到 OTHER，说明请求或响应可能违反服务条款，或者不受支持。没有可检查的字段，也没有可以解除它的设置，BLOCK_NONE 修不了它。怎么定位触发点，见 Nano Banana 2 blockReason OTHER：官方只写「原因未知」，该查什么。

改提示词时，下面几条经验有时有效，但 Google 没有写进文档，也没有成功率保证：用通用描述代替角色名或 IP（写“穿蓝色裙子的公主”，不写某个具体角色）；加上明确的画风，如“水彩风格数字插画”；人物主体不要和可能被理解为未成年人的服装或姿势描述放在一起。安全拦截由模型自身的保护机制决定，调用同一个 Google 模型的网关不会改变结果，所以换渠道不如改提示词。Google 没有公布各类别的拦截率，最好统计你自己的数据：模特穿搭的电商图、基于知名角色的同人图或恶搞图值得优先测试，风景、物件和抽象画一般不容易出问题。

Python 错误处理代码：重试、换模型与无图判断

下面的函数把前面的规则写进一个循环：只对 408、429 和 5xx 退避重试；出现两次 503 后换到 gemini-nano-banana-2.1；400、401、402、403、404 立即返回错误原文；HTTP 200 时检查 blockReason 和图片数据，没有图就带上 finishReason 返回，不当成成功。它用的是 Google 现行的 google-genai SDK，旧版代码里的 google.generativeai 写法要按 Gemini API 文档里的 SDK 迁移指南改写。

import random
import time

from google import genai
from google.genai import errors, types

PRIMARY_MODEL = "gemini-3-pro-image"
FALLBACK_MODEL = "gemini-nano-banana-2.1"
RETRYABLE = {408, 429, 500, 502, 503, 504}

# 默认客户端的 generate_content 不会自动重试，次数和等待全部由下面的循环控制
client = genai.Client()  # 从环境变量 GEMINI_API_KEY 读取密钥


def generate_image(prompt: str, max_attempts: int = 5) -> dict:
    model = PRIMARY_MODEL
    overloaded = 0
    for attempt in range(max_attempts):
        try:
            response = client.models.generate_content(
                model=model,
                contents=prompt,
                config=types.GenerateContentConfig(
                    response_modalities=["TEXT", "IMAGE"],
                    image_config=types.ImageConfig(image_size="2K"),
                ),
            )
        except errors.APIError as e:
            if e.code not in RETRYABLE:
                # 400/401/402/403/404 重试也不会成功，带上状态和原文交给人处理
                return {"status": "error", "code": e.code, "detail": e.status, "message": e.message}
            if e.code == 503:
                overloaded += 1
                if overloaded >= 2 and model != FALLBACK_MODEL:
                    model = FALLBACK_MODEL  # 文字准确度会下降，按业务决定是否允许
                    continue
            time.sleep(min(60, 2 ** attempt) + random.uniform(0, 1))
            continue

        feedback = response.prompt_feedback
        if feedback and feedback.block_reason:
            return {"status": "prompt_blocked", "reason": feedback.block_reason.name}
        candidate = response.candidates[0] if response.candidates else None
        parts = candidate.content.parts if candidate and candidate.content else None
        for part in parts or []:
            if part.inline_data and part.inline_data.data:
                return {"status": "ok", "model": model, "mime": part.inline_data.mime_type,
                        "data": part.inline_data.data}
        reason = candidate.finish_reason.name if candidate and candidate.finish_reason else "NO_CANDIDATE"
        return {"status": "no_image", "model": model, "reason": reason}
    return {"status": "gave_up", "model": model}

这段代码在 google-genai 2.29.0 上，用一个按顺序返回预设响应的本地模拟服务跑过以下情况：连续两次 429 后成功（共 3 次请求）、连续两次 503 后换到 2.1 成功、400 API key not valid 和 404 各只发 1 次请求就返回、IMAGE_SAFETY 和 NO_IMAGE 返回 no_image 和对应原因、blockReason: OTHER 返回 prompt_blocked、429 一直不消失时 5 次后放弃。这些都是模拟响应，没有用真实密钥请求 Google，所以真实错误信息的措辞以你自己的日志为准。

几个可以按需修改的地方：

• 每日配额用完的 429 用这个循环也恢复不了，5 次之后会返回 gave_up，这时应该停下来等太平洋时间午夜重置，或者申请提额。
• 不想要自动换模型，就删掉 503 那段，让它和 429 一样退避。
• 被拦截和无图的结果别自动重发，同一个提示词再发一次多半还是同样结果，在第三方网关上还会多扣一次费用。

除了重试，生产环境还值得加三样东西。第一，全部重试失败的请求进入队列，在负载低时再处理，并保存任务状态，续跑时跳过已经成功的图片。第二，熔断：同一模型在短时间内连续 503，就暂停向它发请求，把流量切到备用模型，直到探测请求恢复。第三，按错误类别统计 429、5xx 和安全拦截的比例，429 比例持续上升说明接近层级上限，该升层级、错峰或改用 Batch，而不是加重试次数。

Gemini 应用里的 Nano Banana Pro 限额：订阅不加 API 配额

在 Gemini 应用里提示“已达上限”和 API 的 429 是两回事，处理办法也不同。截至 2026 年 10 月 8 日，Google 帮助中心是这样写的：

• Gemini 应用按算力计算用量，每 5 小时刷新一次，直到达到每周上限。没有订阅是标准额度，Google AI Plus 是 2 倍，Google AI Pro 是 4 倍，Google AI Ultra 是 Pro 的 5 倍或 20 倍（视订阅而定）；生成图片会消耗更多额度。Google 没有公布每天能出多少张图。
• 用 Nano Banana Pro 重做图片需要 Google AI 订阅；Nano Banana 2 的每日额度用完后，也不能再用 Pro 重做。
• Google 的两个页面对应用里默认用哪个模型说法不同：gemini.google 的介绍页写的是有 Google AI 订阅的用户使用 Nano Banana 2.1，帮助中心仍写 Nano Banana 2。

Google 没有公布每天的出图张数，旧版表格里“免费每天约 2 张、Pro 订阅每天约 100 张、Ultra 每天约 1,000 张”这类数字已经删除。Google AI Pro、Ultra 订阅也不会给 API 增加任何配额，API 的 429 只能按上一节的方法处理。各入口的限额规则见 Nano Banana Pro 每日限额与额度用完：Gemini、AI 模式、Flow、API；免费能用到什么程度，见 Nano Banana Pro 免费吗：Gemini、Flow 与 API 的实际规则。

API 按张计费，截至 2026 年 10 月 8 日的 Google 标准价：Nano Banana Pro 1K 或 2K 每张 $0.134，4K 每张 $0.24，Batch 半价（$0.067 和 $0.12）；Nano Banana 2.1 为 1K $0.0336、2K $0.0504、4K $0.113。Flex 有一处矛盾：Gemini API 定价页给 gemini-3-pro-image 列了 Flex 价格，但 Flex 推理文档的支持列表里没有任何图片模型，Pro 的模型页也写着不支持 Flex，所以想半价出图请用 Batch。价格细节见 Gemini 3 Pro Image API 定价 2026：1K/2K 每张 $0.134，4K $0.24，Batch 和逐次调用怎么选见 Nano Banana Pro Batch API 成本：2K 用 Batch，4K 按次 $0.09 更省。

什么时候换模型或换服务商：Nano Banana 2.1、Batch 与老张API

不是每个错误都能很快修好。高峰时段 503 持续不断、合法提示词经常被 IMAGE_SAFETY 拦截、每日配额或 10 分钟花费上限卡住业务，这几种情况出现时，就该在架构里准备备用路线，而不是继续加重试。Nano Banana Pro 仍然是文字渲染最可靠的选择之一，备用路线是为了让失败不直接暴露给用户。

可选的方向有三个，各有前提：

• 同一 Google 账户内换模型：文字要求不高的任务用 gemini-nano-banana-2.1，单价约为 Pro 的四分之一（$0.0336 对 $0.134，1K），但它的限额和 Pro 一样受项目层级约束。
• 不急的任务走 Batch：1K/2K 每张 $0.067，4K 每张 $0.12，有独立的 Batch 限额，适合批量出图。
• 按次计费的网关做备用：老张API 上 gemini-3-pro-image 不论 1K、2K、4K 每次调用 $0.09，gemini-nano-banana-2.1 为 $0.045，gemini-3.1-flash-image 为 $0.055，gemini-3.1-flash-lite-image 为 $0.025（截至 2026 年 10 月 8 日）。和 Google 标准价比，Pro 1K/2K 便宜 ($0.134 − $0.09) ÷ $0.134 ≈ 32.8%，4K 便宜 ($0.24 − $0.09) ÷ $0.24 = 62.5%；1K/2K 的 Batch（$0.067）比它更便宜；4K 的 Batch 是 $0.12，老张API 比它便宜 ($0.12 − $0.09) ÷ $0.12 = 25%。

用网关前要知道三点：返回 HTTP 200 但没有图片的调用也按一次计费，所以安全拦截后不要盲目重发；尺寸和宽高比只能在 Gemini 原生的 generateContent 路径上设置，OpenAI 兼容路径只返回 1K 图片；安全拦截来自模型本身，换网关不会让被拦的提示词通过。2.1 的接入方式和计费规则见 老张API 的 Nano Banana 2.1 文档。套餐、API 和网关的总体对比见 Nano Banana Pro 多少钱？API、订阅与每张合格图成本；如果要考虑 Google 以外的模型，见 FLUX.2 Pro 与 Nano Banana Pro 怎么选：改图、中文海报与单张成本。

接入备用路线的成本不高：在上面代码返回 gave_up 或 503 降级失败的分支里，把请求转给备用端点即可。关键是把“生成一张图”抽象成一个只接收提示词、返回图片的接口，底层用哪个模型、哪个服务商按可用性切换。依赖单一模型之前，也请核对 Google 对你所用产品的服务条款里有没有适用的 SLA。

常见问题

Nano Banana Pro 的 429 RESOURCE_EXHAUSTED 要等多久？

看撞的是哪种上限。每分钟限额等这一分钟过去就恢复；10 分钟花费上限按滚动窗口计算，等之前的花费移出窗口；每日配额要等到太平洋时间午夜重置；结算账户的月度上限要等到下个月 1 日。冷却期间激进重试只会继续撞限额，建议从约 1 秒开始指数退避，最长等 60 秒，并限制次数。

Nano Banana Pro API 有免费额度吗？

没有。Gemini API 定价页上所有图片模型的免费层都是“不可用”，项目要关联结算账户（Tier 1）才能出图，Google AI Pro 或 Ultra 订阅也不会增加 API 配额。Gemini 应用里用 Pro 重做图片同样需要 Google AI 订阅。

能关掉 Nano Banana Pro 的 IMAGE_SAFETY 拦截吗？

不能。safetySettings 只管骚扰、仇恨言论、色情内容、危险内容四个可调类别，Google 没有提供关闭 IMAGE_SAFETY 的设置，针对核心伤害的内置保护也始终生效。能做的是改提示词：用通用描述代替角色名，写清主体和画风，避免把人物和可能暗示未成年人的描述放在一起。这些是经验做法，没有官方成功率。

为什么 Nano Banana Pro 一直提示 "generated images may contain unsafe content"？

这是图片层面的安全拦截，和 finishReason: IMAGE_SAFETY 是同一类。Google 没有说明触发的是哪条规则，所以从这句话看不出是角色、真人还是构图的问题。用通用描述和明确的画风（如“水彩插画”“扁平矢量风格”）重写；同一提示词仍然失败，就逐步删减内容找出触发点。如果看到的是 promptFeedback.blockReason: OTHER，Google 只把它定义为“未知原因”。

finishReason 里的 SAFETY 和 IMAGE_SAFETY 有什么区别？

SAFETY 表示候选结果因四个可调类别之一被中止，safetyRatings 会显示是哪一类，你可以调整对应阈值。IMAGE_SAFETY 表示生成的图片因安全原因被拦截，Google 没有说明规则，也没有能改变它的设置，只能改提示词。两者都不同于 promptFeedback.blockReason: OTHER。

为什么换了新 key 还是报 404？

404 和密钥无关，是模型 ID 的问题。检查代码、ComfyUI 工作流或第三方工具里是否还写着 gemini-3-pro-image-preview、gemini-3.1-flash-image-preview 这类预览版 ID，它们已于 2026 年 6 月 25 日停用。Pro 改成 gemini-3-pro-image，Flash 档改成 gemini-nano-banana-2.1。

怎么判断 Nano Banana Pro 是不是宕机了？

Gemini API 用户先看 Google AI Studio 状态页，Vertex AI 用户看 Google Cloud Service Health。状态页没有事件但你仍连续收到 503，用一条简单提示词发一张 1K 测试图，区分是模型过载还是你的请求参数有问题；Google AI 开发者论坛上也常能看到其他开发者同时段的报告。