Gemini Image API Guide: Python Code, 3 Current Models, Pricing

The Gemini image API is the Nano Banana family of models inside the Gemini API. As of October 5, 2026, three of them still answer requests: Nano Banana 2 Lite (gemini-3.1-flash-lite-image), Nano Banana 2 (gemini-3.1-flash-image) and Nano Banana Pro (gemini-3-pro-image). The first-generation gemini-2.5-flash-image was shut down on October 2, 2026, and the -preview IDs went away in June. Image output is not part of the free tier for any of these models, so the first step is an API key on a paid project with at least $5 prepaid. For most new projects, start with gemini-3.1-flash-image: it does 0.5K to 4K output, takes up to 14 reference images and costs $0.067 for a 1K image.

The code below follows Google's documentation as of October 5, 2026, using the current google-genai SDK. It has not been run against a live key for this guide, so treat it as a starting point and check the first response before you build on it.

One note before you start: if you want Gemini to read images (describe a photo, pull text from a screenshot, answer questions about a chart), that is a different feature. Any Gemini text model accepts images as input; Google covers it in the image understanding guide.

Which Gemini image model to use: 3 model IDs as of October 2026

All three models share one request format, so switching later means changing a single string. They differ in output sizes, reference-image limits and price.

Prices are from Google's Gemini API pricing page as of October 4, 2026. Google describes Lite as its fastest and cheapest image model but "not optimized for multiple reference inputs or multi-turn sequential editing", which is why it is a poor fit for edit loops. Pro thinks before it draws. That thinking is on by default and billed, so a Pro call costs a little more than its image price.

If your code still names any of these models, it will fail:

• gemini-2.5-flash-image (first-generation Nano Banana): shut down October 2, 2026. Google's image guide recommends moving to Nano Banana 2 Lite.
• gemini-3-pro-image-preview and gemini-3.1-flash-image-preview: shut down June 25, 2026. Drop the -preview suffix.
• imagen-4.0-generate-001, imagen-4.0-ultra-generate-001 and imagen-4.0-fast-generate-001: shut down August 17, 2026, with gemini-3.1-flash-image as the listed replacement.

The dates come from Google's deprecations page. Nano Banana 2 and Nano Banana Pro have no announced shutdown date.

If you are still deciding between the Gemini app, Google AI Studio and the API, the Gemini image generation guide compares those routes.

Is the Gemini image API free? No, a paid key needs $5 prepaid

No. On Google's pricing page, every current image model shows image output as "Not available" on the free tier. A free API key can still call text models, but image requests need a project on a paid tier. As of October 5, 2026, the AI Studio playground also locks Nano Banana 2 and Nano Banana 2 Lite behind an API key or a Google AI plan.

The setup in Google AI Studio:

1. Sign in at aistudio.google.com and create an API key. New accounts get a project and key by default. AI Studio requires you to be 18 or older and in a supported region.
2. On the Projects or API keys page, click Set up billing next to the project and link a billing account.
3. Prepay at least $5 in credits. New users default to the Prepay plan, a change Google rolled out from March 23, 2026. The move from the free tier to Tier 1 usually takes effect right away.
4. Store the key in an environment variable instead of in your code: export GEMINI_API_KEY="...".

What $5 covers at Standard prices, counting only the image itself: about 148 Lite images ($5 ÷ $0.0336), 74 Nano Banana 2 images at 1K ($5 ÷ $0.067) or 37 Pro images at 1K or 2K ($5 ÷ $0.134). Prompt, reference-image and thinking tokens come on top.

Two billing details catch people out. When the prepaid balance hits $0, every key in every project on that billing account stops at once, and requests fail with HTTP 402 Payment Required until you add credits. The $300 Google Cloud Free Trial doesn't help either: Google's billing page says it can't be used for the Gemini API or AI Studio. For the cheapest ways to test without an API, see whether the Gemini image API is free.

Generate an image in Python with client.interactions.create

Google's image guide writes its examples for the Interactions API in the google-genai SDK. Install it with pip install -U google-genai. The old google-generativeai package and genai.GenerativeModel do not appear in the current docs. genai.Client() reads the key from GEMINI_API_KEY.

import base64
from google import genai

client = genai.Client()  # uses the GEMINI_API_KEY environment variable

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="A ceramic coffee mug on a walnut desk, soft window light, product photo",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

image = interaction.output_image
if image is None:
    raise SystemExit("No image in the response; inspect it before retrying")

with open("mug.png", "wb") as f:
    f.write(base64.b64decode(image.data))

interaction.output_image holds the last image the model produced, as base64. Putting an image entry in response_format asks for the image only. Without it, the model returns text and an image together. To get both on purpose, pass a list such as [{"type": "text"}, {"type": "image"}]. If you ask for a story with several illustrations, output_image captures only the last one, and you have to walk the response steps yourself, as Google's guide shows.

The JavaScript SDK (@google/genai) uses the same shape: ai.interactions.create({ model, input, response_format }). Over REST, the request goes to POST https://generativelanguage.googleapis.com/v1beta/interactions with the key in an x-goog-api-key header.

Edit an existing image: send the photo and the instruction together

Editing uses the same call. The input becomes a list with a text part and one or more image parts, each base64-encoded with its MIME type.

import base64
from google import genai

client = genai.Client()

with open("living-room.jpg", "rb") as f:
    photo = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input=[
        {
            "type": "text",
            "text": (
                "Using the provided image, change only the sofa to a dark green "
                "velvet sofa. Keep everything else in the image exactly the same, "
                "preserving the original style, lighting, and composition."
            ),
        },
        {"type": "image", "data": photo, "mime_type": "image/jpeg"},
    ],
)

with open("living-room-edit.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

# Refine the same image in a second turn
follow_up = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Make the lighting slightly warmer. Do not change anything else.",
    previous_interaction_id=interaction.id,
)

The prompt pattern is Google's own template for targeted edits. For iterating on one image, Google recommends multi-turn editing through previous_interaction_id; the follow-up call carries only the new instruction. Without a size setting, the output follows the input image's aspect ratio. Larger files and other input methods are covered on the image understanding page linked above.

Google's guide adds a reminder for this feature: you need the rights to any image you upload, and the Prohibited Use Policy applies. That matters most for photos of other people.

The same request with generateContent and imageConfig

The older generateContent endpoint still serves the image models, and you need it in two cases. Batch mode, which costs half, works only with generateContent. Custom safetySettings are not available in the Interactions API either. Size and ratio move to generationConfig.imageConfig:

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A ceramic coffee mug on a walnut desk, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }' > response.json

The image comes back as base64 in candidates[0].content.parts[].inlineData.data, with its type in inlineData.mimeType. A short script to save it, or to show why nothing came back:

import base64, json

r = json.load(open("response.json"))
candidate = (r.get("candidates") or [{}])[0]
for part in candidate.get("content", {}).get("parts", []):
    if "inlineData" in part:
        open("mug.png", "wb").write(base64.b64decode(part["inlineData"]["data"]))
        break
else:
    print("No image:", r.get("promptFeedback"), candidate.get("finishReason"))

In Python the same endpoint is client.models.generate_content(...). Field names are listed in the generateContent reference.

Image size and aspect ratio: 1K by default, uppercase K only

Every model returns 1K unless you ask for more. Write sizes with an uppercase K ("1K", "2K", "4K"). Google's guide says lowercase values such as "1k" are rejected. With no ratio set, the output matches your input image's ratio. With no input image, you get a 1:1 square.

The generateContent reference lists 512 as the imageSize value for the 0.5K option. Only 1:1 reaches 4096x4096. Wide and tall ratios trade one side for the other, so Pro's 21:9 at 4K is 6336x2688. Every Pro size, its cost and the watermark rules are in the Nano Banana Pro 4K guide.

Reference images: up to 14, split by type

The Gemini 3 image models can mix up to 14 reference images in one request, but the split by type differs per model, according to Google's image guide:

Google's Nano Banana 2 launch post mentions "up to five characters and 14 objects". For API work, go by the guide's table above. Each reference image is billed as input tokens: on Pro, one image is 560 tokens, about $0.0011. Pro's JSON layouts, YAML configs and PDF inputs are covered in the Nano Banana Pro API guide.

Gemini image API pricing per image as of October 4, 2026

Google bills image output by tokens, and each size maps to a fixed token count, so every size has a fixed price per image:

Source: Google's pricing page as of October 4, 2026, paid tier only. On top of the image price you pay for input (text and reference images) and for text and thinking output: $3 per million tokens on Nano Banana 2 and $12 per million on Pro. Grounding with Google Search is free for 5,000 requests a month, shared across Gemini 3.x models, then $14 per 1,000. Paid-tier prompts and outputs are not used to improve Google's products.

Two worked examples. 1,000 Nano Banana 2 images at 1K cost $67 at Standard and about $33.60 in Batch (1,000 × $0.0336, which Google rounds to $0.034 per image). 1,000 Pro images at 4K cost $240 at Standard and $120 in Batch. Batch jobs target a 24-hour turnaround, so they suit catalog runs and overnight jobs, not interactive apps. Model-by-model detail: Nano Banana 2 API pricing, Gemini 3 Pro Image API pricing, when Batch pays off for Pro and a side-by-side of Lite, Nano Banana 2 and Pro.

A third-party gateway is a different trade-off. LaoZhang API lists flat per-call prices as of September 24, 2026: $0.055 for gemini-3.1-flash-image and $0.09 for gemini-3-pro-image at 1K, 2K or 4K. That is cheaper than Google's Standard rate for Pro at 4K ($0.24) and at 1K/2K ($0.134), but not cheaper than Pro in Batch ($0.067). Three conditions come with it. A call that returns HTTP 200 without an image is still charged. Size and aspect ratio can be set only on its Gemini-native route, while the OpenAI-compatible route returns 1:1 at 1K. Requests still go to Google's model, so Google's safety behavior applies unchanged. You are also signing up to a separate provider with its own terms.

Disclosure: laozhang.ai is our own service. Its prices are platform pricing, not an independent comparison.

Rate limits: per project, counted in images per minute

Gemini API rate limits apply per project, not per API key, so a second key in the same project adds no capacity. Image models get an extra limit, images per minute (IPM), on top of requests per minute and per day. Daily quotas reset at midnight Pacific time. Google's rate limits page doesn't print current numbers for the GA image models. Your actual limits are shown in AI Studio for your project and tier.

Tiers move with spend:

• Tier 1: an active linked billing account.
• Tier 2: $100 paid and 3 days since the first successful payment.
• Tier 3: $1,000 paid and 30 days since the first successful payment.

Upgrades happen automatically. Some accounts, depending on billing history, also have a spend-based limit measured over a rolling 10 minutes: $10 on Tier 1, $50 on Tier 2, $200 on Tier 3. On Tier 1 that works out to about 74 Pro images at 1K or 2K per 10 minutes ($10 ÷ $0.134), so a burst job can hit it well before any request limit. Batch jobs have their own separate limits, including 100 concurrent batch requests.

Errors: 402, 429 and responses that come back without an image

Failed 400 and 500 requests are not charged, but they still count against your quota. The adjustable safety categories (harassment, hate speech, sexually explicit, dangerous content) already default to Off on current Gemini models. Google's built-in protections, such as child safety, can't be adjusted at all. Because the adjustable filters are already off, setting BLOCK_NONE or OFF won't clear an IMAGE_SAFETY, PROHIBITED_CONTENT or OTHER result. Trying to get around the filters violates Google's Prohibited Use Policy and can lead to limits on the project. Diagnosis guides: blockReason OTHER and what the safety filters let you change.

With the Interactions API, check that output_image exists before decoding it, as in the first example. A missing image is a normal outcome you have to handle.

Moving old code off google-generativeai and retired model IDs

If you have code from 2025 or early 2026, four changes bring it up to date:

1. SDK: replace google-generativeai with google-genai. genai.configure(...) plus genai.GenerativeModel(...) becomes client = genai.Client() and either client.interactions.create(...) or client.models.generate_content(...).
2. Model IDs: gemini-3-pro-image-preview becomes gemini-3-pro-image, and gemini-3.1-flash-image-preview becomes gemini-3.1-flash-image. For gemini-2.5-flash-image, use gemini-3.1-flash-lite-image if the job is cheap single-shot images, or gemini-3.1-flash-image if it edits or uses references.
3. Imagen 4: Imagen parameters such as personGeneration have no equivalent on the Gemini image models, which have no people setting at all. Rewrite those calls in the generate format above instead of mapping parameters one by one.
4. Free-tier assumptions: any "500 requests per day for free" logic is out of date. Budget for paid calls from the first image.

Gemini image API FAQ

Do images from the Gemini API carry a watermark?

Yes, an invisible one. Google's image guide says all generated images include a SynthID watermark, and the API has no option to turn it off. The visible sparkle mark is a separate thing: it's a watermark setting inside the Gemini app, and Google's API guide mentions only SynthID.

Should I use Vertex AI instead of the Gemini API?

Use Vertex AI if your project already runs on Google Cloud and you want Google Cloud authentication and billing instead of an AI Studio key. The Nano Banana models are offered there too, and Pro's token rates on the Vertex AI Global endpoint match the Gemini API's. The Vertex AI Nano Banana API guide covers model IDs and setup there.

Can I use the Gemini image API from any country?

No. Google publishes a list of supported regions for the Gemini API and AI Studio. The United States, the EEA, the UK, Switzerland, Japan, South Korea and Taiwan are on it. Mainland China, Hong Kong and Russia are not. AI Studio also requires users to be 18 or older.