How to use the Nano Banana 2 API: key, request and result
Use the Nano Banana 2 API step by step: create a key, send a generateContent request, poll the task, add reference images, and let a coding agent run it.
Read as MarkdownTo use the Nano Banana 2 API, create an API key, send Google's generateContent request body with a model field to one endpoint, and poll the task it returns until the image URL is ready. The same steps work for Nano Banana Pro and Nano Banana 2 Lite; only the model value changes.
This guide walks through each step with working code, then shows how to edit with reference images and how to hand the job to a coding agent.
What do you need before the first request?
- An API key. Create one on the API keys page and keep it on your server. Never put it in browser code.
- Credits. Add a balance on the billing page. Credits never expire, and failed requests are not charged.
- A model ID.
gemini-3.1-flash-imagebills a flat price per image;gemini-3.1-flash-image-officialbills tokens. See the pricing guide to choose.
export SEEDROUTER_API_KEY="your-key"How do you send a Nano Banana 2 request?
POST the request to /v1/images/generations. The body is Google's generateContent shape plus 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"}
}
}'The response is a task, not an image:
{
"id": "task_...",
"model": "gemini-3.1-flash-image",
"status": "processing",
"created_at": 1790310979
}If you already call Google's API, the body you send is the same one you would send to generateContent. Calling /v1beta/models/...:generateContent on SeedRouter directly is not supported; use this endpoint.
How do you get the image?
Poll the task every few seconds until status is completed or failed. In 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}.")A completed task has the image URL in output.data[0].url, plus token usage. With "responseModalities": ["TEXT", "IMAGE"], any text the model writes comes back in output.text. Download the image to your own storage if you need it long term.
A timeout while polling does not mean the image failed. Keep the task ID and check it again; submitting a new request means paying for a second image.
How do you edit an image or use references?
Add fileData parts next to the text. Each one is a public URL and its MIME type:
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 accepts up to 14 references per request: images, videos or PDFs, each under 50 MB. References must be URLs; base64 inlineData is not accepted. If a URL cannot be fetched, the task fails and is not charged. For a follow-up edit, send the earlier turns as user and model entries and end with a new user turn.
Which settings matter most?
| Setting | What it does |
|---|---|
imageConfig.imageSize | 512, 1K, 2K or 4K; 1K by default |
imageConfig.aspectRatio | 14 ratios from 1:8 to 8:1; follows the first reference if omitted |
responseModalities | ["IMAGE"] for the image only, ["TEXT", "IMAGE"] to also get text |
systemInstruction | Standing rules such as a house style |
seed | Reuse it to get closer to an earlier result |
mediaResolution | How many tokens each reference uses; lower is cheaper on Official |
The Nano Banana 2 API reference lists every field and limit. Unknown fields are rejected before anything is charged, and Google Search grounding (tools) is not available yet.
How do you let a coding agent use the Nano Banana 2 API?
A coding agent such as Claude Code, Codex or Cursor can call the API with a shell command or a short script. SeedRouter does not ship an MCP server or a packaged skill; this prompt is the whole integration. Export the key first, then paste:
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.The approval step matters: the agent spends your balance, so it should never submit on its own.
Frequently asked questions
How do I get a Nano Banana 2 API key?
Sign in, open the API keys page and create a key. The same key works for Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite and the other models on SeedRouter.
Does the Nano Banana 2 API support batch requests?
Send one request per image and poll the tasks in parallel. Each request returns one image, and each task is billed on its own.
What errors should I handle?
A 400 means the body broke a rule, such as an unknown field or an unsupported size, and nothing is charged. A task that ends failed carries an error message and is not charged either. The error guide lists every code and when to retry.
Send your first request
Create a key, add a small balance, and run the Python example above, or try the same request with no code in the Nano Banana 2 playground. For complex prompts, change the model to gemini-3-pro-image for Nano Banana Pro.
