Vertex AI 调用 Nano Banana：正确配置与费用

截至 2026 年 9 月 24 日，用 Vertex AI 调用 Nano Banana 仍然可行，但按 2025 年的写法配置的代码，基本都要改三处：模型 ID 换成正式版（gemini-3.1-flash-image、gemini-3-pro-image、gemini-3.1-flash-lite-image），location 用 global（只有 Nano Banana 2 还能选 us、eu），客户端开启 enterprise=True 或设置环境变量 GOOGLE_GENAI_USE_ENTERPRISE=True。带 -preview 后缀的两个图片模型已在 2026 年 7 月 17 日退役，而 Python SDK 不会在本地拦截这些 ID，请求照常发出，到了服务器才失败。

费用上，Vertex 的 global 标价和 AI Studio 付费层完全一致：Nano Banana 2 一张 2K 图的输出费约 $0.10，Nano Banana Pro 的 1K 和 2K 都约 $0.134。换到 Vertex 不会更便宜，它的价值在于服务账号与 IAM、VPC Service Controls、CMEK、数据驻留和 Google Cloud 统一账单。公司没有这些要求、只想拿一个 key 出图，AI Studio 的 API Key 路线更省事。

Vertex AI 改名之后，旧代码为什么跑不通

2026 年 4 月 22 日起，Google 把 Vertex AI 并入 Gemini Enterprise Agent Platform。官方中文文档现在写作「Agent Platform」，控制台里原来的 Vertex AI Studio 改叫 Agent Studio，API 叫 Agent Platform API；文档地址迁到 docs.cloud.google.com/gemini-enterprise-agent-platform/...，旧的 vertex-ai/generative-ai/docs/... 链接仍能打开，调用的主机依然是 aiplatform.googleapis.com。所以查资料时，「Vertex AI」和「Agent Platform」指的是同一个平台，不是两条路线。

Python SDK 也跟着改了参数名。google-genai 2.25.0（2026 年 9 月 22 日发布）的源码注释里，enterprise 参数的说明是「Gemini Enterprise Agent Platform 端点（原 Vertex AI API）」，vertexai 则标为旧参数。两者在 2.25.0 里效果相同，旧代码里的 vertexai=True 暂时不用改；但新代码建议统一写 enterprise=True，和官方示例保持一致。

旧代码失效通常出在下面三处：

• 模型 ID 已退役：gemini-3.1-flash-image-preview 和 gemini-3-pro-image-preview 于 2026 年 5 月 28 日弃用，7 月 17 日在 Agent Platform 上退役，官方写明「no longer accessible」。SDK 不校验模型名，写错或写旧都照样拼出请求地址。
• 客户端没切到 Vertex：只传了 project 和 location，没开 enterprise 或 vertexai，SDK 会把它当成 AI Studio 客户端，直接抛出 ValueError: Gemini API does not support project/location.。
• 照搬了 AI Studio 文档的新写法：ai.google.dev 的图片生成文档现在以 Interactions API 为主（参数放在 response_format 里）；Vertex 的官方示例仍是 generateContent 加 imageConfig（aspectRatio、imageSize）。两套写法的参数名和结构不同，不能混用。

还有一处容易看漏：同一个模型 ID 在两个平台上的退役时间不同。初代 Nano Banana（gemini-2.5-flash-image）在 Gemini API 上 2026 年 10 月 2 日停用，在 Agent Platform 上延到 2027 年 3 月 15 日。

模型 ID、location 与退役时间对照

下表按 Agent Platform 模型页整理（模型页最后更新于 2026 年 9 月 22 日）。

几点会改变你配置的细节：

• Pro 和 Lite 只能用 global。把 location 写成 us-central1 之类的具体区域，这两个模型都不在可用列表里。官方图片生成页的 Node.js 示例默认 location 是 us-central1、模型是 gemini-2.5-flash-image，照着改模型名时要把 location 一起换成 global。
• Nano Banana 2 的 us、eu 多区域从 2026 年 8 月 31 日起提供，覆盖模型可用性、ML 处理、Provisioned Throughput 和 Standard PayGo，适合需要把数据处理留在美国或欧盟的团队，但单价比 global 高 10%。
• 没有亚洲区域。所有 Nano Banana 模型都没有亚洲的区域端点，需要把数据驻留在亚洲的团队无法用 Vertex 满足这一条。
• 7 月 17 日的发布说明里建议迁移到 gemini-3-flash-image，这是笔误；弃用表和模型页给出的 Pro 替代 ID 是 gemini-3-pro-image。

能力方面，Nano Banana 2 和 Pro 都支持 15 种宽高比，包括 1:4、4:1、1:8、8:1、21:9、9:21；Lite 支持 14 种。Nano Banana 2 和 Pro 一次最多传 14 张参考图，内联图片每张不超过 7 MB，从 Cloud Storage 读取的每张不超过 30 MB。Nano Banana 2 和 Pro 都支持「使用 Google 搜索建立依据」，不支持函数调用和代码执行，也不支持微调。4K 输出从 8 月 31 日起在 Nano Banana 2 和 Pro 上转为正式功能。

走 Vertex 还是 AI Studio API Key

两条路线调用的是同一批模型，差别在认证、端点、额度和企业控制：

Google 在 Gemini API 迁移文档里的原话是：大多数开发者应使用 Gemini Developer API，除非确实需要特定的企业控制。据此可以这样判断：

• 选 Vertex：公司要求走 GCP 账单或合规流程；需要 VPC-SC、CMEK、美国或欧盟数据驻留；想用 Google Cloud 免费试用的 $300 赠金；或者线上还在跑 gemini-2.5-flash-image，需要多几个月迁移时间。
• 选 AI Studio：个人项目或原型，不需要上述控制，想少配一套 IAM。接入方式见 Nano Banana API Key 指南 2026：官方 Gemini 接入、模型选择与可运行代码；两个平台在治理、计费和迁移上的完整对比见 Gemini API 和 Vertex AI API 怎么选：先看开发速度还是云上治理。

关于 $300 赠金：Google Cloud 免费试用的条款只点名了两类不能用赠金支付的费用，一是 AI Studio 里的 Gemini API，二是以托管 API 形式提供的第三方合作模型。Agent Platform 上 Google 自家的 Gemini 不在排除项里，按条款可以用赠金支付 Nano Banana 的调用费。代价是试用期账号不能申请提高配额。

跑通第一张图

准备项目和凭据

1. 准备一个已关联结算账号的 Google Cloud 项目（免费试用账号也可以），启用 Agent Platform API：gcloud services enable aiplatform.googleapis.com。
2. 本机开发用应用默认凭据（ADC）：gcloud auth application-default login。部署到服务器时改用服务账号，不要把个人凭据放上去。
3. 安装或升级 SDK：pip install --upgrade google-genai（Node.js 为 npm install @google/genai）。
4. 可选但值得做：在控制台打开 Agent Studio，点「Create prompt」，用「Switch model」选模型，把「Outputs」设为「Image and text」，发一句提示词。控制台能出图、代码不能出图时，问题多半在客户端这一侧（SDK 开关、模型 ID、location 或网关），而不在项目本身。

Python：显式传参

import os
from google import genai
from google.genai import types

client = genai.Client(
    enterprise=True,  # 旧写法 vertexai=True 在 2.25.0 中效果相同
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    location="global",  # Pro 和 Lite 只能用 global；Nano Banana 2 还可以用 "us" 或 "eu"
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents="一只橘猫趴在窗台上看雨，水彩风格",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
    ),
)

for i, part in enumerate(response.candidates[0].content.parts):
    if part.text:
        print(part.text)
    elif part.inline_data:
        ext = part.inline_data.mime_type.split("/")[-1]
        with open(f"output_{i}.{ext}", "wb") as f:
            f.write(part.inline_data.data)

也可以不在代码里写参数，改用官方快速入门的三个环境变量，然后直接 genai.Client()：

export GOOGLE_CLOUD_PROJECT=你的项目ID
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

如果环境里还留着旧的 GOOGLE_GENAI_USE_VERTEXAI，并且和 GOOGLE_GENAI_USE_ENTERPRISE 的值冲突，2.25.0 会打印警告并以 GOOGLE_GENAI_USE_ENTERPRISE 为准。

在 google-genai 2.25.0 里离线构造上面这次调用（请求在发出前被拦下，没有真正访问 Google，也没有生成图片），SDK 拼出的地址是：

https://aiplatform.googleapis.com/v1beta1/projects/<项目ID>/locations/global/publishers/google/models/gemini-3.1-flash-image:generateContent

请求体里的生成配置序列化为 {'responseModalities': ['TEXT', 'IMAGE'], 'imageConfig': {'aspectRatio': '16:9', 'imageSize': '2K'}}。把模型换成已退役的 gemini-3.1-flash-image-preview，SDK 同样照常拼出地址，本地不报任何错。把 location 换成 us 或 eu，主机变成 aiplatform.us.rep.googleapis.com 或 aiplatform.eu.rep.googleapis.com；换成 us-central1，主机变成 us-central1-aiplatform.googleapis.com。这个离线探测只验证了 SDK 的路由和参数拼装，出图耗时、成功率和画面质量都不在其中。

curl：直接调 REST

PROJECT_ID="你的项目ID"
MODEL_ID="gemini-3.1-flash-image"

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/google/models/${MODEL_ID}:generateContent" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一只橘猫趴在窗台上看雨，水彩风格"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }' > response.json

jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' response.json \
  | head -n 1 | base64 --decode > output.png

官方 REST 和 express 模式示例用的是 v1，Python SDK 用的是 v1beta1，请求体结构相同。图片以 base64 字符串放在 inlineData.data 里，2K、4K 图的响应体会很大，自建代理或网关要留意请求体和响应体的大小上限。

express 模式：只有 API Key 时

Agent Platform 的 express 模式目前是预览功能，面向 @gmail.com 账号：从未用过 Google Cloud 的新用户注册后有 90 天免费层，不用填结算信息，额度内免费；已经是 Google Cloud 用户、或者一旦启用结算，免费层就取消。注册后拿到一个 API Key，客户端这样写：

client = genai.Client(enterprise=True, api_key=os.environ["GOOGLE_API_KEY"])

这种写法不传 project 和 location，SDK 直接走 aiplatform.googleapis.com。

需要注意的是，express 模式说明页的模型列表里，图片模型仍然写着已退役的两个 preview ID 和 gemini-2.5-flash-image（每分钟 10 次请求）；正式版图片 ID 能不能在 express 免费层调用，页面没有写明。不要把它当成免费出图的固定渠道，想用的话先在 express 控制台里实际出一张图再写代码。

一张图多少钱：按分辨率算

Vertex 按 token 计费，图片输出的单价是每 100 万 token：Nano Banana 2 在 global 为 $60、在 us / eu 为 $66，Pro 为 $120，Lite 和初代 Nano Banana 为 $30。每张图按分辨率折合固定的输出 token 数，所以单张输出费用可以直接算：

单张输出费用 = 该分辨率的输出 token 数 × 图片输出单价 ÷ 1,000,000

表中是 2026 年 9 月 24 日 Agent Platform 价格页的美元标价，只算图片输出。几个会影响账单的点：

• Pro 的 1K 和 2K 同价。用 Pro 时直接出 2K，不多花钱。
• Flex PayGo 和 Batch 的图片单价都是 Standard 的一半（Batch 即批量推理）。夜间批量生成商品图这类不需要立即拿到结果的任务，走 Batch 可以把单张费用直接减半。另有价格更高的 Priority PayGo，Pro 图片输出为每 100 万 token $216。
• 输入另计：每张参考图在 Nano Banana 2 和 Lite 上按 1,120 token 计，在 Pro 上按 560 token 计，折合约 $0.00056（Nano Banana 2）和 $0.00112（Pro）；提示词文字按输入单价计，金额很小。
• 文字输出和思考过程按文字输出单价计：Nano Banana 2 每 100 万 token $3（us / eu 为 $3.30），Pro 为 $12。模型边想边画时，这部分会让实际单价略高于表中数字。
• 使用 Google 搜索建立依据另外计费：所有 Gemini 3 模型合计每月 5,000 次免费，之后每 1,000 次 $14。
• 被安全策略拦下或失败后重试的请求，也可能产生输入和文字 token 费用。

举例：用 Nano Banana 2 在 global 生成 1,000 张 2K 图，Standard 约 1,680 × 60 ÷ 1,000,000 × 1,000 = $100.80，走 Batch 约 $50.40；同样 1,000 张换成 Pro，Standard 约 $134.40。这些是按标价的估算，不是账单，实际以 Cloud Billing 为准。

报错与 429：按现象排查

先看下表定位，再按改法处理。SDK 报错原文取自 google-genai 2.25.0，其他版本措辞可能不同。

最后一行来自 2025 年 9 月 linux.do 上的讨论：当时有人在 Vertex AI Studio 里能用，经 new-api、done-hub 调用却失败，回复指出新模型需要客户端适配（new-api 当时要 0.9 alpha 15 之后的版本）。版本号已经过时，但排查顺序仍然适用：先确认网关支持该模型，再确认渠道配置。ComfyUI 等工具里的 Vertex 节点同理，关键是节点能否传入正式版模型 ID 和 global。

429 怎么处理

Vertex 上的 429 有两种原文。按量付费时是 Resource exhausted, please try again later.，说明共享容量暂时不够；买了 Provisioned Throughput 的项目超出预留量时是 Too many requests. Exceeded the Provisioned Throughput.。

图片模型的容量是共享的，按尽力而为分配。Standard PayGo 按组织支出分档、给出每分钟 token 基线的那套规则，官方文档明确写着不适用于 Nano Banana 2、Nano Banana 2 Lite、Nano Banana Pro 和初代 Nano Banana；模型页也都标注不支持固定配额，所以没有可以申请提高的项目配额，Google 也没有公布这几个模型每分钟能出多少张图。

Google 给出的处理办法：

1. 尽量用 global 端点，不用区域端点。global 能调度更大的多区域共享容量。
2. 用截断指数退避重试。
3. 平滑流量，把请求均匀分布在每一分钟里，避免秒级的尖峰；用量增长时逐步加量，用量陡增可能触发加速限制，同样返回 429。
4. 需要确定的容量、不能接受限流时，购买 Provisioned Throughput。

按量付费下的 429 不计入 SLA 的错误率。google-genai 2.25.0 默认不重试，要在创建客户端时传入 HttpRetryOptions 才会开启；开启后默认最多请求 5 次（含第一次），对 408、429、500、502、503、504 按指数退避加随机抖动重试：

import os

from google import genai
from google.genai import types

client = genai.Client(
    enterprise=True,
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    location="global",
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
)

2026 年 1 月到 3 月，Google AI 开发者论坛上有人反映 Vertex 上的 Nano Banana Pro 在很低的用量下持续返回 429，发帖人称改用 Gemini API 后不再报错；Google 员工称 1 月 8 日推送了修复，之后仍有「5 到 6 个并发就 429」的反馈。这些都发生在 preview 阶段、正式版发布之前，不能说明现在的稳定性。低用量下仍频繁 429 时，可以用同一提示词分别走 Vertex 和 AI Studio Key 各试一次，判断问题在入口还是在自己的流量；区分服务故障和自身问题的方法见 Nano Banana 2 宕机了吗？先查入口，再判断 429、503。

Vertex 出的图有没有水印

API 直接返回图片数据，文档没有提到可见角标，但这不等于没有水印。Gemini API 文档写明所有生成图片都带 SynthID 隐形水印；Google Cloud 博客介绍 Vertex 上的 Nano Banana 时也写明内置 SynthID，Nano Banana 2 的企业版公告提到 SynthID 与 C2PA 内容凭据配合使用，模型页同样列出支持 C2PA。「Vertex 出图没有水印」只在「看不到 logo」这个意义上成立，图片里仍嵌有 SynthID 隐形水印，并可附带 C2PA 内容凭据。

不需要 Vertex 的企业控制时

Nano Banana 模型在 Vertex 上没有亚洲区域端点。服务器在中国大陆时，需要能稳定访问 aiplatform.googleapis.com 的国际网络，还要能开通 Google Cloud 结算；这两点是网络与账号条件，跟代码写法无关。

如果你并不需要 VPC-SC、CMEK、数据驻留、Google 的 SLA 或 Provisioned Throughput，只是想拿到 Nano Banana 的图，还有两条路：

• AI Studio API Key：同样是 Google 官方接口，标价与 Vertex 的 global 一致，不用配 IAM 和项目，只是 Nano Banana 2 和 Pro 没有免费层。
• 老张API（laozhang.ai）：第三方按次计费服务，适合开不了 Google Cloud 结算、或服务器不便直连 Google 端点的场景。截至 2026 年 9 月 24 日，gemini-3.1-flash-lite-image 每次 $0.025、gemini-3.1-flash-image 每次 $0.055、gemini-3-pro-image 每次 $0.09，不随分辨率变化。它提供 Gemini 原生格式的 POST https://api.laozhang.ai/v1beta/models/{model}:generateContent，同样用 generationConfig.imageConfig 设置比例和分辨率，Bearer 认证；也有 OpenAI 兼容格式。模型 ID 和上文相同，文档见 docs.laozhang.ai 的 Nano Banana 页面。

老张API不是 Vertex：没有 VPC-SC、CMEK、数据驻留、Google SLA 和 Provisioned Throughput，请求要经过第三方。按次价也不是在所有情况下都更便宜：Nano Banana 2 出 512 图时 Vertex Standard 为 $0.0448，走 Batch 的 1K 图只要 $0.0336，Pro 走 Batch 的 1K、2K 图为 $0.0672，Lite 走 Batch 为 $0.0168，都低于对应的按次价；三个模型的 Standard 调用（Nano Banana 2 为 1K 到 4K）则是按次价更低，而且按次价不随思考 token 和参考图数量增加。公司要求合规审计的场景，仍然应该用 Vertex。

常见问题

用 Vertex 调用 Nano Banana 免费吗？

没有长期免费额度。Google Cloud 新用户有 90 天、$300 的试用赠金，条款没有把 Agent Platform 上的 Gemini 排除在外，可以用来付 Nano Banana 的调用费；express 模式对新用户有 90 天免费层，但说明页的模型列表还停在已退役的 preview ID，正式版图片模型能否免费调用没有写明。AI Studio 那边的 Nano Banana 2 和 Pro 也没有免费层。更多额度规则见 Nano Banana 2 限制与每日额度：按算力还是按张。

Vertex 上的 Nano Banana 能微调吗？

不能。Agent Platform 的模型页对 Nano Banana 2、Pro 和 Lite 都标注「Tuning: Not supported」。想固定风格或角色，只能靠参考图（Nano Banana 2 和 Pro 每次最多 14 张）和提示词。

gemini-2.5-flash-image 还能用多久？

在 Agent Platform 上用到 2027 年 3 月 15 日，在 Gemini API 上 2026 年 10 月 2 日就停用。官方建议迁移到 gemini-3.1-flash-lite-image，它同样只出 1K 图，输出单价和初代一样是每 100 万 token $30，单张约 $0.0336。

Vertex 上的 Pro 和 AI Studio 上的 Pro 请求格式一样吗？

模型相同，Vertex 这边用 generateContent 加 imageConfig，AI Studio 的新文档以 Interactions API 为主。Vertex 的 ImageConfig 还多出几个 Gemini API 不支持的字段：output_mime_type、output_compression_quality、prominent_people、image_output_options。Pro 在 Gemini API 侧的请求结构见 Nano Banana Pro API 怎么调用：官方文档、JSON 模板、YAML 配置与 PDF 边界。