Nano Banana Pro API 怎么调用：官方文档、JSON 模板、YAML 配置与 PDF 边界

现在调用 Nano Banana Pro，Google 官方模型 ID 是 gemini-3-pro-image。如果是新接入，优先按 Interactions API 调用；现有 generateContent 项目可以继续维护，但它是另一套请求和返回格式。

30 秒选路线，然后直接调用

先按你的真实条件选合同：

Google 直连的最小请求如下。把 AI Studio 的 key 放进环境变量 GEMINI_API_KEY：

bash
curl -sS -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "input": [{
      "type": "text",
      "text": "为一家上海茶饮店生成 16:9 夏季新品海报。画面中央是一杯透明青柠气泡茶，浅绿色背景，只出现中文“青柠气泡茶”和“夏日限定”。不要价格、人物、英文副标题或额外 Logo。"
    }],
    "response_format": {
      "type": "image",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'

这段请求依据 2026 年 7 月 20 日的 Google 图片生成文档 整理，并通过本地 JSON 语法检查。本轮没有获得用于任务的付费凭据，也没有执行真实生图，因此不把它写成速度、画质或成功率实测。

报错前先核对字段归谁

复制到一半最容易出错，因为网上常把四类内容都叫“API JSON”：

Google 当前仍维护 generateContent 图片文档。若旧项目使用 contents[].parts[]、generationConfig 和 candidates[].content.parts[]，就把 endpoint、body、parser 作为一个整体保留。不要只换 model 字符串，再把 Interactions 的字段塞进去。

首次失败时按这个顺序查：endpoint → key 发行方和 header → model ID → body → response parser → project limit。六项同时改，会让 400、401、404、429 和上游错误失去可判断性。

JSON prompt 和 YAML 应该停在应用层

为了让运营、设计和开发对需求达成一致，可以保存一份语义对象：

json
{
  "scene_id": "shanghai-lime-tea-summer",
  "product": "透明杯青柠气泡茶",
  "required_text": ["青柠气泡茶", "夏日限定"],
  "visual_rules": ["浅绿色背景", "中央单品", "杯身与青柠完整可见"],
  "forbidden": ["价格", "人物", "英文副标题", "额外 Logo"],
  "output": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }
}

这不是 Google 官方 schema。程序应先校验数组、文字和档位，把语义字段渲染成自然语言，再把比例与尺寸写进当前 endpoint 允许的位置。Structured Outputs 约束的是模型返回的 JSON，不是一个能让 Nano Banana Pro 自动提质的“官方 JSON 提示词”。

同一任务也可以存成 YAML，方便覆盖环境和批次默认值：

yaml
route: google-interactions
model: gemini-3-pro-image
credential_env: GEMINI_API_KEY

creative:
  scene_id: shanghai-lime-tea-summer
  required_text:
    - 青柠气泡茶
    - 夏日限定
  forbidden:
    - 价格
    - 人物
    - 英文副标题
    - 额外 Logo

output:
  aspect_ratio: "16:9"
  image_size: 2K

YAML 运行时必须经过解析、类型校验、secret 注入和 route mapping。不要把它以 application/yaml 直接 POST，也不要在仓库里保存真实 key。服务商若没有明确文档，也不会自动理解 credential_env 或 required_text。

文档问题先做 PDF 决策

“Gemini 能读 PDF”不等于“所有 Gemini 模型都能直接收 PDF”。当前 Gemini 3 Pro Image 模型卡 声明的是文本和图片输入；PDF 属于另一条 文档理解能力。

按任务选处理方式：

• 只需要报告中的几项事实： 用支持文档的 Gemini 模型读取 PDF，抽取数值、页码和标签，核对后把文字交给 Pro。
• 需要保留图表或版式： 先提取并核验相关页，再把选定页面渲染为图片，和文字一起输入 Pro。
• 要求逐页、逐表、脚注和法律文字全部不丢： 停止把任务当普通生图，改用文档生产与人工校对流程。
• 含客户、合同或未公开数据： 先确认允许上传的产品、地区、保留期和数据合同。

通用文档说明里的 50 MB、1000 页是 document-capable route 的边界，不能反向证明 gemini-3-pro-image 支持 PDF 直传。Word、Markdown、HTML、XML 等按文本读取时也可能丢失布局和图表语义。

国内接入服务商要核验什么

网关有价值的前提是，它确实解决你的付款、统一账单、模型切换或日志需求。切换 base URL 后，以下内容都变成 provider owner：

当前公开 laozhang.ai 文生图文档 使用 provider alias gemini-3-pro-image，列出 $0.09/call；简单的 OpenAI-compatible 路径固定在 1:1/1K，自定义比例与 2K/4K 走其 generateContent-compatible route。这些只是该服务商当前公开合同，不是 Google 官方 endpoint 或价格。

同一文档目前在“14 种比例”和部分像素表项上与 Google Pro 专属表不完全一致。产品 UI 不能把 provider 选项反写成官方能力；若 live console、日志和返回 metadata 无法解释差异，就不要上线。

Key、Free Tier、价格和 quota 是四个问题

• Key： 在 API key 官方文档 与 AI Studio 中管理并绑定 Google Cloud project。新 key 默认走 auth key；Google 当前说明 standard key 将在 2026 年 9 月被拒绝。
• Free Tier： Google Pro 图片输出行当前不提供 Free Tier。能免费创建 key，不代表图片调用免费。
• 价格： 官方价格页 在 2026 年 7 月 20 日列出 Standard 的 1K/2K 为 $0.134、4K 为 $0.24；Batch/Flex 分别为 $0.067、$0.12。输入、thinking/text output、grounding、重试和税费还可能增加账单。
• Quota： Rate limit 文档 明确限制按 project 执行，不按 key 叠加。实际 RPM、TPM、RPD、图像 IPM 以当前 project 页面为准。

只缺凭据时看 Nano Banana Pro API key 获取指南；卡在 429 或容量时看 Nano Banana Pro quota 提升指南。两个 reader job 不应靠轮换 key 混在一起处理。

官方 Pro 表当前列出 1K、2K、4K 和 10 个比例：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9。通用配置参考和服务商可能出现额外比例，不能直接写成 Pro 官方保证。“4K”也是档位，而非每种比例都等于 4096×4096。

参考图同样有双重边界：官方页面描述总计最多 14 张，并给出 6 张物体、5 张人物一致性、3 张风格参考的任务分项；同页另有 5 张高保真图片限制。更稳妥的产品文案是“总量上限仍受类别和保真限制”。

按错误码保留证据

调用规则可以压缩成一句：先选合同，核对 endpoint、鉴权、model、body、response、quota，做一笔有日志的小测试后再放量。