ComfyUI Extension: ComfyUI Civitai Helper Extension

Authored by vovler

Created

Updated

1 stars

ComfyUI extension for parsing Civitai PNG workflows and automatically downloading missing models

Custom Nodes (0)

    README

    ComfyUI Civitai Helper Extension

    A powerful ComfyUI custom node collection that automatically parses PNG workflow images from Civitai, extracts embedded ComfyUI metadata, identifies missing models, and downloads them directly using the Civitai API.

    Features

    āœØ PNG Workflow Parsing: Automatically extracts ComfyUI workflow JSON from PNG images downloaded from Civitai
    šŸ–±ļø Drag & Drop Support: Simply drag and drop Civitai PNG images directly into ComfyUI
    šŸ” Smart Model Detection: Identifies missing checkpoints, LoRAs, VAE, embeddings, ControlNet, and other models
    šŸš€ Automatic Downloads: Downloads missing models directly from Civitai using their API
    šŸ“ Intelligent Organization: Saves models to the correct ComfyUI folders automatically
    šŸ”§ Advanced Matching: Uses fuzzy matching to find models even with slight name variations
    āš” Progress Tracking: Real-time download progress with file size information
    šŸ›”ļø Backup Support: Optional backup creation before overwriting existing files
    šŸŽÆ Multi-format Support: Prioritizes .safetensors files but supports .pt, .ckpt, and other formats
    āš™ļø Persistent Settings: Save your API key and preferences for easy reuse
    šŸŽ›ļø Separate Download Node: Dedicated node for downloading with safety controls

    Nodes Overview

    šŸŽØ Civitai Workflow Parser

    Main node for analyzing Civitai PNG images and identifying missing models:

    • Drag & Drop Support: Simply drag PNG images into the node
    • Workflow Extraction: Automatically extracts ComfyUI workflow from image metadata
    • Model Detection: Identifies all missing models in the workflow
    • Check Mode: Safe analysis without downloads

    šŸ“„ Civitai Model Downloader

    Dedicated download node with safety controls:

    • Safe Downloads: Requires explicit confirmation to download
    • Batch Processing: Downloads multiple models efficiently
    • Progress Tracking: Real-time download status and progress
    • Error Handling: Detailed error reporting and recovery

    āš™ļø Civitai Settings

    Settings management node:

    • API Key Storage: Securely save your Civitai API key
    • Persistent Settings: Preferences saved between sessions
    • Settings Export/Import: Backup and restore your configuration

    Installation

    1. Clone this repository into your ComfyUI custom nodes directory:

      cd ComfyUI/custom_nodes/
git clone https://github.com/your-username/comfui-civitaihelper.git

    2. Install dependencies:

      cd comfui-civitaihelper
pip install -r requirements.txt

    3. Restart ComfyUI

    Quick Start Guide

    Step 1: Set Up Your API Key

    1. Get your Civitai API key from Civitai Account Settings
    2. Add the āš™ļø Civitai Settings node to your workflow
    3. Set action to "Save New Key" and enter your API key
    4. Execute the node to save your key

    Step 2: Analyze a Civitai Image

    1. Add the šŸŽØ Civitai Workflow Parser node
    2. Drag and drop a PNG image from Civitai directly onto the image input
    3. Set check_only=True for safe analysis
    4. Execute to see workflow and missing models

    Step 3: Download Missing Models (Optional)

    Option A: Direct Download

    • Set check_only=False and auto_download=True in the parser node

    Option B: Separate Download Node (Recommended)

    1. Add the šŸ“„ Civitai Model Downloader node
    2. Connect the workflow_json and missing_models outputs from the parser
    3. Set download_models=True to confirm downloads
    4. Execute to download missing models

    Detailed Usage

    Drag & Drop Workflow

    The easiest way to use the extension:

    1. Find a Civitai Image: Browse Civitai.com and find an image you like
    2. Save the Image: Right-click and save the PNG image (includes workflow metadata)
    3. Drag & Drop: Drag the saved PNG directly onto the image input of the parser node
    4. Analyze: Execute the node to extract the workflow and identify missing models
    5. Download: Use the download node to automatically download missing models

    Manual Path Input

    You can also specify image paths manually:

    • Leave the image input empty
    • Enter the path in the image_path field
    • Supports absolute and relative paths

    Settings Management

    The āš™ļø Civitai Settings node provides several actions:

    • Get Current Key: Check if an API key is saved (shows masked version)
    • Save New Key: Store a new API key securely
    • Clear Saved Key: Remove the saved API key

    Safety Features

    • Check Mode: Default safe mode that only analyzes without downloading
    • Download Confirmation: Dedicated download node requires explicit confirmation
    • Backup Creation: Optional backup of existing files before overwriting
    • Progress Monitoring: Real-time download progress and status

    Supported Model Types

    • Checkpoints: Stable Diffusion models (.safetensors, .ckpt, .pt)
    • LoRAs: Low-Rank Adaptation models (.safetensors, .pt)
    • VAE: Variational Autoencoders (.safetensors, .pt, .ckpt)
    • Embeddings: Textual Inversions (.safetensors, .pt, .bin)
    • ControlNet: Control models (.safetensors, .pt)
    • CLIP Vision: Vision models (.safetensors, .pt)
    • Upscale Models: Super-resolution models (.pth, .pt, .safetensors)

    Model Organization

    Models are automatically saved to the appropriate ComfyUI directories:

    ComfyUI/models/
ā”œā”€ā”€ checkpoints/          # SD checkpoints
ā”œā”€ā”€ loras/                # LoRA models
ā”œā”€ā”€ vae/                  # VAE models
ā”œā”€ā”€ embeddings/           # Textual inversions
ā”œā”€ā”€ controlnet/           # ControlNet models
ā”œā”€ā”€ clip_vision/          # CLIP vision models
ā””ā”€ā”€ upscale_models/       # Upscaling models

    Advanced Configuration

    Settings File Location

    Settings are automatically saved to:

    • ComfyUI/custom_nodes/civitai_helper_settings.json (preferred)
    • ~/.comfyui_civitai_settings.json (fallback)

    Environment Variables

    You can also use environment variables:

    export CIVITAI_API_KEY="your_api_key_here"
export COMFYUI_MODELS_PATH="/path/to/your/models"

    Custom Configuration

    Edit config.py to customize:

    • API endpoints and timeouts
    • Model type mappings
    • File extensions and priorities
    • Download chunk sizes
    • Search parameters

    Workflow Examples

    Basic Analysis Workflow

    Image ā†’ šŸŽØ Civitai Workflow Parser ā†’ View Results

    Safe Download Workflow

    Image ā†’ šŸŽØ Civitai Workflow Parser ā†’ šŸ“„ Civitai Model Downloader ā†’ Download

    Settings Management

    āš™ļø Civitai Settings ā†’ Save API Key ā†’ Ready to Use

    Troubleshooting

    Common Issues

    "No workflow metadata found in image"

    • Ensure the PNG was downloaded from Civitai with workflow metadata
    • Try different PNG images from Civitai
    • Check that the image hasn't been recompressed or edited

    "Please drag & drop an image or provide a valid image path"

    • Make sure you've either dragged an image onto the image input socket (not the node itself)
    • Try using the image_path field as an alternative
    • Restart ComfyUI if drag & drop stops working

    "Civitai API key is required"

    • Use the āš™ļø Civitai Settings node to save your API key
    • Get your API key from Civitai Account Settings
    • Ensure the key has proper permissions

    "Model not found on Civitai"

    • The model might not be available on Civitai
    • Try searching manually on Civitai.com
    • The model name might be slightly different

    Debug Mode

    Enable debug logging:

    import logging
logging.getLogger().setLevel(logging.DEBUG)

    Settings Reset

    To reset all settings:

    1. Use the āš™ļø Civitai Settings node with "Clear Saved Key"
    2. Or manually delete the settings file

    Node Reference

    šŸŽØ Civitai Workflow Parser

    Inputs:

    • image (IMAGE, optional): Drag & drop image input
    • image_path (STRING, optional): Manual path to image file
    • auto_download (BOOLEAN): Enable automatic downloads
    • check_only (BOOLEAN): Safe mode - analyze only
    • civitai_api_key (STRING, optional): API key override
    • comfyui_models_path (STRING, optional): Custom models path
    • prefer_safetensors (BOOLEAN): Prefer .safetensors format
    • create_backup (BOOLEAN): Backup existing files

    Outputs:

    • workflow_json (STRING): Extracted workflow JSON
    • missing_models (STRING): List of missing models
    • download_status (STRING): Status and progress info
    • model_info (STRING): Summary of all models

    šŸ“„ Civitai Model Downloader

    Inputs:

    • workflow_json (STRING): Workflow from parser node
    • missing_models (STRING): Missing models from parser node
    • download_models (BOOLEAN): Confirmation to download
    • civitai_api_key (STRING, optional): API key override
    • comfyui_models_path (STRING, optional): Custom models path
    • prefer_safetensors (BOOLEAN): Prefer .safetensors format
    • create_backup (BOOLEAN): Backup existing files

    Outputs:

    • download_status (STRING): Download results summary
    • download_summary (STRING): Detailed download information

    āš™ļø Civitai Settings

    Inputs:

    • action (CHOICE): Get Current Key | Save New Key | Clear Saved Key
    • new_api_key (STRING, optional): New API key to save

    Outputs:

    • status (STRING): Operation result
    • current_key_info (STRING): Current key information (masked)

    API Rate Limits

    • Civitai has API rate limits
    • The extension respects these limits
    • If you hit rate limits, wait a few minutes before retrying

    Security Considerations

    • API keys are stored locally in ComfyUI's directory
    • Keys are masked in outputs for security
    • Never share API keys publicly
    • Regularly rotate your API keys

    Contributing

    We welcome contributions! Please:

    1. Fork the repository
    2. Create a feature branch
    3. Make your changes
    4. Add tests if applicable
    5. Submit a pull request

    License

    This project is licensed under the MIT License - see the LICENSE file for details.

    Changelog

    v2.0.0

    • šŸ†• Drag & drop image support
    • šŸ†• Dedicated download node with safety controls
    • šŸ†• Persistent settings management
    • šŸ†• Three separate nodes for different functions
    • āœØ Enhanced UI with emojis and better feedback
    • šŸ›”ļø Improved security and error handling
    • šŸŽÆ Better separation of concerns

    v1.0.0

    • Initial release
    • PNG workflow parsing
    • Model detection and downloading
    • Support for all major model types
    • Fuzzy model name matching
    • Progress tracking
    • Backup support

    Acknowledgments

    • ComfyUI - The amazing UI for Stable Diffusion
    • Civitai - The model sharing platform
    • The open-source AI community

    Support

    • Create an issue on GitHub for bugs or feature requests
    • Join the ComfyUI community for general support
    • Check Civitai documentation for API-related questions

    Note: This extension requires an active internet connection and a valid Civitai API key to download models. Always respect the license terms of downloaded models.