142 lines
9.4 KiB
Markdown
142 lines
9.4 KiB
Markdown
# ComfyUI NanoSeed Edit
|
|
|
|
 
|
|
|
|
A Custom Node that integrates [Fal.ai's](https://fal.ai) powerful image editing APIs. This node allows you to edit images using the latest Image Editing Models available via Fal.ai API.
|
|
<img width="925" height="464" alt="image" src="https://github.com/user-attachments/assets/e8cce9fc-dacb-4027-a1cf-4e29ace68329" />
|
|
## ✨ Features
|
|
|
|
* **Multi-Model Support:** Access multiple editing models from a single node.
|
|
* **Multi-Image Input:** Support for up to 10 input images for context-aware editing (model dependent).
|
|
* **Flexible Output:** Control aspect ratios, resolution, and batch size.
|
|
* **Concurrent Workflow Nodes:** Independent NanoSeed nodes yield during fal.ai network waits, allowing ComfyUI to execute them at the same time.
|
|
* **Asynchronous Queue:** Every model uses fal.ai's durable queue with non-blocking status polling and automatic provider-side retries.
|
|
* **Per-Node Concurrency:** Submit up to 8 independent runs from one NanoSeed node while preserving output order.
|
|
|
|
## 🚀 Supported Models
|
|
|
|
| Model | ID in Node | Description |
|
|
| :--- | :--- | :--- |
|
|
| **Nano Banana** | `nano_banana` | Fast, efficient editing. |
|
|
| **Nano Banana Pro** | `nano_banana_pro` | Enhanced quality version of Nano Banana. |
|
|
| **Nano Banana 2** | `nano_banana_2` | New generation model with web search and thinking options. |
|
|
| **GPT Image 2 Edit** | `gpt_image_2_edit` | OpenAI image editing with quality and mask controls. |
|
|
| **GPT Image 2.5 Flare Edit** | `gpt_image_2_5_flare_edit` | Precise GPT Image 2.5 editing with high-resolution, background, quality, format, compression, and mask controls. |
|
|
| **GPT Image 2.5 Sunburst Edit** | `gpt_image_2_5_sunburst_edit` | Precision-focused GPT Image 2.5 editing with the same extended controls. |
|
|
| **Grok Imagine Edit** | `grok_imagine_edit` | xAI image edit model, up to 3 input images. |
|
|
| **Seedream 4.5** | `seedream_4.5` | ByteDance's model. Optimized for high-res editing. |
|
|
| **Seedream 5 Pro Edit** | `seedream_5` | ByteDance Seedream 5.0 Pro region-precise editing. |
|
|
| **Seedream 5 Lite Edit** | `seedream_5_lite` | ByteDance Seedream 5.0 Lite editing. |
|
|
| **Qwen Edit Plus** | `qwen_edit_plus` | Powerful instruction-based editing with guidance control. |
|
|
| **Flux 2 (Standard, Pro, Flex)** | `flux_2_edit` | (BFL) High-fidelity editing capabilities. |
|
|
| **Flux 2 Klein 9B Edit** | `flux_2_klein_9b_edit` | Fast FLUX.2 Klein 9B image editing model. |
|
|
|
|
## 📦 Installation
|
|
|
|
1. Navigate to your ComfyUI `custom_nodes` directory:
|
|
```bash
|
|
cd /path/to/ComfyUI/custom_nodes/
|
|
```
|
|
2. Clone this repository (or unzip the folder containing these files):
|
|
```bash
|
|
git clone [https://github.com/yourusername/ComfyUI-NanoSeed.git](https://github.com/yourusername/ComfyUI-NanoSeed.git)
|
|
```
|
|
3. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## 🔑 Configuration
|
|
|
|
You must have a **Fal.ai API Key** to use this node.
|
|
|
|
1. Go to [fal.ai](https://fal.ai/dashboard/keys) and generate an API Key.
|
|
2. Set `FAL_KEY` in the environment running ComfyUI, or enter the key in the `fal_key` widget. The environment variable takes priority.
|
|
|
|
## 🎛️ Usage
|
|
|
|
### Inputs
|
|
* **prompt**: (Required) A text description of how to edit the image.
|
|
* **model**: Select the specific AI model to use.
|
|
* **fal_key**: Optional UI fallback for your API key when `FAL_KEY` is not set.
|
|
* **image1 - image10**: Connect the images you want to edit.
|
|
* **mask**: Optional GPT Image 2 or GPT Image 2.5 edit mask. Other models ignore it.
|
|
|
|
### Settings
|
|
* **width / height**: Output resolution.
|
|
* *Note:* `nano_banana` models ignore this and use `aspect_ratio`.
|
|
* *Note:* `seedream_4.5` requires high resolutions (see constraints below).
|
|
* **num_images**: How many variations to generate. GPT Image 2.5 supports up to 10; existing model-specific caps remain enforced.
|
|
* **num_inference_steps**: Number of inference steps for supported models.
|
|
* **seed**: Seed for reproducibility.
|
|
* **aspect_ratio**: Set target aspect ratio (e.g., 16:9, 1:1).
|
|
* **resolution**: Sets the GPT output tier while preserving the first input image's aspect ratio. `0.5K`, `1K`, and `2K` use 512px, 1024px, and 2048px maximum edges. `4K` uses the largest valid dimensions under fal's 3840px-edge and 8,294,400-pixel limits.
|
|
* **quality**: GPT quality. GPT Image 2 supports `auto` through `high`; GPT Image 2.5 also supports `xhigh` and `max`.
|
|
* **enable_web_search**: Enables web search context for supported models.
|
|
* **thinking_level**: `off`, `minimal`, or `high` for supported models.
|
|
* **concurrent_runs**: Number of independent fal.ai queue jobs to submit in parallel from this node. This is separate from workflow-level concurrency, which automatically overlaps independent NanoSeed nodes. Each run requests its own `num_images`; outputs are returned in run order. Models with an explicit seed increment it for each additional run.
|
|
* **queue_timeout**: Maximum wait per queue job in seconds. Timed-out jobs receive a best-effort cancellation request.
|
|
* **gpt_background**: `auto`, `transparent`, or `opaque` for GPT Image models.
|
|
* **gpt_image_size**: Optional GPT aspect-ratio override. `auto` follows the first input image; presets or non-zero `width` and `height` override the aspect ratio, while `resolution` still caps the longest edge.
|
|
* **gpt_output_format**: `png`, `jpeg`, or `webp` for GPT Image models.
|
|
* **gpt_output_compression**: Optional GPT Image 2.5 JPEG/WebP compression from 0-100. Leave at `-1` to use the API default.
|
|
* **on_failure**: `continue` returns a red error image so other independent NanoSeed nodes can finish; `raise` keeps strict ComfyUI error behavior.
|
|
|
|
### ⚠️ Model Specific Constraints
|
|
|
|
Different models have different requirements implemented in the node:
|
|
|
|
1. **GPT Image 2.5 Flare / Sunburst**:
|
|
* Supports all 10 NanoSeed reference-image sockets and up to **10 output images**.
|
|
* Supports `auto`, `low`, `medium`, `high`, `xhigh`, and `max` quality. Higher levels increase cost and latency.
|
|
* Supports automatic, transparent, or opaque backgrounds and PNG, JPEG, or WebP output.
|
|
* `resolution` automatically calculates the largest valid dimensions from the first input image.
|
|
* At `4K`, 16:9 becomes **3840x2160**, portrait 9:16 becomes **2160x3840**, square becomes **2880x2880**, and a **3678x4598** input becomes **2576x3216**.
|
|
* Calculated dimensions are multiples of 16, and input aspect ratios beyond the API limit are clamped to 3:1.
|
|
* `gpt_image_size` or non-zero `width` and `height` can override the aspect ratio, but not the selected resolution cap.
|
|
* Supports the shared GPT `mask` socket.
|
|
|
|
2. **Flux 2 Edit (`flux_2_edit`)**:
|
|
* **Single Image Only:** Do not connect `image2` through `image5`.
|
|
* **Resolution:** Width and Height must be between **512px and 2048px**.
|
|
|
|
3. **Flux 2 Klein 9B Edit (`flux_2_klein_9b_edit`)**:
|
|
* Supports up to **4 input images**.
|
|
* `num_inference_steps` is limited to **4-8**.
|
|
|
|
4. **Seedream 4.5 (`seedream_4.5`)**:
|
|
* **High Res Only:** Width and Height must be between **1920px and 4096px**.
|
|
* **Pixel Count:** Total pixels (W x H) must be between ~3.6MP and 16.7MP.
|
|
* **Batch Limit:** The sum of input images and output `num_images` cannot exceed 15.
|
|
|
|
5. **Seedream 5 Pro Edit (`seedream_5`)**:
|
|
* Supports up to **10 input images**.
|
|
* If `aspect_ratio` is not `auto`, the selected aspect ratio is prioritized and converted to Seedream's `image_size`.
|
|
* If `aspect_ratio` is `auto`, the selected `resolution` is mapped to Seedream's automatic size presets.
|
|
* Pro supports `auto_1K` and `auto_2K`; `4K` falls back to Pro's highest automatic preset.
|
|
|
|
6. **Seedream 5 Lite Edit (`seedream_5_lite`)**:
|
|
* Supports up to **10 input images**.
|
|
* Uses the same aspect-ratio-first behavior as Seedream 5 Pro.
|
|
* Supports Lite automatic presets up to `auto_4K`.
|
|
|
|
7. **Nano Banana / Pro / 2**:
|
|
* These models rely on `aspect_ratio` and `resolution` settings rather than custom width/height integers.
|
|
* `nano_banana_2` supports `0.5K`, `1K`, `2K`, and `4K` resolution presets.
|
|
* `nano_banana_2` also supports extended aspect ratios: `4:1`, `1:4`, `8:1`, and `1:8`.
|
|
|
|
8. **Grok Imagine Edit (`grok_imagine_edit`)**:
|
|
* Supports up to **3 input images**.
|
|
* Uses up to **4 output images**.
|
|
|
|
## 🛠️ Troubleshooting
|
|
|
|
* **Queue failures**: The node reports the failed run number and fal request ID. Check account balance, model access, input validation, and safety filters.
|
|
* **Queue timeout**: Increase `queue_timeout` when fal.ai is busy or when using slower high-resolution models.
|
|
* **Many parallel nodes**: NanoSeed limits simultaneous payload uploads to four and retries transient upload failures once. Queue generations remain asynchronous and can continue in parallel after submission.
|
|
* **Isolated failures**: With `on_failure=continue`, a failed NanoSeed node returns a red placeholder instead of aborting the workflow. Successful runs from the same node are retained.
|
|
* **Nodes still run in order**: Restart ComfyUI after updating the node. NanoSeed nodes connected by data dependencies must remain sequential; independent branches run concurrently on ComfyUI versions with async-node scheduling.
|
|
* **Resolution Errors**: If using Seedream, ensure your resolution is set high enough (min 1920x1920). If using Flux, ensure it is within 512-2048.
|
|
|
|
*Star this repo if it helps your workflow! 🚀*
|