From 543ffa7342b94d27f9aa2d4dd1bcc0799797d55e Mon Sep 17 00:00:00 2001 From: comrender <139063732+comrender@users.noreply.github.com> Date: Sun, 15 Mar 2026 17:17:36 +0100 Subject: [PATCH] Update README.md --- README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 128 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index ea2b539..4c7a6d4 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,144 @@ -# ComfyUI-NanoB-Edit-Gemini +# ComfyUI Nano Banana Edit Gemini -This custom node facilitates direct interaction with the **Google Gemini API** (supporting **Gemini 3 Pro** and **Gemini 2.5 Flash**) for advanced image editing tasks within ComfyUI. It features parallel request handling to generate multiple variations efficiently. +ComfyUI custom node for Gemini native image generation/editing with multimodal image input support. -### 💡 Why this Node? -Google's infrastructure can be complex to navigate—specifically the distinctions between Vertex AI/Gemini. Naming conventions are often inconsistent (e.g., `gemini-3-pro-image-preview` vs. "Nano Banana Pro"), and straightforward documentation for implementing these specific API endpoints is scarce. This node aims to bridge that gap by providing a simple, working implementation. +## Supported Models ---- +- `gemini-2.5-flash-image` (Nano Banana) +- `gemini-3-pro-image-preview` (Nano Banana Pro) +- `gemini-3.1-flash-image-preview` (Nano Banana 2) -## Key Features +## Main Features -* **Multi-Model Support:** Compatible with Gemini 3 Pro and Gemini 2.5 Flash. -* **Parallel Processing:** Handles parallel requests to generate multiple image variations simultaneously. -* **Debug Mode:** Includes a debug option to view the exact input sent to Gemini directly in the ComfyUI terminal/console. -* **Flexible Auth:** Supports both direct API key input (UI) and Environment Variables (Recommended). +- Multi-model image editing with prompt + up to 14 input reference images. +- Parallel request execution to generate multiple variations quickly. +- Model-aware validation for ratios, resolutions, and feature toggles. +- Google Search toggle for supported Gemini 3 image models. +- Thinking toggle for Gemini 3.1 Flash Image Preview. +- File API toggle for large or reusable input images. +- Output format control: `png`, `jpg`, `webp`. +- Debug payload mode with safe base64 truncation and request-size diagnostics. +- API key from node input or `GEMINI_API_KEY` environment variable. ---- +## Node Inputs -## ⚠️ Security & Best Practices +### Required -**Important:** While this node allows you to enter your API key directly into the UI widget, **it is highly recommended to use Environment Variables.** +- `prompt` (STRING, multiline) +- `model`: + - `gemini-2.5-flash-image` + - `gemini-3-pro-image-preview` + - `gemini-3.1-flash-image-preview` +- `gemini_api_key` (STRING, optional if `GEMINI_API_KEY` env var exists) +- `seed` (INT) +- `aspect_ratio`: + - Common: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` + - Gemini 3.1 additions: `1:4`, `4:1`, `1:8`, `8:1` +- `resolution`: `0.5K`, `1K`, `2K`, `4K` + - `0.5K` maps to Gemini API value `512` and is valid only for `gemini-3.1-flash-image-preview` + - `gemini-2.5-flash-image` is constrained to `1K` in this node +- `output_format`: `png`, `jpg`, `webp` +- `num_images` (1-4, parallel requests) +- `use_file_api` (BOOLEAN) +- `use_google_search` (BOOLEAN) +- `enable_thinking` (BOOLEAN) + - Applies to `gemini-3.1-flash-image-preview` only +- `safety_filter`: `block_none`, `block_few`, `block_some`, `block_most` +- `debug_payload` (BOOLEAN) -> [!WARNING] -> **Do not publish your workflows or embed workflows into final images with your API key entered in the node's text box.** -> If you share a workflow with the key inside, your API usage will be disclosed to third parties. Keep the UI text box empty and use the setup steps below. +### Optional image inputs ---- +- `image1` ... `image5` (single image sockets) +- `image6_14` (batched IMAGE socket) -## 🛠️ Setup Instructions +## Model-Specific Behavior -### 1. Set the Environment Variable -To keep your API key secure, set the `GEMINI_API_KEY` on your system. +- `gemini-3.1-flash-image-preview` + - Supports `0.5K`, `1K`, `2K`, `4K` + - Supports expanded aspect ratios (`1:4`, `4:1`, `1:8`, `8:1`) + - Thinking toggle maps to `thinkingConfig.thinkingLevel` (`HIGH` vs `MINIMAL`) + - Supports Google Search tool toggle -#### **Windows** -1. Search for **"Edit the system environment variables"** in the Start menu. -2. Click **Environment Variables** -> **New**. -3. **Variable Name:** `GEMINI_API_KEY` -4. **Variable Value:** `your_actual_api_key_here` -5. *Note: You must restart ComfyUI (and the console) after setting this for changes to take effect.* +- `gemini-3-pro-image-preview` + - Supports `1K`, `2K`, `4K` + - Supports base aspect-ratio set + - Supports Google Search tool toggle + +- `gemini-2.5-flash-image` + - Uses ratio-only image configuration in this node + - Resolution constrained to `1K` in this implementation + - Google Search and Thinking toggle are not enabled for this model in this node + +## Multi-Image Reference Limits (Latest Guidance) + +This node accepts up to 14 input references and truncates extra inputs with a warning. + +Latest model guidance for up to 14 references: + +- `gemini-3.1-flash-image-preview` + - Up to 10 object references with high-fidelity detail + - Up to 4 character-consistency references +- `gemini-3-pro-image-preview` + - Up to 6 object references with high-fidelity detail + - Up to 5 character-consistency references + +The node cannot automatically classify "object" vs "character" images, so it enforces only the global 14-image cap and prints warnings when count exceeds per-model recommended ranges. + +## Image Understanding and Quality Notes + +To improve quality and instruction following: + +- Keep source images clear, correctly oriented, and not blurry. +- Prefer concise but explicit prompts with concrete edits. +- For multimodal prompts, this node sends image parts before text instruction for better image-understanding behavior. +- Keep inline payloads below API size limits. + +## Request Size and Error Handling + +- API inline payloads are validated with a conservative preflight budget. +- If estimated inline size is too large and File API is off, the node fails early with a clear message suggesting enabling File API. +- When File API is on, images are uploaded first and the node sends `fileData` references instead of inline base64 image parts. +- File API upload start/finalize failures are surfaced with explicit HTTP details. +- HTTP/network errors include per-request diagnostics. +- Candidate parsing failures include finish reason + snippet of text response when no image is returned. +- Safety blocks from `promptFeedback` are surfaced in logs. + +## Output Format Support + +This node supports output normalization to: + +- `image/png` +- `image/jpeg` +- `image/webp` + +`HEIC` and `HEIF` output are intentionally skipped in this version. + +## Security Best Practices + +Use environment variables for API keys whenever possible. + +> Do not publish workflows that include your API key in node text fields. + +### Set `GEMINI_API_KEY` + +#### Windows + +1. Open **Edit the system environment variables**. +2. Open **Environment Variables** and add: + - Name: `GEMINI_API_KEY` + - Value: `your_actual_api_key_here` +3. Restart ComfyUI after changes. + +#### Linux/macOS + +Add to shell profile: -#### **Linux / macOS** -Add the export command to your shell profile (`.bashrc`, `.zshrc`, etc.) or your launch script: ```bash export GEMINI_API_KEY="your_actual_api_key_here" +``` + +## References + +- Gemini image generation docs: +- 14 reference images details: +- Gemini image understanding docs: