# Gemini 图片 API 调用教程：现役模型 ID、Python 代码与每张价格

> 截至 2026 年 10 月，Gemini 图像 API 只剩 3 个图片模型，图片输出没有免费层，标准价每张 $0.0336 到 $0.24，预充值 $5 即可调用。

- URL: https://blog.laozhang.ai/zh/posts/gemini-image-api-guide-2026
- Published: 2026-03-16
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: API 接入指南
- Tags: Gemini API, Gemini 图片生成, Nano Banana 2, Nano Banana Pro, google-genai, API 价格

---
截至 2026 年 10 月 5 日，Gemini API 里能生成图片的只有三个模型：Nano Banana 2 Lite（`gemini-3.1-flash-lite-image`）、Nano Banana 2（`gemini-3.1-flash-image`）和 Nano Banana Pro（`gemini-3-pro-image`）。`gemini-2.5-flash-image`、两个 `-preview` 图片模型和整个 Imagen 4 系列都已关停。图片输出没有免费层，在 Google AI Studio 给项目开通付费层、至少预充值 $5 之后，API key 才能出图；标准价从每张 $0.0336 到 $0.24 不等。

代码用的是当前的 `google-genai` SDK（`from google import genai`），旧的 `google-generativeai` 包和 `genai.GenerativeModel` 在现行文档里已经不用了。下面的示例按 Google 图片生成指南（2026 年 9 月 23 日更新）和 generateContent 接口参考整理，发布前没有用真实 key 实际运行，第一次接入请先出一张 1K 图确认返回正常。如果你要的是让 Gemini 看懂一张图、回答图里有什么，那是图片理解，用普通 Gemini 模型即可，见 Google 的[图片理解文档](https://ai.google.dev/gemini-api/docs/image-understanding?hl=zh-cn)。

## Gemini 图片 API 现役模型：3 个模型 ID，旧 ID 已关停

Google 图片指南把 Nano Banana 2 定为默认首选：速度、质量和价格最均衡，支持 4K、多张参考图和文字渲染。Lite 更快更便宜，但只出 1K 图，官方说明它不适合多张参考图输入和多轮连续修改。Pro 面向复杂指令和成品素材，默认开启思考（Thinking，会计费），能用 Google 搜索建立依据。

| 模型 | 模型 ID | 输出尺寸 | 比例 | 标准价（每张） |
|---|---|---|---|---|
| Nano Banana 2 Lite | `gemini-3.1-flash-lite-image` | 仅 1K | 10 种 | $0.0336 |
| Nano Banana 2 | `gemini-3.1-flash-image` | 0.5K、1K、2K、4K | 14 种 | $0.045–$0.151 |
| Nano Banana Pro | `gemini-3-pro-image` | 1K、2K、4K | 10 种 | $0.134（1K/2K）、$0.24（4K） |

价格截至 2026 年 10 月 4 日，来自 [Gemini API 价格页](https://ai.google.dev/gemini-api/docs/pricing)；尺寸和比例来自[图片生成指南](https://ai.google.dev/gemini-api/docs/image-generation)。

已经不能再调用的图片模型，按 Google [弃用页](https://ai.google.dev/gemini-api/docs/deprecations)的日期：

- `gemini-3-pro-image-preview`、`gemini-3.1-flash-image-preview`：2026 年 6 月 25 日关停，分别换成 `gemini-3-pro-image`、`gemini-3.1-flash-image`。
- Imagen 4 全系（`imagen-4.0-generate-001`、`-ultra-`、`-fast-`）：2026 年 8 月 17 日关停，官方替代是 `gemini-3.1-flash-image`。
- `gemini-2.5-flash-image`（第一代 Nano Banana）：2026 年 10 月 2 日关停。图片指南建议改用 Nano Banana 2 Lite；对画质要求更高、或要用多张参考图时，可以改用 Nano Banana 2。

![区分Interactions与generateContent响应后找到图片数据、保存文件并核对无图原因](https://blog.laozhang.ai/posts/zh/gemini-image-api-guide-2026/img/response-image-delivery.webp)



拿不准选哪个，可以按任务分：批量出 1K 小图、不需要参考图，用 Lite；日常生成和改图、要 2K 或 4K，用 Nano Banana 2；海报、信息图、品牌物料这类对文字和细节要求高的，再上 Pro。三者的价格差异和适用场景在 [Lite、Nano Banana 2 与 Pro 怎么选](https://blog.laozhang.ai/zh/posts/nano-banana-api-pricing-free-vs-pro)里有更细的对比，Pro 的接口细节见 [Nano Banana Pro API 调用说明](https://blog.laozhang.ai/zh/posts/nano-banana-pro-api-guide)。

## 开通 Gemini 图片 API：图片输出没有免费层，预充值 $5 起

价格页上，三个图片模型的免费层一栏都写着“Not available”。也就是说，没有绑定结算账户的 key 调不出图；不带 key、也没有 Google AI 套餐的账号，在 AI Studio 的 Playground 里选 Nano Banana 2 或 Lite 同样会提示升级。开通步骤在 AI Studio 里完成：

1. 用 Google 账号登录 [Google AI Studio](https://aistudio.google.com/)。新用户默认已有一个项目和一个 API key，需要新 key 时点 Create API key。
2. 在 API keys 页或 Projects 页，找到要用的项目，点 Billing Tier 一栏的 Set up billing，选国家、填联系信息和付款方式。
3. 按提示预充值，最低 $5。2026 年 3 月 23 日之后的新用户默认是预付费（Prepay）模式。
4. 把 key 放进环境变量：`export GEMINI_API_KEY="你的 key"`，不要写进代码仓库。

预付费有几条容易踩的规则，都写在 Google 的[结算说明](https://ai.google.dev/gemini-api/docs/billing)里：余额用到 $0 时，这个结算账户下所有项目的 key 会同时停用，请求返回 HTTP 402，充值后恢复；充值金额 12 个月内未用完会过期，不退款；计费有大约 10 分钟的延迟，期间可能产生少量超额。Google Cloud 的 $300 免费试用额度不能用于 Gemini API 或 AI Studio。只想免费出几张图、不需要 API 的话，可以看 [Gemini 图片生成 API 免费吗](https://blog.laozhang.ai/zh/posts/gemini-image-api-free)里列出的 Gemini 应用等免费入口。

地区和年龄也是门槛。AI Studio 要求年满 18 岁；Gemini API 的[可用地区列表](https://ai.google.dev/gemini-api/docs/available-regions)包括美国、日本、韩国、台湾地区和欧洲经济区等，不包括中国大陆和香港。在列表以外的地区，Google 不提供这项服务。

## 用 google-genai 生成第一张图（Interactions 写法）

Google 图片指南现在的示例全部用 Interactions 接口：`client.interactions.create()` 传入模型和提示词，返回的 `interaction.output_image.data` 是 base64 编码的图片。先安装 SDK：

```bash
pip install -U google-genai
```

`genai.Client()` 不传参数时，从环境变量 `GEMINI_API_KEY` 读取 key。最小生成示例，顺带指定了 16:9 和 2K：

```python
import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="一碗热气腾腾的牛肉面，俯拍，深色木桌，窗边自然光",
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

image = interaction.output_image
if image:
    with open("noodles.png", "wb") as f:
        f.write(base64.b64decode(image.data))
else:
    print("没有返回图片：", interaction)
```

几个要点：

- `response_format` 里只写 `{"type": "image"}` 时，只返回图片，不带说明文字；不写 `response_format`，模型默认图文都返回。想要图文都有、又要控制尺寸，可以传一个列表，如 `[{"type": "text"}, {"type": "image"}]`。
- `output_image` 取的是最后一张图。生成图文穿插的内容（比如带插图的故事）时，要遍历返回的各个步骤，便捷属性拿不全。
- 如果报 `client` 没有 `interactions` 属性，先把 `google-genai` 升级到最新版。

## 上传参考图改图：最多 14 张，按模型分配

改图就是把原图和一句修改指令一起放进 `input`。图片用 base64 传入，并标明 MIME 类型：

```python
import base64
from google import genai

client = genai.Client()

with open("product.png", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input=[
        {
            "type": "text",
            "text": "只把背景换成浅灰色摄影棚背景，产品的形状、颜色、光线和构图保持不变。",
        },
        {"type": "image", "data": source_b64, "mime_type": "image/png"},
    ],
)

if interaction.output_image:
    with open("product_studio.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))
```

继续在上一张图的基础上修改时，不必重新上传，传 `previous_interaction_id=interaction.id` 再写新指令即可。Google 给的局部修改句式是“使用提供的图片，只把 A 改成 B，其余部分保持原样，保留原来的风格、光线和构图”；想去掉什么，直接描述想要的画面（“空无一人的街道”），比写“不要车”更有效。

一次请求最多混用 14 张参考图，各模型的分配不同（[图片生成指南](https://ai.google.dev/gemini-api/docs/image-generation)）：

| 模型 | 物体参考图 | 人物一致性参考图 | 风格参考图 |
|---|---|---|---|
| Nano Banana 2 Lite | 最多 14 张 | 不支持 | 不支持 |
| Nano Banana 2 | 最多 10 张 | 最多 4 张 | 不支持 |
| Nano Banana Pro | 最多 6 张 | 最多 5 张 | 最多 3 张 |

Google 发布 Nano Banana 2 时的博客写的是“最多 5 个角色、14 个物体”，与上表的开发者文档不一致，写代码以上表为准。参考图按输入 token 计费，Pro 一张参考图约 560 个 token，约合 $0.0011。

上传的图片需要你有相应的权利。Google 的禁止使用政策不允许冒充他人欺骗、非自愿的私密图像，也不允许绕过安全过滤；另外，Nano Banana 2 用 Google 搜索建立依据时，暂不支持使用网络上的真人照片。

## generateContent 写法：用 imageConfig 设比例和尺寸

generateContent 是 Gemini 原有的接口，仍在文档中，而且有两个场景要用到它：一是需要自定义安全设置（`safetySettings`）时，Interactions 接口不支持这项；二是 Batch 批处理，官方批处理示例用的是 generateContent 的请求格式。比例和尺寸写在 `generationConfig.imageConfig` 下：

```bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "一张中秋节活动海报，标题写“月满人团圆”，暖色调"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "3:4", "imageSize": "2K"}
    }
  }' > response.json

jq -r '[.candidates[0].content.parts[] | select(.inlineData and (.thought != true))] | last | .inlineData.data' response.json \
  | base64 --decode > poster.png
```

返回的图片在 `candidates[0].content.parts` 里带 `inlineData` 的那一项。Pro 会在思考过程中生成中间图，这部分不计费；上面的 `jq` 过滤掉了标记为思考内容的部分，取最后一张。要改图时，在 `parts` 里加一项 `inline_data`（`mime_type` 加 base64 的 `data`）即可。

用 Python SDK 时对应的是 `client.models.generate_content()`，配置字段改成下划线写法，官方批处理示例里写的就是 `response_modalities`。

## image_size 与 aspect_ratio：大写 K，默认 1K

不指定时，输出 1K；比例默认跟随输入图片，没有输入图片就是 1:1。尺寸必须写大写 K，写成 `1k` 会被拒绝。

| 模型 | 可选尺寸 | 可选比例 | 4K 示例像素 |
|---|---|---|---|
| Nano Banana 2 Lite | 1K | 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 | 无 4K |
| Nano Banana 2 | 0.5K、1K、2K、4K | 上面 10 种，加 1:4、4:1、1:8、8:1 | 1:1 为 4096x4096 |
| Nano Banana Pro | 1K、2K、4K | 与 Lite 相同的 10 种 | 16:9 为 5504x3072 |

0.5K 这一档只有 Nano Banana 2 支持，generateContent 参考里写作 `512`。Pro 的 1K 和 2K 都按 1,120 个输出 token 计费，所以同价；4K 是 2,000 个 token。各比例下 Pro 4K 的完整像素表，以及 4K 是否值得多花钱，见 [Nano Banana Pro 4K 尺寸与参数](https://blog.laozhang.ai/zh/posts/nano-banana-pro-4k-guide)。

Gemini 图片 API 没有 CFG、步数、去噪强度、采样器这类扩散模型参数，也没有 Imagen 那样的 `personGeneration` 开关。画面控制靠提示词、参考图和上面两个参数。

## Gemini 图片 API 每张多少钱：$0.0336 到 $0.24，Batch 半价

截至 2026 年 10 月 4 日，Gemini API 价格页上的每张图片价格（美元）：

| 模型 | 0.5K | 1K | 2K | 4K |
|---|---|---|---|---|
| Nano Banana 2 Lite 标准 | — | $0.0336 | — | — |
| Nano Banana 2 Lite Batch | — | $0.0168 | — | — |
| Nano Banana 2 标准 | $0.045 | $0.067 | $0.101 | $0.151 |
| Nano Banana 2 Batch | $0.022 | $0.034 | $0.050 | $0.076 |
| Nano Banana Pro 标准 | — | $0.134 | $0.134 | $0.24 |
| Nano Banana Pro Batch | — | $0.067 | $0.067 | $0.12 |

上表只算图片输出。另外还有三笔：输入（提示词和参考图，Nano Banana 2 每百万 token $0.50，Pro $2）；文字和思考输出（Pro 每百万 token $12，思考默认开启）；用 Google 搜索建立依据时，Gemini 3.x 各模型每月共享 5,000 次免费搜索，超出后每 1,000 次 $14。Batch 为异步处理，目标在 24 小时内完成，适合不急着要结果的批量任务，具体怎么算更省见 [Nano Banana Pro Batch API 成本](https://blog.laozhang.ai/zh/posts/nano-banana-pro-batch-api-cost-optimization)。

最低预充值的 $5 大概能出多少张（只算图片输出，向下取整）：Lite 1K 是 5 ÷ 0.0336 ≈ 148 张；Nano Banana 2 1K 是 5 ÷ 0.067 ≈ 74 张；Pro 1K/2K 是 5 ÷ 0.134 ≈ 37 张；Pro 4K 是 5 ÷ 0.24 ≈ 20 张。付费层的提示词和输出不会被用于改进 Google 产品，这一点与免费层不同。各模型更完整的价格拆解见 [Nano Banana 2 API 每张价格与预算](https://blog.laozhang.ai/zh/posts/nano-banana-2-api-pricing-guide)和 [Gemini 3 Pro Image API 定价](https://blog.laozhang.ai/zh/posts/gemini-3-pro-image-api-pricing)。

![Pro 标准、Batch 与网关各尺寸计费对照及 Nano Banana 2 网关价](https://blog.laozhang.ai/posts/zh/gemini-image-api-guide-2026/img/pro-image-billing-routes.webp)

无法开通 Google 付费层，或者更想按次计费时，可以考虑第三方 API 服务。以 [LaoZhang API](https://docs.laozhang.ai/en/api-capabilities/nano-banana-image) 为例，其 2026 年 9 月 24 日的公开价格是 `gemini-3-pro-image` 每次 $0.09（1K、2K、4K 同价）、`gemini-3.1-flash-image` 每次 $0.055。对 Pro 4K 来说比官方标准价 $0.24 低 62.5%，计算式为 (0.24 − 0.09) ÷ 0.24；1K/2K 低约 32.8%；但如果能用官方 Batch，Pro 1K/2K 的 $0.067 反而更便宜。需要注意：尺寸和比例参数只在它的 Gemini 原生接口格式下生效，OpenAI 兼容格式固定输出 1:1 的 1K 图；返回 HTTP 200 但没有图片也按一次计费；请求最终仍由 Google 的模型处理，安全过滤规则不变。这是独立的服务，适用它自己的条款。

*说明：[laozhang.ai 是我们自己的服务](https://blog.laozhang.ai/zh/about#laozhang)，其价格是平台报价，不是独立比较的结论。*

## 限流按项目计算：图片模型另有 IPM 与消费上限

Google [限流说明](https://ai.google.dev/gemini-api/docs/rate-limits)的规则可以归成四条：

- 限额按项目计算，不按 API key。同一个项目里多建几个 key 不会多出额度。
- 图片模型除了每分钟请求数（RPM），还有每分钟图片数（IPM）；每日请求数（RPD）在太平洋时间午夜重置。
- 绑定结算后，项目从免费层升到 Tier 1 通常立即生效，之后随累计消费自动升级，后续升级在 10 分钟内生效。每个模型当前的具体限额只在 AI Studio 的限流页面显示，文档没有列出现役图片模型的数字。
- 视账户的结算记录，可能还有按消费计算的上限，以滚动 10 分钟计：Tier 1 为 $10，Tier 2 为 $50，Tier 3 为 $200。按 Pro 4K 每张 $0.24 算，Tier 1 的 $10 大约对应 10 分钟 41 张（10 ÷ 0.24 ≈ 41.7，未计输入和思考 token）。

撞上任何一项都会返回 429 `RESOURCE_EXHAUSTED`。批量任务要么控制并发、加退避重试，要么直接改走 Batch。

## 402、429 与没出图：按状态码和 finishReason 排查

| 现象 | 原因 | 处理 |
|---|---|---|
| HTTP 402 | 预付费余额为 $0，整个结算账户下的 key 全部停用 | 充值后恢复 |
| HTTP 429 `RESOURCE_EXHAUSTED` | 超出 RPM、IPM、RPD 或消费上限 | 降低并发、指数退避重试，或改用 Batch |
| 带尺寸参数的请求被拒 | `image_size` 写成了小写，或该模型不支持这个尺寸 | 用大写 K；Lite 只能 1K，0.5K 只有 Nano Banana 2 |
| 返回成功但没有图片 | 提示词或输出被拦截 | 查 `promptFeedback.blockReason` 和 `candidates[0].finishReason` |

没出图时，generateContent 的返回里有两个地方要看。提示词层面的 `promptFeedback.blockReason` 可能是 `SAFETY`、`OTHER`、`BLOCKLIST`、`PROHIBITED_CONTENT`、`IMAGE_SAFETY`；生成结果层面的 `finishReason` 可能是 `IMAGE_SAFETY`、`IMAGE_PROHIBITED_CONTENT`、`IMAGE_OTHER`、`NO_IMAGE`、`SPII`、`OTHER` 等。用 Interactions 写法时，`output_image` 为空就把整个返回对象打印出来看。

可调的安全类别（骚扰、仇恨言论、色情、危险内容）在现行 Gemini 模型上默认就是关闭的，而儿童安全等核心防护始终生效、不能调整。所以把阈值设成 `BLOCK_NONE` 或 `OFF`，通常解决不了 `IMAGE_SAFETY` 或 `OTHER`，这是根据默认值做出的推断。另外，安全设置只能在 generateContent 里改，Interactions 不支持。返回 400 和 500 的失败请求不收费，但会计入限额。

具体排查思路见 [blockReason OTHER 是什么意思](https://blog.laozhang.ai/zh/posts/nano-banana-2-blockreason-other)和 [Nano Banana Pro 安全过滤器能调什么](https://blog.laozhang.ai/zh/posts/nano-banana-pro-safety-filters)。

## 从旧代码迁移：google-generativeai、preview ID 与 Imagen

2026 年上半年之前写的 Gemini 图片代码，多数要改这几处：

1. 包名：`pip uninstall google-generativeai`，改装 `google-genai`；`import google.generativeai as genai` 换成 `from google import genai`，`genai.configure()` 加 `genai.GenerativeModel()` 换成 `client = genai.Client()`。
2. 模型 ID：去掉 `-preview` 后缀。`gemini-3-pro-image-preview` 改成 `gemini-3-pro-image`，`gemini-3.1-flash-image-preview` 改成 `gemini-3.1-flash-image`；`gemini-2.5-flash-image` 改成 `gemini-3.1-flash-lite-image` 或 `gemini-3.1-flash-image`。
3. Imagen：`imagen-4.0-*` 的 `:predict` 接口和 `sampleCount`、`personGeneration` 等参数都随模型一起停用。改用 `gemini-3.1-flash-image`，请求格式按上面的 Interactions 或 generateContent 重写。
4. 尺寸：老代码里没有尺寸参数的，默认输出 1K；需要 2K 或 4K 要显式加 `image_size` 或 `imageSize`。

如果你的项目跑在 Google Cloud 的 Vertex AI 上，按 token 计价的单价与 Gemini API 相同（Vertex AI 全球端点），但认证、配额和账单都走 Google Cloud 项目，配置方法见 [Vertex AI 调用 Nano Banana](https://blog.laozhang.ai/zh/posts/vertex-ai-nano-banana-api)。

## Gemini 图片 API 常见问题

### Gemini 图片 API 免费吗？

不免费。截至 2026 年 10 月，三个现役图片模型的免费层都不能输出图片，AI Studio 的 Playground 里用 Nano Banana 2 也要 Google AI 套餐或 API key。最低门槛是给项目预充值 $5。

### Gemini API 生成的图片有水印吗？

所有生成的图片都嵌有 SynthID 隐形水印，肉眼看不到；想确认一张图是否由 Google AI 生成，可以把它上传到 Gemini 应用里询问。Gemini 应用设置里的可见水印开关只作用于 Gemini 应用本身，与 API 无关；按 Google 发布 Nano Banana Pro 时的说明，在 AI Studio 里生成的图不加可见水印。

### Gemini 应用生成和 API 生成有什么区别？

Gemini 应用面向个人账号，不用写代码，额度按账号有没有 Google AI 套餐来定；API 按张计费，适合批量生成和接入自己的程序。只想在网页或手机上生成图片，看 [Gemini 图片生成教程](https://blog.laozhang.ai/zh/posts/gemini-image-generation-complete-guide)。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。

- [图片理解文档](https://ai.google.dev/gemini-api/docs/image-understanding?hl=zh-cn) (ai.google.dev)
- [Gemini API 价格页](https://ai.google.dev/gemini-api/docs/pricing) (ai.google.dev)
- [图片生成指南](https://ai.google.dev/gemini-api/docs/image-generation) (ai.google.dev)
- [弃用页](https://ai.google.dev/gemini-api/docs/deprecations) (ai.google.dev)
- [Google AI Studio](https://aistudio.google.com/) (aistudio.google.com)
- [结算说明](https://ai.google.dev/gemini-api/docs/billing) (ai.google.dev)
- [可用地区列表](https://ai.google.dev/gemini-api/docs/available-regions) (ai.google.dev)
- [限流说明](https://ai.google.dev/gemini-api/docs/rate-limits) (ai.google.dev)