# ComfyUI NanoSeed Edit ![ComfyUI](https://img.shields.io/badge/ComfyUI-Custom_Node-blue) ![Fal.ai](https://img.shields.io/badge/Backend-Fal.ai-purple) 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. image ## ✨ 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! 🚀*