DEV Community

Cover image for How to Use the Nano Banana 2.1 API
Hassann
Hassann

Posted on Originally published at apidog.com

How to Use the Nano Banana 2.1 API

Google launched Nano Banana 2.1 on October 6, 2026. It is available through the Gemini API as gemini-nano-banana-2.1. The model updates Nano Banana 2 (Gemini 3.1 Flash Image) with improved visual quality, mask-style editing, and stronger multi-turn character consistency. At shared resolutions, it costs half as much per generated image as Nano Banana 2.

Try Apidog today

This guide goes from an empty terminal to a saved image, then covers aspect ratios, 2K and 4K output, edits, multi-turn workflows, reference images, Search grounding, testing, and cost. Save each request in Apidog to compare Nano Banana 2.1 with the model you use today.

Want the background first? Read What Is Nano Banana 2.1 for what changed and what Google has not published yet.

What you need

Item Value
Base URL https://generativelanguage.googleapis.com/v1beta
Auth header x-goog-api-key: $GEMINI_API_KEY
Model ID gemini-nano-banana-2.1
Endpoint POST /v1beta/interactions
Resolutions 1K (default), 2K, 4K
Inputs Text, images (up to 14 references), video
Python SDK pip install google-genai
JavaScript SDK npm install @google/genai

All examples use the Interactions API, which is the API Google documents for Nano Banana 2.1 image generation.

Step 1: Get a Gemini API key

  1. Open Google AI Studio and sign in.
  2. Select Get API key and create a key in a Google Cloud project.
  3. Enable billing for that project. Google lists the Nano Banana 2.1 API free tier as “Not available,” so API requests require a paid project.
  4. Export the key in your shell: 
export GEMINI_API_KEY="your-key-here"
Enter fullscreen mode Exit fullscreen mode

Google links 2.1 to the AI Studio playground for prompt testing, but it has not published how much a free account can generate there. See how to use Nano Banana 2.1 for free and getting a Gemini API key for additional setup guidance.

Step 2: Generate your first image

Call the API with cURL

Send a text prompt to the Interactions endpoint:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {
        "type": "text",
        "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

The API returns JSON. Generated image data is base64-encoded in an image content block, so use an SDK or script to decode and save it.

Save the result with Python

Install the SDK:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

Then create an image and write it to disk:

from google import genai
import base64

client = genai.Client()  # Reads GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
Enter fullscreen mode Exit fullscreen mode

interaction.output_image returns the last generated image block. Its data field is base64, so decode it before writing the file.

Save the result with JavaScript

Install the SDK:

npm install @google/genai
Enter fullscreen mode Exit fullscreen mode

Create and save the image:

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
});

const image = interaction.output_image;

if (image) {
  fs.writeFileSync("nano-banana.png", Buffer.from(image.data, "base64"));
}
Enter fullscreen mode Exit fullscreen mode

Gemini 3 image models think before generating. Nano Banana 2.1 may produce up to two interim “thought images” while planning composition. These are not billed, and API users cannot disable thinking.

Step 3: Set aspect ratio, resolution, and image-only output

Use response_format to control the generated output. Setting "type": "image" returns only an image and omits conversational text, reducing response size and simplifying parsing.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A product shot of a matte black coffee grinder on a marble counter",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

Key details:

  • image_size accepts 1K, 2K, and 4K. Use an uppercase K; 2k is rejected.
  • Nano Banana 2.1 does not have a 512px tier. That option belongs to Nano Banana 2.
  • Supported aspect ratios include 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, and 8:1.
  • A 16:9 image at 2K is 2752x1536. At 4K, it is 5504x3072.
  • To request both text and an image, pass a list: 
response_format=[
    {"type": "text"},
    {"type": "image"},
]
Enter fullscreen mode Exit fullscreen mode

Step 4: Edit an existing image

To edit an image, send a base64 image block alongside a text instruction.

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

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": (
                "Using the provided image of a living room, change only the "
                "blue sofa to be a vintage, brown leather chesterfield sofa. "
                "Keep the rest of the room, including the pillows on the sofa "
                "and the lighting, unchanged."
            ),
        },
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/png",
        },
    ],
)
Enter fullscreen mode Exit fullscreen mode

Mask-style inpainting without a mask file

Nano Banana 2.1 does not use a separate mask upload. Instead, define the edit region with your prompt.

Using the provided image, change only the [specific element] to [new element/description]. Keep everything else in the image exactly the same, preserving the original style, lighting, and composition.

For reliable edits:

  1. Name one specific element.
  2. Describe the replacement concretely.
  3. Explicitly state which visual properties must remain unchanged.

For example, “make the sofa nicer” can cause a full-room redraw. “Change only the blue sofa to a brown leather chesterfield; keep pillows, lighting, walls, and composition unchanged” constrains the edit.

Step 5: Iterate with multi-turn editing

For successive edits, pass the previous interaction ID as previous_interaction_id. Send only the next requested change.

interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Update this infographic to be in Spanish. Do not change any other elements of the image.",
    previous_interaction_id=interaction.id,
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

With REST, include the same field in the request body:

{
  "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>"
}
Enter fullscreen mode Exit fullscreen mode

This workflow benefits from Nano Banana 2.1’s improved multi-turn character consistency: characters and products should remain recognizable over several edit rounds.

Step 6: Combine up to 14 reference images

Add additional image blocks to the input array. For Nano Banana 2.1, Google documents support for up to:

  • 10 high-fidelity object images
  • 4 character images
  • 14 reference images total 
interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": "An office group photo of these people, they are making funny faces.",
        },
        {"type": "image", "data": person_1_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_2_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_3_b64, "mime_type": "image/png"},
    ],
    response_format={
        "type": "image",
        "aspect_ratio": "5:4",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

Reference images count as input tokens. Nano Banana 2.1 input costs three times as much as Nano Banana 2 input, so measure reference-heavy workflows before migrating.

Step 7: Ground images with Google Search

For prompts that depend on current information, such as recent events or weather data, add the Google Search tool.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A detailed painting of a Timareta butterfly resting on a flower",
    tools=[
        {
            "type": "google_search",
            "search_types": ["web_search", "image_search"],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Using only this tool configuration enables web search:

{"type": "google_search"}
Enter fullscreen mode Exit fullscreen mode

Adding image_search allows the model to use web images as visual context. This is supported by Nano Banana 2.1 and Nano Banana 2.

Important constraints:

  • Grounding cannot use real-world images of people from Search.
  • If you display grounded output to users, Google requires displaying the search_suggestions returned in the google_search_result step.

Step 8: Test the request in Apidog

Scripts are useful for generation, but saved requests are faster for validating prompts, credentials, and model behavior. In Apidog:

  1. Create an environment and add a GEMINI_API_KEY variable.
  2. Create a request: 
   POST https://generativelanguage.googleapis.com/v1beta/interactions
Enter fullscreen mode Exit fullscreen mode
  1. Add this header: 
   x-goog-api-key: {{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode
  1. Add a JSON request body containing model, input, and response_format.
  2. Click Send.
  3. Add this post-response script to verify both the status code and image output: 
pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("response contains an image block", () => {
  const steps = pm.response.json().steps || [];

  const hasImage = steps.some((s) =>
    s.type === "model_output" &&
    (s.content || []).some((c) => c.type === "image" && c.data)
  );

  pm.expect(hasImage).to.be.true;
});
Enter fullscreen mode Exit fullscreen mode
  1. Duplicate the request and change the model ID to gemini-3.1-flash-image.
  2. Send both requests with the same prompt.

You now have a repeatable side-by-side comparison of Nano Banana 2.1 and Nano Banana 2, including status, timing, and response size. For a broader comparison, see Nano Banana 2.1 vs Nano Banana 2 vs Pro.

What it costs

Paid-tier pricing from Google’s pricing page on October 7, 2026:

Model Input / 1M 1K image 2K image 4K image Batch 1K
Nano Banana 2.1 $1.50 $0.0336 $0.0504 $0.0756 $0.0168
Nano Banana 2 $0.50 $0.067 $0.101 $0.151 $0.034
Nano Banana Pro $2.00 $0.134 $0.134 $0.24 $0.067

For Nano Banana 2.1:

  • Image output costs $30 per 1M tokens.
  • A 1K image uses 1,120 tokens.
  • A 2K image uses 1,680 tokens.
  • A 4K image uses 2,520 tokens.
  • Text and thinking output costs $7.50 per 1M tokens.
  • Search grounding includes 5,000 free monthly requests shared across Gemini 3.x models, then costs $14 per 1,000 requests.

Worked example: 1,000 product images at 2K

Assume short prompts of about 100 input tokens each.

  • Output: 1,000 × $0.0504 = $50.40
  • Input: 100,000 × $1.50 / 1,000,000 = $0.15
  • Total: approximately $50.55, plus any thinking-text tokens

The same job on Nano Banana 2 costs about $101.

With the Batch API, Nano Banana 2.1’s 2K price drops to $0.0252 per image. The output cost for 1,000 images drops to $25.20 if you can wait. Batch jobs trade turnaround times of up to 24 hours for higher rate limits.

For more detail, see the Nano Banana 2 API pricing breakdown.

Common errors

These are generic Gemini API behaviors, not Nano Banana 2.1-specific errors.

Error Likely cause Fix
400 INVALID_ARGUMENT Lowercase image_size, unsupported ratio, malformed input Use 2K, not 2k; validate the ratio and request shape
403 PERMISSION_DENIED Invalid key or billing is not enabled Check the key and enable billing
404 NOT_FOUND Incorrect model ID Use gemini-nano-banana-2.1 exactly
429 RESOURCE_EXHAUSTED Rate limit reached Use backoff and retry, or use Batch
500 / 503 Temporary server issue Retry with exponential backoff
200 but no image Prompt blocked or text-only output Set "type": "image" and rephrase the prompt

FAQ

Is there a free tier for the Nano Banana 2.1 API?

No. Google lists the API free tier as “Not available.” The AI Studio playground links to 2.1, but Google has not published a free limit for it.

Is Nano Banana 2.1 a drop-in replacement for Nano Banana 2?

Mostly. Change the model ID to gemini-nano-banana-2.1. However, 2.1 removes the 512px tier and has higher input-token pricing, so evaluate reference-heavy edit workflows before switching.

Do generated images carry a watermark?

Yes. All outputs include a SynthID watermark.

Can I generate an image from a video?

Yes. Nano Banana 2.1 accepts a video input block, such as a YouTube URL, alongside the text prompt.

Does the old Nano Banana 2 API guide still apply?

The core concepts still apply. See the Nano Banana 2 API guide for the earlier model.

Wrap-up

Nano Banana 2.1 promises improved images at half of Nano Banana 2’s per-image price while retaining the same Interactions API shape.

Start with a billed Gemini API key, generate one image, and save the request in Apidog with status and image assertions. Then duplicate the request, switch to the older model ID, and compare both models using the same prompts.

Top comments (0)