Overview
Nano Banana (codename) is Google’s image generation model series, currently with the following available versions:
Latest Version (Recommended)
Nano Banana Pro : gemini-3-pro-image-preview (🔥 Launched November 20, 2025)
Based on Gemini 3 Pro, stronger reasoning capabilities
Supports 4K high-resolution image generation (1K, 2K, 4K)
Industry-leading text rendering capabilities
Supports advanced local editing features
Previous Versions
Official Release : gemini-2.5-flash-image (Stable version, supports 10 aspect ratios)
Preview Version : gemini-2.5-flash-image-preview (⚠️ Discontinued on October 30, 2025)
🔥 November 20, 2025 Major Update : Google released Nano Banana Pro (gemini-3-pro-image-preview), a brand new image generation model based on Gemini 3 Pro! Supports 4K high-resolution output, industry-best text rendering, and advanced local editing capabilities. Generation speed about 20 seconds, significantly improved stability.
📚 Latest Documentation Feishu Complete Usage Guide - Fastest updates, supports comment interactionVisit Feishu documentation for latest tutorials, tips sharing, and Q&A. Documentation continuously updated, questions can be discussed directly in Feishu comments.
Core Advantages
🔥 Nano Banana Pro New Features :
🎯 4K High-Resolution Support : Supports 1K, 2K, 4K three resolutions, up to 4096×4096
📝 Text Rendering King : Clear and readable text in images, perfect for posters and ads
✨ Local Editing : Supports camera angle, focus, color grading, scene lighting adjustments
🧠 Smart Reasoning : Based on Gemini 3 Pro, better understanding of complex prompts
🚀 Universal Advantages :
⚡ Generation Speed : Nano Banana Pro ~20 seconds, previous version ~10 seconds
💰 Affordable Pricing : Combined with top-up bonuses, extremely cost-effective
🔄 Full Compatibility : Supports both Google native format and OpenAI compatibility mode
🎨 Google Technology : Based on Google’s latest and strongest image generation/editing technology
Calling Methods
Correct Endpoint ✅
POST /v1/chat/completions
Incorrect Endpoint ❌
POST /v1/images/generations # This endpoint not supported
Important Note : This model uses the chat completion endpoint, not the traditional image generation endpoint. This design maintains compatibility with models like gpt-4o-image and sora_image.
Compatibility Notes
If you’ve previously used the following models, simply replace the model name:
Upgrade to Latest Version
Any old version → gemini-3-pro-image-preview (🔥 Recommended, Nano Banana Pro)
Supports 4K high-resolution output
Strongest text rendering capabilities
Local editing features
Use Stable Version
gpt-4o-image → gemini-2.5-flash-image
sora_image → gemini-2.5-flash-image
Old Nano Banana → gemini-2.5-flash-image
Keep other parameters unchanged for seamless switching.
Version Selection Guide :
🔥 Need Best Quality & High Resolution → Use gemini-3-pro-image-preview (Nano Banana Pro)
⚡ Need Fast Generation → Use gemini-2.5-flash-image (~10 seconds, Nano Banana Pro ~20 seconds)
🎯 Need Text in Images → Strongly recommend gemini-3-pro-image-preview
Python Example Code
Complete Python example code with automatic local saving of base64 images:
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Gemini Image Generation - Python Version
Supports non-streaming output and automatic saving of base64 images locally
"""
import requests
import json
import base64
import re
import os
import datetime
from typing import Optional, Tuple
class GeminiImageGenerator :
def __init__ ( self , api_key : str , api_url : str = "https://api.apiyi.com/v1/chat/completions" ):
"""
Initialize Gemini Image Generator
Args:
api_key: API key
api_url: API address
"""
self .api_key = api_key
self .api_url = api_url
self .headers = {
"Content-Type" : "application/json" ,
"Authorization" : f "Bearer { api_key } "
}
def generate_image ( self , prompt : str , model : str = "gemini-2.5-flash-image" ,
output_dir : str = "." ) -> Tuple[ bool , str ]:
"""
Generate image and save locally
Args:
prompt: Image description prompt
model: Model to use
output_dir: Output directory
Returns:
Tuple[success status, result message]
"""
print ( "🚀 Starting image generation..." )
print ( f "Prompt: { prompt } " )
print ( f "Model: { model } " )
# Generate filename
timestamp = datetime.datetime.now().strftime( "%Y%m %d _%H%M%S" )
output_file = os.path.join(output_dir, f "gemini_generated_ { timestamp } .png" )
try :
# Prepare request data
payload = {
"model" : model,
"stream" : False ,
"messages" : [
{
"role" : "user" ,
"content" : prompt
}
]
}
print ( "📡 Sending API request..." )
# Send non-streaming request
response = requests.post(
self .api_url,
headers = self .headers,
json = payload,
timeout = 300
)
if response.status_code != 200 :
error_msg = f "API request failed, status code: { response.status_code } "
try :
error_detail = response.json()
error_msg += f ", error details: { error_detail } "
except :
error_msg += f ", response content: { response.text[: 500 ] } "
return False , error_msg
print ( "✅ API request successful, parsing response..." )
# Parse non-streaming JSON response
try :
result = response.json()
print ( "✅ Successfully parsed JSON response" )
except json.JSONDecodeError as e:
return False , f "JSON parsing failed: { str (e) } "
# Extract message content
full_content = ""
if "choices" in result and len (result[ "choices" ]) > 0 :
choice = result[ "choices" ][ 0 ]
if "message" in choice and "content" in choice[ "message" ]:
full_content = choice[ "message" ][ "content" ]
if not full_content:
return False , "Message content not found"
print ( f "📝 Got message content, length: { len (full_content) } characters" )
print ( "🔍 Parsing image data..." )
# Extract and save image (supports both base64 and URL)
success, message = self ._extract_and_save_images(full_content, output_file)
if success:
return True , message
else :
return False , f "Image save failed: { message } "
except requests.exceptions.Timeout:
return False , "Request timeout (300 seconds)"
except requests.exceptions.ConnectionError as e:
return False , f "Connection error: { str (e) } "
except Exception as e:
return False , f "Unknown error: { str (e) } "
def _extract_and_save_images ( self , content : str , base_output_file : str ) -> Tuple[ bool , str ]:
"""
Efficiently extract and save base64 image data
Args:
content: Content containing image data
base_output_file: Base output file path
Returns:
Tuple[success status, result message]
"""
try :
print ( f "📄 Content preview (first 200 chars): { content[: 200 ] } " )
# Use precise regex to extract base64 image data in one go
base64_pattern = r 'data:image/ ([ ^ ; ] + ) ;base64, ([ A-Za-z0-9+/= ] + ) '
match = re.search(base64_pattern, content)
if not match:
print ( '⚠️ Base64 image data not found' )
return False , "Response does not contain base64 image data"
image_format = match.group( 1 ) # png, jpg, etc.
b64_data = match.group( 2 )
print ( f '🎨 Image format: { image_format } ' )
print ( f '📏 Base64 data length: { len (b64_data) } characters' )
# Decode and save image
image_data = base64.b64decode(b64_data)
if len (image_data) < 100 :
return False , "Decoded image data too small, may be invalid"
# Set file extension based on detected format
output_file = base_output_file.replace( '.png' , f '. { image_format } ' )
os.makedirs(os.path.dirname(output_file) if os.path.dirname(output_file) else "." , exist_ok = True )
with open (output_file, 'wb' ) as f:
f.write(image_data)
print ( f '🖼️ Image saved successfully: { output_file } ' )
print ( f '📊 File size: { len (image_data) } bytes' )
return True , f "Image saved successfully: { output_file } "
except Exception as e:
return False , f "Error processing image: { str (e) } "
def main ():
"""
Main function
"""
# Configuration parameters
API_KEY = "sk-" # Replace with your actual API key
PROMPT = "a beautiful cat under the tree"
print ( "=" * 60 )
print ( "Gemini Image Generator - Python Version" )
print ( "=" * 60 )
print ( f "Start time: { datetime.datetime.now() } " )
# Create generator instance
generator = GeminiImageGenerator( API_KEY )
# Generate image
success, message = generator.generate_image( PROMPT )
print ( " \n " + "=" * 60 )
if success:
print ( "🎉 Execution successful!" )
print ( f "✅ { message } " )
else :
print ( "❌ Execution failed!" )
print ( f "💥 { message } " )
print ( f "End time: { datetime.datetime.now() } " )
print ( "=" * 60 )
if __name__ == "__main__" :
main()
Usage Steps
Replace API Key : Replace API_KEY in code with your actual API key
Modify Prompt : Modify PROMPT variable as needed
Run Script : Execute Python script, image will be automatically saved locally
Price Comparison
Model Pricing Advantage Nano Banana Pro (4K)$0.050/image (~¥0.29 with bonuses) 🔥 4K support, 17% of official price Nano Banana Pro (1K-2K)$0.050/image (~¥0.29 with bonuses) 🔥 High-res output, 30% of official price Nano Banana $0.025/image (~¥0.15 with bonuses) ⭐ Fast generation, 52% of official price gpt-image-1 Higher - flux-kontext-pro $0.035/image On par sora_image Lower Reverse-engineered model, moderate stability
Cost-effectiveness Recommendation :
Nano Banana Pro : 4K support, strongest text rendering, ultra-low pricing at 17-30% of official
Nano Banana : Fast generation (~10 seconds), 52% of official price, suitable for regular high-quality image generation
Feature Comparison
Speed Comparison
Nano Banana : Average 10 seconds
OpenAI Series : 15-30 seconds
Other Models : Varies by model
Compatibility
✅ Fully compatible with gpt-4o-image calling method
✅ Fully compatible with sora_image calling method
✅ Supports chat completion endpoint
❌ Does not support traditional image generation endpoint
API Error Handling Guide
Nano Banana Pro has strict content safety controls and may reject non-compliant requests at multiple levels. Understanding error types and handling methods helps you better diagnose issues and provide a friendly user experience.
Core Error Detection Indicators
candidatesTokenCount Highest Priority When value is 0, content was rejected during review stage with no candidate content generated. This is the strictest rejection.
finishReason Secondary Priority When value is not STOP (like PROHIBITED_CONTENT, SAFETY), indicates rejection during generation process.
API Text Response Rejection Explanation When API returns rejection explanation text instead of image data, these explanations should be displayed to users.
Common Error Scenarios
Content Review Rejection (candidatesTokenCount = 0)
Detection Condition : response.usageMetadata.candidatesTokenCount === 0Reason : Prompt or reference image contains inappropriate content (such as sexual content, violence, sensitive topics, etc.), rejected during content review stage.Recommendations :
Check prompt to ensure no sensitive content
If using reference images, ensure image content is appropriate
Avoid descriptions of violence, sexual content, or other inappropriate content
Safety Policy Rejection (finishReason abnormal)
Detection Condition : finishReason is not STOPCommon Values :
PROHIBITED_CONTENT - Prohibited content
SAFETY - Triggered safety filter
RECITATION - May involve copyright issues
MAX_TOKENS - Token limit exceeded
Recommendations :
Use healthy, positive descriptions
Avoid sensitive topics
Adjust prompt and retry
Feature Limitation Rejection
Common Situations :
Watermark Removal : Violates content policy, cannot process
Face Swap : Involves privacy and ethical issues, cannot process
Knowledge Base Limitation : Mentions future years (2026+) or unreleased products
Recommendations :
Avoid referencing future products or concepts
Use professional image editing software for special needs
Ensure requested content is within model knowledge scope (knowledge cutoff January 2025)
Error Handling Best Practices
Check candidatesTokenCount
First check usageMetadata.candidatesTokenCount, if 0 then directly indicate content review failure.
Check finishReason
If finishReason is not STOP, provide corresponding friendly prompts based on specific value.
Handle Text Response
If API returns text explanation instead of image, directly display these explanations to users to help understand rejection reason.
Preserve Technical Information
In development/testing environments, preserve complete API responses for debugging and troubleshooting.
Complete Error Handling Documentation For detailed error handling workflows, code implementation examples, and best practices, visit the complete documentation: https://xinqikeji.feishu.cn/wiki/Rslqw724YiBwlokHmRLcMVKHnRfDocumentation includes: complete error detection flowcharts, code examples for each scenario, user-friendly message templates for C-side/B-side users, and more.
FAQ
Why use chat completion endpoint instead of image generation endpoint?
To maintain compatibility with existing image generation models (like gpt-4o-image, sora_image), making it convenient for users to seamlessly switch between different image generation models.
How to switch from other image models to Nano Banana?
Simply change the model name from gpt-4o-image or sora_image to gemini-2.5-flash-image (recommended) or gemini-2.5-flash-image-preview, keeping other parameters unchanged.
What's the difference between official and preview versions?
Official version gemini-2.5-flash-image supports 10 aspect ratios and custom resolution features, while preview version gemini-2.5-flash-image-preview has fewer features but works normally. Both have identical pricing and calling methods, official version recommended.
What format are generated images?
The model returns base64-encoded image data, typically in PNG or JPEG format. Code automatically detects format and saves to corresponding file type.
Does it support image editing features?
Yes, Nano Banana supports not only image generation but also image editing features. Please refer to detailed documentation for specific usage methods.
For more technical details and use cases, check the detailed usage guide link above.