Skip to content

NanoBanana2_User_Guide_en

Jump to bottom
zxwzxw edited this page Mar 10, 2026 · 2 revisions

NanoBanana2 User Guide (UE5)

1. Overview

NanoBanana2 is a UE5 Gemini image generation plugin with both Runtime and Editor modules:

  • NanoBanana2 (Runtime): async Blueprint nodes, generation requests/results, history/prompt library helpers, image split tools.
  • NanoBanana2Editor (Editor): full control panel UI (CN/EN switch, reference image workflow, queue, history, prompt library, split preview).

Core capabilities:

  • API key verification
  • Text-to-image and image-guided generation (multi-reference images)
  • SSE streaming generation (text/image chunks)
  • Batch queue generation
  • Prompt rewriting with retries and fallback model
  • History and prompt library management
  • Image splitting with custom ratios

2. Install and Enable

  1. Put the plugin under your project: YourProject/Plugins/NanoBanana2
  2. Open UE5, enable the plugin in Edit -> Plugins
  3. Restart the editor if needed

3. Open the Editor Panel

Open from:

  • Window -> NanoBanana2

4. Quick Start

  1. Enter your Gemini API key and verify it.
  2. Enter your prompt.
  3. Optionally add one or more reference images. Browse and Capture VP both append to the existing set.
  4. Choose model, resolution, aspect ratio, and output directory.
  5. Click generate.
  6. Result is saved automatically and added to history.

Notes:

  • Generation works even without reference images.
  • Retry is controlled by MaxRetries.

5. Panel Features

5.1 API Key and Language

  • API key visibility toggle and verification status
  • Chinese/English UI switching

5.2 Reference Images (Multi-image + Viewport Capture)

  • Multiple local reference images are supported.
  • The old read-only path textbox is removed; references are managed via buttons + tag list.
  • Browse and Capture VP append into the current reference set (no implicit clear).
  • Import from disk or reuse from history.
  • Remove specific images from the current reference set.
  • Empty reference set is valid (prompt-only generation).
  • Capture VP also records viewport pose (location/rotation/FOV). The pose can be linked to generated history records.

5.3 Single Generation

  • Sends one request with current settings.
  • Returns status, retry count, token info, estimated cost, response text, and saved image path.
  • AI Rewrite is now placed inside the prompt editor area (top-right).
  • Open Latest Image button has been removed from the center workspace.

5.4 Streaming Generation

  • Emits text/image chunks progressively.
  • Useful for live UI updates while generation is running.

5.5 Queue Generation

  • Build a queue of requests.
  • Per-item completion callback and final queue completion callback.
  • Queue items can be removed from the UI.

5.6 Prompt Rewrite

  • Rewrite prompt with style mode and thinking settings.
  • Supports fallback model and retry on transient failures.

5.7 History

  • Auto-saves generated results to history.
  • Search, remove record, delete associated file, and double-click to apply.

5.8 Prompt Library

  • Save reusable prompts with thumbnails.
  • Search, apply, delete, and assign thumbnail from current preview.
  • Prompt thumbnails are now independent from history files.

5.9 Image Split

  • Split by rows/columns.
  • Supports custom X/Y split ratios.
  • Split preview and final split output are both supported.

5.10 Viewport Overlay Alignment

  • When showing viewport overlay, the panel first restores the linked captured pose, then overlays the image.
  • If absolute paths differ in format, pose lookup falls back to filename matching for better robustness.
  • The workflow no longer depends on spawning/locking camera actors.

6. Saved Data Paths

Default location:

  • Project/Saved/NanoBanana2/outputs
  • Project/Saved/NanoBanana2/history.json
  • Project/Saved/NanoBanana2/prompt_library.json
  • Project/Saved/NanoBanana2/prompt_library_thumbnails

7. Blueprint API Quick Reference

7.1 Async Nodes

  • VerifyApiKey
  • GenerateImage
  • StreamGenerateImage
  • ProcessQueue
  • RewritePrompt

7.2 Blueprint Library Functions

  • Paths: GetDefaultOutputDirectory, GetHistoryFilePath, GetPromptLibraryFilePath
  • History: LoadHistory, SearchHistory, RemoveHistoryByFilePath, ClearHistory, DeleteGeneratedFile
  • Prompt library: LoadPromptLibrary, SavePromptToLibrary, SearchPromptLibrary, RemovePromptFromLibrary
  • Validation/models: IsValidAspectRatio, GetSupportedAspectRatios, GetSupportedModels
  • Cost: EstimateCostCNY
  • Image tools: SplitImage

8. Supported Models and Settings

Current supported models:

  • gemini-3.1-flash-image-preview
  • gemini-3-pro-image-preview
  • gemini-2.5-flash-image

Supported aspect ratios:

  • Auto, 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9

9. FAQ

Q1: Can I generate without reference images?

Yes. Prompt-only generation is fully supported.

Q2: Why do I see DecompressImage failed in logs?

Usually a local image decode failure (corrupt file, unsupported payload, or invalid path).

Q3: If I delete history, will prompt thumbnails disappear?

No. Prompt thumbnails are stored independently in prompt_library_thumbnails.

Q4: What to check when generation fails?

  1. API key validity
  2. Network reachability to Gemini endpoints
  3. Model/parameter correctness
  4. Output directory write permission

10. Best Practices

  • Keep reusable prompt templates in the prompt library.
  • Use queue mode for batch production.
  • Validate composition with lower resolution first, then upscale.
  • Periodically clean old outputs and history to control Saved size.

Clone this wiki locally