# Gemini Image API Guide: Python Code, 3 Current Models, Pricing > As of October 5, 2026, the Gemini image API runs on three models, from $0.0336 per image. Image output has no free tier: you need a paid key with $5 prepaid. - URL: https://blog.laozhang.ai/en/posts/gemini-image-api-guide-2026 - Published: 2026-03-16 - Updated: 2026-10-05 - Author: LaoZhang AI Team (https://blog.laozhang.ai/en/about) - Topic: API Guides - Tags: Gemini API, Nano Banana 2, Nano Banana Pro, Image Generation, Python --- 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](https://ai.google.dev/gemini-api/docs/image-understanding). ## 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. | Model | Model ID | Output sizes | Standard price per image | Good fit | |---|---|---|---|---| | Nano Banana 2 Lite | `gemini-3.1-flash-lite-image` | 1K only | $0.0336 | High-volume, single-shot generation | | Nano Banana 2 | `gemini-3.1-flash-image` | 0.5K, 1K, 2K, 4K | $0.045–$0.151 | Default choice; editing, multiple references, text in images | | Nano Banana Pro | `gemini-3-pro-image` | 1K, 2K, 4K | $0.134 (1K/2K), $0.24 (4K) | Hard layouts, brand consistency, dense text, final assets | Prices are from Google's [Gemini API pricing page](https://ai.google.dev/gemini-api/docs/pricing) 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](https://ai.google.dev/gemini-api/docs/deprecations). Nano Banana 2 and Nano Banana Pro have no announced shutdown date. ![Current Gemini image model choices: Nano Banana 2 Lite, Nano Banana 2 and Nano Banana Pro with sizes and Standard image prices](https://blog.laozhang.ai/posts/en/gemini-image-api-guide-2026/img/image-model-task-selection.webp) If you are still deciding between the Gemini app, Google AI Studio and the API, the [Gemini image generation guide](https://blog.laozhang.ai/en/posts/gemini-image-generation-complete-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](https://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](https://ai.google.dev/gemini-api/docs/available-regions). 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](https://ai.google.dev/gemini-api/docs/billing) 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](https://blog.laozhang.ai/en/posts/gemini-image-api-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`. ```python 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. ```python 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`: ```bash 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: ```python 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](https://ai.google.dev/api/generate-content). ## 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. | Model | Sizes | Aspect ratios | Example pixels | |---|---|---|---| | Nano Banana 2 Lite | 1K | 10: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | 1:1 at 1K = 1024x1024 | | Nano Banana 2 | 0.5K, 1K, 2K, 4K | The same 10, plus 1:4, 4:1, 1:8, 8:1 | 1:1 at 4K = 4096x4096; 4:1 at 4K = 8192x2048 | | Nano Banana Pro | 1K, 2K, 4K | The same 10 as Lite | 16:9 at 4K = 5504x3072; 16:9 at 2K = 2752x1536 | 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](https://blog.laozhang.ai/en/posts/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: | Model | Object images | Character images | Style references | |---|---|---|---| | Nano Banana 2 Lite | Up to 14 | Not supported | Not supported | | Nano Banana 2 | Up to 10 | Up to 4 | Not supported | | Nano Banana Pro | Up to 6 | Up to 5 | Up to 3 | 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](https://blog.laozhang.ai/en/posts/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: | Model and size | Standard | Batch | |---|---|---| | Nano Banana 2 Lite, 1K | $0.0336 | $0.0168 | | Nano Banana 2, 0.5K | $0.045 | $0.022 | | Nano Banana 2, 1K | $0.067 | $0.034 | | Nano Banana 2, 2K | $0.101 | $0.050 | | Nano Banana 2, 4K | $0.151 | $0.076 | | Nano Banana Pro, 1K or 2K | $0.134 | $0.067 | | Nano Banana Pro, 4K | $0.24 | $0.12 | 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](https://blog.laozhang.ai/en/posts/nano-banana-2-api-pricing-guide), [Gemini 3 Pro Image API pricing](https://blog.laozhang.ai/en/posts/gemini-3-pro-image-api-pricing), [when Batch pays off for Pro](https://blog.laozhang.ai/en/posts/nano-banana-pro-batch-api-cost-optimization) and a [side-by-side of Lite, Nano Banana 2 and Pro](https://blog.laozhang.ai/en/posts/nano-banana-api-pricing-free-vs-pro). ![Conceptual paid-key image workflow through Interactions output_image, with the alternate generateContent inlineData response path](https://blog.laozhang.ai/posts/en/gemini-image-api-guide-2026/img/request-to-usable-image.webp) A third-party gateway is a different trade-off. [LaoZhang API](https://docs.laozhang.ai/en/api-capabilities/nano-banana-image) 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](https://blog.laozhang.ai/en/about#laozhang). 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](https://ai.google.dev/gemini-api/docs/rate-limits) 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 | What you see | What it means | What to do | |---|---|---| | HTTP 402 Payment Required | Prepaid balance on the billing account is $0 | Add credits or set up auto-reload | | HTTP 429 `RESOURCE_EXHAUSTED` | A rate limit or spend-based limit was hit | Back off and retry, then check limits in AI Studio | | Request rejected as invalid | A field value the model doesn't accept, such as a lowercase size or `imageConfig` on a model without image output | Fix the request; retrying won't help | | `promptFeedback.blockReason` set, no candidates | The prompt was blocked: `SAFETY`, `OTHER`, `BLOCKLIST`, `PROHIBITED_CONTENT` or `IMAGE_SAFETY` | Read the reason before you resend anything | | `finishReason` other than `STOP`, no image | The output was stopped: `IMAGE_SAFETY`, `IMAGE_PROHIBITED_CONTENT`, `IMAGE_OTHER`, `NO_IMAGE`, `SPII` and others | Same; `NO_IMAGE` means an image was expected but none was produced | 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](https://blog.laozhang.ai/en/posts/nano-banana-2-blockreason-other) and [what the safety filters let you change](https://blog.laozhang.ai/en/posts/nano-banana-pro-safety-filters). 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](https://blog.laozhang.ai/en/posts/vertex-ai-nano-banana-api) covers model IDs and setup there. ### Can I use the Gemini image API from any country? No. Google publishes a [list of supported regions](https://ai.google.dev/gemini-api/docs/available-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.