Extensions/RS NAI API Request Editable

ComfyUI Extension

RS NAI API Request Editable

NovelAI V5 generation and editable PNG/WebP metadata restoration nodes for ComfyUI.

By omoitukahen·Created a day ago·Updated about 20 hours ago· 0

omoitukahen/ComfyUI_RS_NAI_API_Request_Editable

Nodes—

On cloudLocal install

Stars0

Updatedabout 20 hours ago

Readme

ComfyUI_RS_NAI_API_Request Editable Fork

This extension provides custom nodes for ComfyUI to interact with the NovelAI API using a synchronous requests-based approach. It allows you to generate images, perform image-to-image, inpainting, and advanced face detailing directly from within ComfyUI.

This is a modified fork of raspie10032/ComfyUI_RS_NAI_API_Request. It retains the upstream GPL-3.0-only license and copyright notices.

Maintained by omoitukahen. See PUBLISHING.md for release procedures.

Features

NovelAI API Integration: Support for NAI Diffusion V5, V4.5, V4, V3, and earlier supported models.
Synchronous Requests: Stable connection using requests library.
Multi-Character Support: Spatial multi-character prompting for NAI V4/V5 payloads.
Editable Metadata Restore: Restore prompts, character rows, coordinates, resolution, seed, sampler, and supported generation settings from NovelAI PNG/WebP metadata, then edit them before generation.
Face Detailer: Intelligent face detection (YOLO) and segmentation (SAM) combined with NAI inpainting for high-quality face restoration.

Installation

Method 1: Manual Installation

Navigate to your ComfyUI custom_nodes directory.

Clone this repository:

git clone https://github.com/omoitukahen/ComfyUI_RS_NAI_API_Request_Editable.git

Install dependencies using the Python environment used by ComfyUI:
```
python -m pip install -r requirements.txt
```

Method 2: ComfyUI Manager (after Registry publication)

Open ComfyUI.
Click on Manager -> Custom Nodes Manager.
Search for RS NAI API Request Editable.
Click Install.

Configuration (API Token)

To use these nodes, you must provide your NovelAI API Token.

Copy .env.example to .env in the root of this custom node directory.
Add your token to the file using the canonical variable name:
```
NAI_ACCESS_TOKEN=your_api_token_here
```
NAI_API_TOKEN is also accepted as a fallback for compatibility, but NAI_ACCESS_TOKEN is recommended.

Alternatively, you can set either variable as a system environment variable (NAI_ACCESS_TOKEN is checked first; NAI_API_TOKEN is checked if the first is absent).

Nodes

1. NAI Image Generator (`NovelAIGenerator`)

Main node for text-to-image generation.

2. NAI Character Prompt Select (`CharacterPromptSelect`)

Defines up to 5 characters with spatial coordinates (0-10 scale) for NAI V4+.

2b. NAI Metadata Prompt Loader (`NAIMetadataPromptLoader`)

Reads NovelAI prompt metadata and supported generation settings from a PNG or WebP selected through ComfyUI's input-image upload field. Parsing is offline and read-only. Selecting an image fills editable global prompts and an arbitrary-length character editor. Reload metadata discards edits and restores the image values.

Typical connection:

NAI Metadata Prompt Loader.prompt              -> NAI Image Generator.prompt
NAI Metadata Prompt Loader.negative_prompt     -> NAI Image Generator.negative_prompt
NAI Metadata Prompt Loader.characterPrompts    -> NAI Image Generator.characterPrompts
NAI Metadata Prompt Loader.generationSettings  -> NAI Image Generator.metadataSettings

The first four output positions are retained for existing workflows. When V5 Full and Curated cannot be distinguished from the image metadata, the Generator's current model selection is kept and a warning is shown. Source use_coords / use_order flags are preserved even when only characterPrompts is connected.

NovelAI PNG metadata is read with stealth_pngcomp priority and regular PNG text fallback. NovelAI WebP metadata is read from EXIF UserComment. JPEG, A1111 metadata, Stable Diffusion metadata, and ComfyUI prompt graphs are intentionally rejected.

3. NAI Img2Img (`NAIImg2ImgNode`)

Performs image-to-image generation.

4. NAI Inpaint (`NAIInpaintNode`)

Specialized node for inpainting. Automatically snaps dimensions to 64px.

5. NAI Face Detailer (`NAIFaceDetailerNode`)

Advanced face restoration using YOLO detection and SAM segmentation before sending to NAI API.

Requirement: Requires ComfyUI-Impact-Pack and ComfyUI-Impact-Subpack for detectors. BBOX_DETECTOR types are provided by ComfyUI-Impact-Subpack.

Behavior: Detects the first face, crops it, resizes the crop so its longest side is 1024 px, runs SAM segmentation, sends the crop to NAI inpaint, then pastes the downscaled inpaint result directly back over the original crop region.

Face Detailer outputs the composited image and a mask visualization. If no face is detected the original image is returned on both outputs. Edited results are autosaved under NAI_autosave/face with metadata preserved from the NAI inpaint result.

5b. Detailer (`NAIFaceDetailerSegmNode`)

Same pipeline as NAI Face Detailer, but segm_detector is the required primary detector (defines the crop region) and bbox_detector is optional (additive equal-layer source). SAM always produces the final mask. eye_bbox_detector and limit_opus_free behave identically to the Face Detailer node. Displayed in ComfyUI as Detailer.

6. Prompt Converters

Prompt converter nodes translate weighted prompts between ComfyUI, NovelAI V4, and old NovelAI styles.

Converter Weight Rules

The converter should treat comma characters as tag separators in every supported syntax. This means a weighted range such as 1.3::tag1, tag2 :: contains two weighted tags, not one literal tag containing a comma.

NovelAI V4 numeric weights use scoped ranges:

1.3::tag1, tag2 :: applies 1.3 to tag1 and tag2.
1.3::tag1, tag2, tag3 has no closing ::, so 1.3 applies forward to all following comma-separated tags.
A closing :: ends the active numeric scope after the current comma-separated tag.

Old NovelAI weights use brace/bracket scopes:

{ opens a forward 1.05x scope for following comma-separated tags until a matching } closes it.
[ opens a forward 0.95x scope for following comma-separated tags until a matching ] closes it.
A closing } with no active { applies 1.05x backward to all previous parsed tags.
A closing ] with no active [ applies 0.95x backward to all previous parsed tags.
Mixed braces and brackets are handled by the same character-level scope rules. For example, {[tag]} multiplies 1.05 * 0.95, which is treated as approximately neutral after normalization.

When writing converted prompts, consecutive tags with the same effective weight should be merged into a single scope where possible:

1.05::tag1 ::, 1.05::tag2 :: can be written as 1.05::tag1, tag2 ::.
{tag1}, {tag2} can be written as {tag1, tag2}.

Old NovelAI brace/bracket syntax cannot exactly represent arbitrary numeric weights, negative weights, or zero weights. Those values are converted to the nearest practical old-style approximation when exporting to old NovelAI syntax.

Opus Free-Generation Protection

All generation nodes (NovelAIGenerator, NAIImg2ImgNode, NAIInpaintNode, NAIFaceDetailerNode) include a limit_opus_free parameter.

What it does: When enabled, the node clamps the request dimensions and step count to the conditions allowed under the NovelAI Opus free-generation tier, following the same approach as bedovyy/ComfyUI_NAIDGenerator.

What it does NOT do:

It does not auto-detect your account subscription tier.
It does not check your Anlas balance or block requests when balance is insufficient. The NovelAI API itself will reject any request that cannot be fulfilled.
An Anlas Tracker node is not included in this extension.

Set limit_opus_free to False if you have a paid subscription and want to generate at larger sizes or higher step counts.

Screenshots

(Screenshots placeholders)

Requirements

requests
Pillow
numpy
python-dotenv
segment_anything (SAM)
ComfyUI-Impact-Pack (Mandatory for Face Detailer node)
ComfyUI-Impact-Subpack (Mandatory for Face Detailer node; provides BBOX_DETECTOR types used for bbox loading)

Branch Comparison: `main` vs `Add_facedetail`

This section summarizes the differences introduced in the Add_facedetail branch relative to main.

Newly Added

| Item | Description | | :--- | :--- | | nai_api.py | New module housing shared NAI API helpers (request building, response parsing) extracted from generators.py. | | image_utils.py | New module with image manipulation helpers shared by the Face Detailer and generator nodes. | | NAIFaceDetailerNode | Full face detailer implementation: YOLO detection → SAM segmentation → NAI inpainting → crop-paste composite. Only the first detected face is processed per run. | | Metadata-preserving autosave | Face Detailer results are autosaved with NAI metadata intact (same metadata written by the inpainting call). | | /face autosave subfolder | Face Detailer autosaves are written to NAI_autosave/face/ to keep them separate from standard generation outputs. | | n_samples=1 policy | Face Detailer enforces a single sample per NAI API call, matching NAI inpaint constraints. | | segment-anything>=1.0 | SAM added as an explicit runtime dependency in requirements.txt and pyproject.toml. | | limit_opus_free parameter | Manual toggle (default True) on all generation nodes that caps total pixels to ≤ 1,048,576 and steps to ≤ 28, matching Opus free-tier generation limits. No account detection or Anlas balance checking. |

Removed / Pruned

Behavior-Preserving Changes

load_dotenv() calls consolidated — previously called redundantly at module level in both generators.py and __init__.py; now called once.
__init__.py import and export variable names normalized to match the names exported by generators.py.
_get_save_path return signature simplified to a (path, filename) tuple (was a 5-tuple with unused empty-string fields).

Credits / Acknowledgments

The original project is raspie10032/ComfyUI_RS_NAI_API_Request. This fork preserves the upstream copyright and license notices.

See THIRD_PARTY_NOTICES.md for full details.

License

The source code in this repository is published under GPL-3.0-only. Full corresponding source is provided in this repository. The complete GPLv3 license text is in the COPYING file. See the LICENSE file for the short SPDX notice.

This is a factual license notice, not legal advice.

Workflow Examples

Files in workflow_example/ (example.json, example.png) are project-provided examples distributed with this project under GPL-3.0-only unless otherwise noted.