Skip to main content

Overview

Nano Banana (codename) is Google’s image generation model series, currently with the following available versions:
  • 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-imagegemini-2.5-flash-image
  • sora_imagegemini-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

  1. Replace API Key: Replace API_KEY in code with your actual API key
  2. Modify Prompt: Modify PROMPT variable as needed
  3. Run Script: Execute Python script, image will be automatically saved locally

Price Comparison

ModelPricingAdvantage
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-1Higher-
flux-kontext-pro$0.035/imageOn par
sora_imageLowerReverse-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 PriorityWhen value is 0, content was rejected during review stage with no candidate content generated. This is the strictest rejection.

finishReason

Secondary PriorityWhen value is not STOP (like PROHIBITED_CONTENT, SAFETY), indicates rejection during generation process.

API Text Response

Rejection ExplanationWhen API returns rejection explanation text instead of image data, these explanations should be displayed to users.

Common Error Scenarios

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
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
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

1

Check candidatesTokenCount

First check usageMetadata.candidatesTokenCount, if 0 then directly indicate content review failure.
2

Check finishReason

If finishReason is not STOP, provide corresponding friendly prompts based on specific value.
3

Handle Text Response

If API returns text explanation instead of image, directly display these explanations to users to help understand rejection reason.
4

Preserve Technical Information

In development/testing environments, preserve complete API responses for debugging and troubleshooting.
Complete Error Handling DocumentationFor 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

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.
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.
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.
The model returns base64-encoded image data, typically in PNG or JPEG format. Code automatically detects format and saves to corresponding file type.
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.