# Gemini 3.1 Flash Image（Nano Banana 2）API 接入教程：价格、代码与国内接入方案

> Gemini 3.1 Flash Image（Nano Banana 2）完整API接入教程，含Python/Node.js代码示例、官方定价解析、国内中转方案对比，5分钟快速上手AI图片生成。

- Source: https://www.aifreeapi.com/zh/posts/gemini-flash-image-api-guide
- Language: zh
- Published: 2026-03-08
- Updated: 2026-10-20
- Publisher: AI Free API (https://www.aifreeapi.com)

Gemini 3.1 Flash Image（代号 Nano Banana 2）是 Google 主打速度和成本的 AI 图片生成模型：预览版于 2026 年 2 月 26 日发布，正式版 `gemini-3.1-flash-image` 于 2026 年 5 月 28 日推出，定位是用 Flash 级速度提供接近 Pro 的图片质量。它已不是 Google 最新的图片模型：Google 的弃用页列出 2026 年 10 月 6 日发布的 [Nano Banana 2.1](/zh/posts/nano-banana-2-1)（`gemini-nano-banana-2.1`）作为 NB2 的推荐替代，NB2 本身截至 2026 年 10 月 20 日仍未公布停用日期。本文将从 API 接入、价格解析、国内方案到生产实践，为中文开发者提供一站式完整指南——官方 1K 图片定价 $0.067/张，批处理减半（Gemini API 定价页，截至 2026 年 10 月 20 日）。

## Gemini 3.1 Flash Image（Nano Banana 2）到底是什么

Google 在 2026 年 2 月 26 日发布了 Gemini 3.1 Flash Image 的预览版（Preview），2026 年 5 月 28 日推出正式版，内部代号 Nano Banana 2（简称 NB2）。这个命名延续了 Google AI 团队的水果代号传统——上一代 Gemini 3 Pro Image 的代号是 Nano Banana Pro。NB2 的核心定位非常清晰：用 Flash 级别的速度和成本，提供接近 Pro 级别的图片生成质量。对于大多数商业场景而言，这意味着你可以用一半的价格（1K 每张 $0.067，Pro 为 $0.134），获得接近的视觉效果，生成速度也更快。

从技术架构来看，NB2 基于 Gemini 3.1 Flash 模型的多模态能力构建，模型 ID 为 `gemini-3.1-flash-image`（发布时的 `gemini-3.1-flash-image-preview` 已于 2026 年 6 月 25 日停用，正式版价格不变）。它不是一个独立的图片生成模型，而是一个能够同时理解文本和图片、并原生输出图片的多模态大模型。这意味着你可以在同一个 API 调用中完成文本对话和图片生成，不需要切换不同的端点或模型。这种"原生多模态"的设计也让它能在生成时直接处理提示词里要求出现的文字内容。

NB2 在 Gemini 生态中扮演着"性价比之王"的角色。如果你之前一直在用 [Nano Banana Pro（Gemini 3 Pro Image）](/zh/posts/nano-banana-2-vs-nano-banana-pro)进行图片生成，NB2 为你提供了一个更经济的选择：速度更快、成本更低，而质量差距在大多数使用场景中几乎不可感知。Google 官方的定位也很明确——NB2 适合批量处理、快速迭代和成本敏感的场景，而 Pro 则面向对细节和质量有极致要求的专业用户。对于绝大多数开发者来说，NB2 就是你需要的那个模型。

## Nano Banana 2 核心特性与 Pro 对比

![Nano Banana 2 与 Nano Banana Pro 核心指标量化对比图](https://www.aifreeapi.com/posts/zh/gemini-flash-image-api-guide/img/content-1.png)

选择 NB2 还是 Nano Banana Pro，是很多开发者面临的第一个决策。与其罗列功能清单，不如直接看数据——下面的价格与规格来自 Google 官方文档（Gemini API 定价页，截至 2026 年 10 月 20 日）；速度和文字渲染缺少可复核的公开测试数据，只做定性比较。

在生成速度方面，NB2 按 Flash 级定位设计，通常比 Pro 更快；但单张耗时受分辨率、提示词复杂度、思考级别和服务负载影响，"NB2 4-6 秒、Pro 8-12 秒"这类数字没有公开的测试方法和样本，不宜直接用来估算批量任务时长。需要排期时，先用自己的提示词在目标分辨率下各跑一批（例如 20 次），记录从发出请求到收到完整图片的时间，再按中位数估算。在价格方面，NB2 每张 1K 图片的成本是 $0.067，而 Pro 同分辨率需要 $0.134，整整便宜了一半。

文字渲染能力是衡量图片生成模型质量的关键指标之一。两者的文字渲染准确率缺少统一测试方法和样本的公开数据，不能直接比较百分比。按 Google 对两者的定位，Pro 面向对细节要求更高的场景；小字号文字、密集排版和多语言混排最容易暴露差距。如果你的应用依赖这些，用同一组提示词分别生成并逐字核对，再决定用哪个模型；只是标题、短标语这类大字，NB2 通常够用。

两者在功能支持上也有一些差异值得关注。NB2 支持超过 15 种宽高比，从传统的 1:1、16:9 到竖版的 9:16 都可以自由选择，而 Pro 主要支持标准比例。在搜索增强方面，NB2 同时支持 Web 搜索和图片搜索增强（Google Search grounding），而 Pro 仅支持 Web 搜索。两者都支持最多 14 张参考图作为输入，最高分辨率都可达 4K（4096px）。Arena（原 Chatbot Arena）的文生图名次随投票持续变化，发布时的名次不能代表现在，需要参考时以 Arena 当日榜单为准。

**选型建议非常简单**：如果你追求速度快、成本低、批量处理，选 NB2；如果你对文字渲染精度有极致要求，或者需要最高质量的广告素材、产品摄影级图片，选 Pro。对于多数常规场景，NB2 是更优的选择。更详细的对比数据可以参考我们之前的深度评测文章——[Nano Banana 2 与 Pro 的详细对比](/zh/posts/nano-banana-2-vs-nano-banana-pro)。

## 价格与成本深度解析

![Nano Banana 2 各分辨率价格对比图表展示官方、批处理和中转平台费用差异](https://www.aifreeapi.com/posts/zh/gemini-flash-image-api-guide/img/content-2.png)

理解 NB2 的定价机制，是控制成本的第一步。与传统的按张计费不同，Gemini Flash Image 采用 token 计费模型——输入和输出分别按 token 数量计费，而图片输出的 token 数量取决于分辨率。这个机制初看可能有点复杂，但一旦理解了，就能精确预测每次调用的成本（Gemini API 定价页，截至 2026 年 10 月 20 日）。

### Token 计费机制详解

NB2 的计费分为三个部分：输入 token（$0.50/百万 tokens）、文本输出 token（$3.00/百万 tokens）和图片输出 token（$60.00/百万 tokens）。图片输出的 token 价格是文本输出的 20 倍，这也是为什么图片生成的主要成本来自输出环节。不同分辨率的图片消耗的 token 数量不同：512px 图片消耗 747 tokens，1024px 消耗 1120 tokens，2048px 消耗 1680 tokens，4096px 消耗 2520 tokens。

将这些数字换算成每张图片的实际成本，结果如下表所示。需要注意的是，这里只计算了图片输出的 token 费用——输入 prompt 通常只有几十到几百个 token，成本可以忽略不计。

| 分辨率 | 输出 Tokens | 官方单价 | 批处理（-50%） |
|--------|------------|---------|---------------|
| 512px (0.5K) | 747 | $0.045 | $0.022 |
| 1024px (1K) | 1,120 | $0.067 | $0.034 |
| 2048px (2K) | 1,680 | $0.101 | $0.050 |
| 4096px (4K) | 2,520 | $0.151 | $0.076 |

批处理价按 token 原值计算，再四舍五入到 0.001 美元：批处理图片输出为 $30/百万 tokens，747 × $30 ÷ 1,000,000 ≈ $0.022，1,120 × $30 ÷ 1,000,000 ≈ $0.034，1,680 × $30 ÷ 1,000,000 ≈ $0.050，2,520 × $30 ÷ 1,000,000 ≈ $0.076，与定价页列出的批处理单价一致。

从表中可以清楚地看到，Google 官方提供了一个批处理（Batch API）折扣方案，价格直接打五折。如果你的场景不需要实时响应——比如每晚批量生成第二天需要的营销图片——批处理是官方渠道中最划算的选择。不过批处理有延迟限制，不适合需要即时交互的场景。

对于国内开发者来说，中转平台是另一种付费方式。laozhang.ai 等中转平台按自己的规则定价（有的按张统一计价，有的按 token 折算），价格经常调整，下单前请以平台价格页为准，并和上表的官方单价、批处理价对比。

### 成本优化策略

在实际项目中，有几个经过验证的策略可以有效控制成本。首先是分辨率选择策略：如果图片最终用于社交媒体或网页展示（通常不超过 1200px），选择 1K 分辨率即可，不需要 4K。1K 图片的视觉质量对于大多数屏幕显示场景已经足够。其次是利用 NB2 的多模态特性，在同一个对话中连续生成多张图片，这样输入 context 的 token 可以复用，减少重复的 prompt 开销。最后，对于非实时场景，优先使用批处理 API——同样的图片质量，成本直接减半。关于免费使用方案，可以参考我们的[Gemini 3.1 Flash Image 免费 API 使用方案](/zh/posts/nano-banana-2-free)。

## API 接入实战教程（5分钟上手）

接入 NB2 的 API 非常简单——你需要一个 Google AI API Key，然后通过标准的 Gemini API 发送请求即可。整个过程不超过 5 分钟。下面分别展示 Python、Node.js 和 curl 三种方式。

**获取 API Key**

在开始之前，你需要前往 [Google AI Studio](https://aistudio.google.com/) 创建一个 API Key。登录 Google 账号后，点击左侧的"Get API key"按钮，选择"Create API key in new project"即可。请注意，NB2 的正式版 `gemini-3.1-flash-image` 自 2026 年 5 月 28 日起可用，原预览版已于 2026 年 6 月 25 日停用；截至 2026 年 10 月 20 日，定价页上它的免费层仍为"不可用"——你需要开通付费的 Gemini API 计划才能调用。获取到的 API Key 格式类似 `AIzaSy...`，请妥善保存。

### Python 代码示例

Python 是最主流的接入方式。使用 Google 官方的 `google-genai` SDK，几行代码就能生成图片。下面是一个完整的、可直接运行的示例，包括了图片保存和错误处理：

```python
import os
import base64
from google import genai

# 初始化客户端
client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))

# 生成图片
response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents="一只橘猫坐在窗台上看日落，水彩风格",
    config=genai.types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],  # 同时返回文本和图片
    ),
)

# 处理响应
for part in response.candidates[0].content.parts:
    if part.inline_data:  # 图片数据
        image_bytes = base64.b64decode(part.inline_data.data)
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"图片已保存，格式: {part.inline_data.mime_type}")
    elif part.text:  # 文本描述
        print(f"模型回复: {part.text}")
```

这段代码的关键点在于 `response_modalities=["TEXT", "IMAGE"]` 这个参数——它告诉模型同时返回文本和图片。如果你只需要图片，可以设为 `["IMAGE"]`。响应中的图片数据以 base64 编码的 PNG 格式返回，解码后直接保存即可。

### Node.js 代码示例

如果你的项目基于 Node.js，可以使用 `@google/genai` 官方 SDK。下面是等效的 Node.js 实现：

```javascript
import { GoogleGenAI } from "@google/genai";
import fs from "fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

async function generateImage() {
  const response = await ai.models.generateContent({
    model: "gemini-3.1-flash-image",
    contents: "一只橘猫坐在窗台上看日落，水彩风格",
    config: { responseModalities: ["TEXT", "IMAGE"] },
  });

  for (const part of response.candidates[0].content.parts) {
    if (part.inlineData) {
      const buffer = Buffer.from(part.inlineData.data, "base64");
      fs.writeFileSync("output.png", buffer);
      console.log(`图片已保存，格式: ${part.inlineData.mimeType}`);
    } else if (part.text) {
      console.log(`模型回复: ${part.text}`);
    }
  }
}

generateImage().catch(console.error);
```

### curl 命令行

对于快速测试或集成到 Shell 脚本中，curl 是最直接的方式。下面的命令会发送请求并将返回的图片保存到本地：

```bash
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "一只橘猫坐在窗台上看日落，水彩风格"}]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
for part in data['candidates'][0]['content']['parts']:
    if 'inlineData' in part:
        with open('output.png', 'wb') as f:
            f.write(base64.b64decode(part['inlineData']['data']))
        print('图片已保存为 output.png')
"
```

这三种方式的核心调用逻辑完全相同——发送文本 prompt，接收包含图片数据的 JSON 响应。选择哪种取决于你的技术栈。值得注意的是，NB2 支持在 prompt 中传入参考图片，可以实现图片编辑、风格迁移等高级功能——这些会在后面的高级特性章节中详细介绍。

## 国内开发者接入方案详解

![三种国内接入方案对比：官方直连、中转平台和自建代理的全面比较](https://www.aifreeapi.com/posts/zh/gemini-flash-image-api-guide/img/content-3.webp)

对于国内开发者来说，直接调用 Google 的 API 面临网络障碍是绑不开的现实问题。目前主流的解决方案有三种：官方直连（需要科学上网）、中转平台和自建代理。每种方案各有优劣，适合不同的使用场景和技术能力。

### 方案一：官方直连

官方直连是最直接的方式——在有稳定网络环境的服务器上直接调用 `generativelanguage.googleapis.com`。优点是价格最低（直接享受官方定价）、延迟最小、数据不经过第三方。缺点也很明显：需要海外服务器或稳定的网络通道，不支持国内支付方式（需要国际信用卡），而且网络波动可能导致请求超时。如果你的团队已经有海外服务器基础设施，或者是个人开发者有稳定的网络方案，官方直连是成本最低的选择。

### 方案二：中转平台（推荐）

中转平台是目前国内开发者最主流的选择。这类平台在海外部署服务器，将 Google API 的请求转发给国内用户，同时提供中文技术支持。以 laozhang.ai 为例，接入步骤非常简单——只需要将 API 的 base URL 从 Google 官方地址替换为中转地址，其他代码完全不用改动。

使用 laozhang.ai 中转接入 NB2 的 Python 示例如下：

```python
from openai import OpenAI

# 使用 OpenAI 兼容格式调用
client = OpenAI(
    api_key="your-laozhang-api-key",  # 在 laozhang.ai 获取
    base_url="https://api.laozhang.ai/v1"
)

response = client.chat.completions.create(
    model="gemini-3.1-flash-image",  # 平台目录截至 2026-10-20 仍保留 -preview 名称
    messages=[
        {"role": "user", "content": "一只橘猫坐在窗台上看日落，水彩风格"}
    ],
)
print(response.choices[0].message.content)
```

中转平台的核心优势是**零配置接入**——不需要科学上网，不需要国际信用卡，不需要搭建任何基础设施。而且由于支持 OpenAI 兼容格式，如果你的项目之前已经集成了 OpenAI 的 SDK，只需要改一行 base URL 就能切换到 NB2。价格以各平台当前价格页为准。更多中转渠道的对比可以参考[最便宜的 Gemini Flash Image API 渠道](/zh/posts/cheapest-gemini-flash-image-preview-api)。

### 方案三：自建代理

自建代理适合对数据隐私有严格要求的企业用户。方案是在海外（如新加坡、日本）购买一台云服务器，部署 Nginx 反向代理，将请求转发到 Google API。这样数据只经过你自己的服务器，不经过任何第三方。代价是你需要承担服务器成本（通常 $5-20/月）、运维负担，以及可能的 IP 封禁风险。

对于大多数开发者来说，中转平台在易用性、成本和稳定性之间取得了最好的平衡。如果你的月调用量不高（几千到几万次），中转平台几乎是最优选择。如果月调用量达到百万级别以上，可以考虑自建代理来进一步降低单次调用成本。关于国内代理方案的更多细节，我们在[Gemini API 国内代理完整方案](/zh/posts/gemini-api-china-proxy)中有详细说明。

## 生产环境最佳实践

从 Demo 到生产环境的跨越，往往不在于 API 调用本身，而在于错误处理、并发控制和成本监控这些"周边"能力。下面是经过实际项目验证的最佳实践，帮助你构建一个稳定可靠的图片生成服务。

### 错误处理与重试策略

NB2 的 API 可能返回多种错误类型：429（速率限制）、500（服务器内部错误）、503（服务不可用）。对于这些可重试的错误，建议使用指数退避策略——第一次失败后等 1 秒，第二次等 2 秒，第三次等 4 秒，最多重试 3 次。对于 400（请求格式错误）或 403（认证失败）这类不可重试的错误，应该立即抛出异常而不是反复重试。下面是一个实用的重试封装：

```python
import time
import random

def generate_with_retry(client, prompt, max_retries=3):
    """带指数退避的图片生成"""
    for attempt in range(max_retries):
        try:
            response = client.models.generate_content(
                model="gemini-3.1-flash-image",
                contents=prompt,
                config={"response_modalities": ["TEXT", "IMAGE"]},
            )
            return response
        except Exception as e:
            error_code = getattr(e, 'code', None)
            if error_code in [400, 403, 404]:
                raise  # 不可重试的错误，立即抛出
            if attempt < max_retries - 1:
                wait = (2 ** attempt) + random.uniform(0, 1)
                print(f"请求失败，{wait:.1f}秒后重试... ({e})")
                time.sleep(wait)
            else:
                raise  # 重试耗尽
```

### 并发控制

NB2 的 API 有速率限制，付费账户通常允许每分钟 60-200 次请求（具体取决于你的配额等级）。在批量生成场景中，如果不做并发控制，很容易触发 429 错误。推荐使用信号量（Semaphore）来限制并发数。以 Python 的 `asyncio` 为例，将并发数控制在 10-20 之间是一个安全的选择——这样既能充分利用配额，又不会频繁触发限制。

同时建议在每批次任务完成后加一个短暂的冷却期（比如 1-2 秒），让 API 端的速率计数器有时间重置。这比"跑满配额然后等到下一分钟"的策略更稳定，也能获得更均匀的响应时间。如果你需要更稳定的高并发渠道，可以参考我们的[稳定的 Gemini 图片生成渠道](/zh/posts/stable-gemini-image-channel)评测。

### 成本监控

对于生产级应用，建议在每次 API 调用后记录 token 消耗量，并设置日预算上限。NB2 的响应中包含 `usage_metadata`  字段，里面有 `prompt_token_count` 和 `candidates_token_count` 的详细数据。将这些数据写入数据库或发送到监控系统（如 Prometheus/Grafana），可以实时跟踪成本趋势。一个简单但有效的做法是：设定每日预算，当累计消耗达到阈值的 80% 时触发告警，达到 100% 时自动暂停新请求。这样可以有效避免因 bug 或异常流量导致的成本失控。

## 高级特性与实战技巧

NB2 不只是一个简单的"文字转图片"工具——它支持参考图输入、搜索增强、思考模式等高级特性，掌握这些能力可以解锁更多实际应用场景。

**参考图（Image Reference）**

NB2 支持在 prompt 中同时传入最多 14 张参考图片。这个能力使得图片编辑、风格迁移和品牌一致性维护变得非常简单。比如你可以上传一张产品照片，然后让 NB2 "把这张照片改成水彩风格"或"将背景替换为沙滩场景"。参考图的传入方式是将图片以 base64 编码放在 `inline_data` 字段中，与文本 prompt 一起发送。在实际使用中，1-3 张参考图的效果最好——参考图太多反而可能让模型"困惑"，不知道该优先参考哪张。

一个特别实用的场景是品牌素材生成：上传你的品牌 Logo 和色彩标准图，然后让 NB2 基于这些参考生成不同场景的营销图片，可以确保生成的图片在视觉风格上与品牌保持一致。这在电商和社交媒体运营中非常有价值——以前需要设计师手工制作的工作，现在可以通过 API 批量完成。

### Google Search Grounding

NB2 独特支持 Google Search grounding 功能，同时覆盖 Web 搜索和图片搜索。简单来说，你可以让 NB2 在生成图片之前先搜索互联网获取最新信息，然后基于搜索结果来生成图片。比如 prompt"根据今天的天气生成一张适合的户外活动插图"——NB2 会先搜索当前天气信息，然后据此生成匹配的插图。这个特性在生成时事相关、时效性内容时特别有用。

### 分辨率与宽高比选择策略

NB2 支持 4 种分辨率（512px、1K、2K、4K）和超过 15 种宽高比组合。选择合适的分辨率和宽高比需要考虑两个因素：最终用途和成本。对于社交媒体头图（通常要求 16:9），1K 分辨率即可满足大多数平台的要求；对于印刷品或大幅海报，建议使用 2K 或 4K；对于缩略图或头像，512px 就足够了。值得注意的是，NB2 会自动选择最接近的支持宽高比——如果你请求一个非标准比例（比如 2.35:1），模型会智能调整到最接近的可用比例。在 prompt 中可以通过添加 "aspect ratio 16:9" 来指定宽高比。

**思考模式（Thinking Mode）**

NB2 还支持思考模式（thinking），有 `minimal` 和 `high` 两个级别。开启思考模式后，模型会在生成图片之前先进行推理——分析 prompt 的意图、规划构图、选择色彩方案等。这会增加一些延迟（幅度随提示词和分辨率变化），但在复杂场景下可以显著提升图片质量。推荐在需要精确构图（如"人物站在画面左三分之一处"）或复杂场景（如"日落时分的城市天际线倒映在湖面上"）时开启 `high` 思考模式，在简单场景中使用 `minimal` 或不开启。

## 常见问题与总结

**NB2 和 Nano Banana Pro 应该选哪个？** 如果你追求性价比、速度快、批量处理，选 NB2；如果你需要最高质量的广告素材和精细文字渲染，选 Pro。对于多数常规场景，NB2 是更优选择。

**国内可以直接调用 NB2 的 API 吗？** 不能直接调用 Google 的 API。推荐使用中转平台（如 laozhang.ai），只需更换 base URL 即可。API 文档参考：[docs.laozhang.ai](https://docs.laozhang.ai/)。

**NB2 有免费额度吗？** 截至 2026 年 10 月 20 日，Gemini API 定价页上 NB2（`gemini-3.1-flash-image`）的免费层仍显示"不可用"。你需要开通 Gemini API 付费计划才能使用。

**图片生成失败了怎么办？** 常见原因包括 prompt 触发安全过滤（调整措辞避免敏感内容）、请求超时（检查网络或使用中转）、速率限制（降低并发或等待后重试）。

**NB2 支持生成中文文字的图片吗？** 支持，中文文字同样可以渲染。准确率没有公开的统一测试数据，小字号和长段文字更容易出错，建议在 prompt 中明确指定文字内容、字体大小和位置，生成后逐字核对。

**总结与行动指引**：Gemini 3.1 Flash Image（Nano Banana 2）以 Flash 级速度、接近 Pro 的质量和极具竞争力的价格，成为 2026 年最值得关注的 AI 图片生成模型。对于国内开发者，通过中转平台接入是最简单高效的路径——改一行代码即可开始使用。无论你是想快速原型验证、批量生成营销素材，还是构建生产级图片生成服务，NB2 都能提供可靠的支撑。现在就开始接入吧——5 分钟的配置时间，换来的是一个强大且经济的 AI 图片生成能力。