Claude Opus 5.5 已在 SeedRouter 上线
LogoSeedRouter
全部文章

Nano Banana 2 API 使用教程：获取 Key、发送请求与拿到结果

一步步调用 Nano Banana 2 API：创建 API Key、发送 generateContent 请求、轮询任务、添加参考图，以及交给编程 Agent 执行。

以 Markdown 阅读

调用 Nano Banana 2 API 的步骤是：创建 API Key，把带 model 字段的 Google generateContent 请求体发送到一个端点，然后轮询返回的任务，直到图像 URL 就绪。同样的步骤也适用于 Nano Banana Pro 和 Nano Banana 2 Lite，只需修改 model 的值。

本教程用可运行的代码逐步讲解每一步，然后介绍如何用参考图编辑图像，以及如何把任务交给编程 Agent。

发送第一个请求前需要准备什么？

  1. 一个 API Key。 在 API Key 页面创建，并保存在你的服务端。绝不要把它放进浏览器端代码。
  2. 额度。 在账单页充值余额。额度永不过期，失败的请求不收费。
  3. 一个模型 ID。 gemini-3.1-flash-image 按每张图的固定价计费；gemini-3.1-flash-image-official 按 token 计费。选择方法见价格指南。
export SEEDROUTER_API_KEY="your-key"

如何发送 Nano Banana 2 请求？

把请求 POST 到 /v1/images/generations。请求体就是 Google 的 generateContent 结构，再加上 model：

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

响应是一个任务，而不是图像：

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

如果你已经在调用 Google 的 API，这里发送的请求体与你发给 generateContent 的完全相同。SeedRouter 不支持直接调用 /v1beta/models/...:generateContent，请使用本端点。

如何拿到生成的图像？

每隔几秒轮询一次任务，直到 status 变为 completed 或 failed。Python 示例：

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

已完成的任务在 output.data[0].url 中返回图像 URL，并附带 token 用量。设置 "responseModalities": ["TEXT", "IMAGE"] 时，模型写出的文本会在 output.text 中返回。如需长期保存，请把图像下载到你自己的存储中。

轮询时超时并不意味着出图失败。请保留任务 ID 并再次查询；提交新请求就意味着要为第二张图付费。

如何编辑图像或使用参考图？

在文本旁边添加 fileData part。每个 part 包含一个公开 URL 及其 MIME 类型：

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

Nano Banana 2 每次请求最多接受 14 个参考素材：图像、视频或 PDF，每个小于 50 MB。参考素材必须是 URL，不接受 base64 inlineData。如果某个 URL 无法拉取，任务会失败且不收费。进行后续编辑时，把之前的轮次作为 user 和 model 条目发送，并以一个新的 user 轮次结尾。

哪些参数最重要？

参数作用
imageConfig.imageSize512、1K、2K 或 4K；默认 1K
imageConfig.aspectRatio从 1:8 到 8:1 共 14 种宽高比；省略时跟随第一张参考图
responseModalities["IMAGE"] 只返回图像，["TEXT", "IMAGE"] 同时返回文本
systemInstruction固定规则，例如品牌统一风格
seed复用它可以更接近之前的结果
mediaResolution每个参考素材占用多少 token；在 Official 上越低越便宜

Nano Banana 2 API 文档列出了每个字段和限制。未知字段会在任何扣费发生之前被拒绝，Google Search grounding（tools）暂不可用。

如何让编程 Agent 调用 Nano Banana 2 API？

Claude Code、Codex 或 Cursor 这类编程 Agent 可以通过一条 shell 命令或一段简短脚本调用 API。SeedRouter 不提供 MCP 服务器或打包好的 skill；下面这段提示词就是全部的接入方式。先导出 Key，然后粘贴：

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

审批这一步很重要：Agent 花的是你的余额，所以它绝不应该自行提交请求。

常见问题

如何获取 Nano Banana 2 API Key？

登录后打开 API Key 页面并创建一个 Key。同一个 Key 可用于 Nano Banana 2、Nano Banana Pro、Nano Banana 2 Lite 以及 SeedRouter 上的其他模型。

Nano Banana 2 API 支持批量请求吗？

每张图发送一个请求，并行轮询这些任务。每个请求返回一张图，每个任务单独计费。

需要处理哪些错误？

400 表示请求体违反了某条规则，例如存在未知字段或尺寸不受支持，此时不会扣费。以 failed 结束的任务会带有错误信息，同样不收费。错误指南列出了每个错误码以及何时应该重试。

发送你的第一个请求

创建一个 Key，充值少量余额，然后运行上面的 Python 示例；也可以在 Nano Banana 2 Playground 里无需代码试用同样的请求。遇到复杂提示词时，把模型改为 gemini-3-pro-image 即可使用 Nano Banana Pro。

全部文章

相关指南