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

截至 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 的图片理解文档。

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

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

价格截至 2026 年 10 月 4 日，来自 Gemini API 价格页；尺寸和比例来自图片生成指南。

已经不能再调用的图片模型，按 Google 弃用页的日期：

• 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。

拿不准选哪个，可以按任务分：批量出 1K 小图、不需要参考图，用 Lite；日常生成和改图、要 2K 或 4K，用 Nano Banana 2；海报、信息图、品牌物料这类对文字和细节要求高的，再上 Pro。三者的价格差异和适用场景在 Lite、Nano Banana 2 与 Pro 怎么选里有更细的对比，Pro 的接口细节见 Nano Banana Pro API 调用说明。

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

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

1. 用 Google 账号登录 Google AI Studio。新用户默认已有一个项目和一个 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 的结算说明里：余额用到 $0 时，这个结算账户下所有项目的 key 会同时停用，请求返回 HTTP 402，充值后恢复；充值金额 12 个月内未用完会过期，不退款；计费有大约 10 分钟的延迟，期间可能产生少量超额。Google Cloud 的 $300 免费试用额度不能用于 Gemini API 或 AI Studio。只想免费出几张图、不需要 API 的话，可以看 Gemini 图片生成 API 免费吗里列出的 Gemini 应用等免费入口。

地区和年龄也是门槛。AI Studio 要求年满 18 岁；Gemini API 的可用地区列表包括美国、日本、韩国、台湾地区和欧洲经济区等，不包括中国大陆和香港。在列表以外的地区，Google 不提供这项服务。

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

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

pip install -U google-genai

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

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 类型：

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 张参考图，各模型的分配不同（图片生成指南）：

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 下：

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 会被拒绝。

0.5K 这一档只有 Nano Banana 2 支持，generateContent 参考里写作 512。Pro 的 1K 和 2K 都按 1,120 个输出 token 计费，所以同价；4K 是 2,000 个 token。各比例下 Pro 4K 的完整像素表，以及 4K 是否值得多花钱，见 Nano Banana Pro 4K 尺寸与参数。

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

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

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

上表只算图片输出。另外还有三笔：输入（提示词和参考图，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 成本。

最低预充值的 $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 每张价格与预算和 Gemini 3 Pro Image API 定价。

无法开通 Google 付费层，或者更想按次计费时，可以考虑第三方 API 服务。以 LaoZhang API 为例，其 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 是我们自己的服务，其价格是平台报价，不是独立比较的结论。

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

Google 限流说明的规则可以归成四条：

• 限额按项目计算，不按 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 排查

没出图时，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 是什么意思和 Nano Banana Pro 安全过滤器能调什么。

从旧代码迁移：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。

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 图片生成教程。