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

> 新接入优先使用 Google Interactions API；JSON 提示词不是官方 schema，YAML 不能直接提交，PDF 应先由文档模型读取。

- URL: https://blog.laozhang.ai/zh/posts/nano-banana-pro-api-guide
- Published: 2026-04-01
- Updated: 2026-07-20
- Author: AI Free API Team (https://blog.laozhang.ai/zh/about)
- Category: API 指南
- Tags: Nano Banana Pro, Gemini 3 Pro Image, Gemini API, JSON 模板, YAML, Google AI Studio

---
现在调用 Nano Banana Pro，Google 官方模型 ID 是 **`gemini-3-pro-image`**。如果是新接入，优先按 [Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview) 调用；现有 `generateContent` 项目可以继续维护，但它是另一套请求和返回格式。

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

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

| 你的情况 | 先走哪条路 | 不要混入 |
| --- | --- | --- |
| 有可计费的 Google project，需要官方原生能力 | Google Interactions | 服务商的 Bearer token、task ID、`prompt` body |
| 已有 `generateContent` 代码 | 保留兼容合同，单独迁移 | Interactions 的 `response_format` 和 output parser |
| 需要统一充值、切模型或服务商日志 | 按具体 provider 文档 | 把 provider alias、价格写成 Google 官方事实 |

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 图片生成文档](https://ai.google.dev/gemini-api/docs/image-generation) 整理，并通过本地 JSON 语法检查。本轮没有获得用于任务的付费凭据，也没有执行真实生图，因此不把它写成速度、画质或成功率实测。

![Nano Banana Pro API 合同图，显示提示语义如何进入 Google 或服务商请求，以及 PDF 为什么要先经过文档模型](https://blog.laozhang.ai/posts/zh/nano-banana-pro-api-guide/img/cover.webp)

## 报错前先核对字段归谁

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

| 内容 | 真正 owner | 典型字段 | 错放后的结果 |
| --- | --- | --- | --- |
| Google Interactions | Google | `model`、`input`、`response_format` | 400、输出解析失败 |
| Google `generateContent` | Google 兼容路径 | `contents`、`generationConfig` | 字段大小写或 response parts 不匹配 |
| JSON 提示对象 | 你的应用 | 主体、文字、构图、禁止项 | 不能直接当官方请求体 |
| Provider JSON | 具体服务商 | `prompt`、task、URL 或自有 alias | 鉴权、价格、日志 owner 变了 |

Google 当前仍维护 [`generateContent` 图片文档](https://ai.google.dev/gemini-api/docs/generate-content/image-generation)。若旧项目使用 `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](https://ai.google.dev/gemini-api/docs/structured-output) 约束的是模型返回的 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 模型卡](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image) 声明的是文本和图片输入；PDF 属于另一条 [文档理解能力](https://ai.google.dev/gemini-api/docs/document-processing)。

按任务选处理方式：

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

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

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

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

| 上线前证据 | 要看到什么 | 看不到时怎么做 |
| --- | --- | --- |
| 模型 | 当前控制台 alias 与返回 metadata | 不凭营销页猜上游 |
| 费用 | 单价、输入/输出附加项、失败计费 | 先做一笔可追踪小调用 |
| 合同 | endpoint、auth、body、parser | 不把 Google 示例直接换 URL |
| 质量 | 实际尺寸、比例、文字与参考图表现 | 保存请求与结果再比较 |
| 数据 | 日志、保留、删除、支持边界 | 敏感任务停止上传 |

当前公开 [laozhang.ai 文生图文档](https://docs.laozhang.ai/api-capabilities/nano-banana-pro-image) 使用 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 官方文档](https://ai.google.dev/gemini-api/docs/api-key) 与 AI Studio 中管理并绑定 Google Cloud project。新 key 默认走 auth key；Google 当前说明 standard key 将在 2026 年 9 月被拒绝。
- **Free Tier：** Google Pro 图片输出行当前不提供 Free Tier。能免费创建 key，不代表图片调用免费。
- **价格：** [官方价格页](https://ai.google.dev/gemini-api/docs/pricing) 在 2026 年 7 月 20 日列出 Standard 的 1K/2K 为 `$0.134`、4K 为 `$0.24`；Batch/Flex 分别为 `$0.067`、`$0.12`。输入、thinking/text output、grounding、重试和税费还可能增加账单。
- **Quota：** [Rate limit 文档](https://ai.google.dev/gemini-api/docs/rate-limits) 明确限制按 project 执行，不按 key 叠加。实际 RPM、TPM、RPD、图像 IPM 以当前 project 页面为准。

只缺凭据时看 [Nano Banana Pro API key 获取指南](https://blog.laozhang.ai/zh/posts/how-to-get-nano-banana-pro-api-key)；卡在 429 或容量时看 [Nano Banana Pro quota 提升指南](https://blog.laozhang.ai/zh/posts/increase-nano-banana-pro-api-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 张高保真图片限制。更稳妥的产品文案是“总量上限仍受类别和保真限制”。

## 按错误码保留证据

| 症状 | 第一检查 | 不要做 |
| --- | --- | --- |
| `400` unknown field | endpoint 与字段大小写 | 继续加入猜测参数 |
| `401/403` | key owner、header、project、billing、policy | 把 Google key 发给服务商 |
| `404` model not found | 当前 Google ID 或 provider alias | 无证据退回 preview ID |
| `429` | project/model 的实时限制与流量形状 | 用多个 key 绕 project quota |
| 有文本无图片 | response type、output/steps 或 response parts | 不看原始返回就判模型宕机 |
| `503/504` | 同 route 的超时、一次退避重试、状态页和日志 | 同时换 key、model、endpoint、body |

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