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.
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.
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.
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.
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.
Should I choose Pro version or legacy version?
Recommended for new projects: Nano Banana Pro (gemini-3-pro-image-preview)✅ Pro Version Advantages:
Supports 4K ultra-high resolution (1K, 2K, 4K)
Industry-leading text rendering quality
Advanced local editing features
Only 17-30% of official pricing
⚡ Legacy Version (gemini-2.5-flash-image) suitable for:
Budget-sensitive scenarios (~$0.025/image vs $0.050/image)
Need fast generation (10s vs 20s)
Existing project migration
How to switch from other image models to Nano Banana?
Simply change the model name from gpt-4o-image or sora_image to gemini-3-pro-image-preview (recommended Pro) or gemini-2.5-flash-image (legacy), 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.