Extensions/ComfyUI-NanoSeed
ComfyUI Extension

ComfyUI-NanoSeed

A custom ComfyUI node for seamless image editing using fal.ai's NanoBanana and Seedream (v4) models. Edit images with AI-powered prompts, supporting multi-image batches, custom resolutions, and easy fal.ai API key integration directly in the node interface.

By comrender·Created 12 months ago·Updated 6 days ago· 7
comrender/ComfyUI-NanoSeed
Nodes2
On cloudLocal install
Categoryimage/edit, image/generate
Stars7
Updated6 days ago

Nodes (2)

NanoSeed

NanoSeed turns your ComfyUI graph into a fal.ai editing terminal — no GPU, no model downloads

image/edit
Seedream Text to Image

Seedream text-to-image without a 15GB checkpoint

image/generate
Readme

ComfyUI NanoSeed Edit

ComfyUI Fal.ai

A Custom Node that integrates Fal.ai's 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: 
    cd /path/to/ComfyUI/custom_nodes/
  2. Clone this repository (or unzip the folder containing these files): 
    git clone [https://github.com/yourusername/ComfyUI-NanoSeed.git](https://github.com/yourusername/ComfyUI-NanoSeed.git)
  3. Install dependencies: 
    pip install -r requirements.txt

🔑 Configuration

You must have a Fal.ai API Key to use this node.

  1. Go to fal.ai 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! 🚀