ComfyUI Extension: ComfyUI Civitai Helper Extension
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
-
Clone this repository into your ComfyUI custom nodes directory:
cd ComfyUI/custom_nodes/ git clone https://github.com/your-username/comfui-civitaihelper.git
-
Install dependencies:
cd comfui-civitaihelper pip install -r requirements.txt
-
Restart ComfyUI
Quick Start Guide
Step 1: Set Up Your API Key
- Get your Civitai API key from Civitai Account Settings
- Add the āļø Civitai Settings node to your workflow
- Set action to "Save New Key" and enter your API key
- Execute the node to save your key
Step 2: Analyze a Civitai Image
- Add the šØ Civitai Workflow Parser node
- Drag and drop a PNG image from Civitai directly onto the image input
- Set
check_only=True
for safe analysis - Execute to see workflow and missing models
Step 3: Download Missing Models (Optional)
Option A: Direct Download
- Set
check_only=False
andauto_download=True
in the parser node
Option B: Separate Download Node (Recommended)
- Add the š„ Civitai Model Downloader node
- Connect the workflow_json and missing_models outputs from the parser
- Set
download_models=True
to confirm downloads - Execute to download missing models
Detailed Usage
Drag & Drop Workflow
The easiest way to use the extension:
- Find a Civitai Image: Browse Civitai.com and find an image you like
- Save the Image: Right-click and save the PNG image (includes workflow metadata)
- Drag & Drop: Drag the saved PNG directly onto the image input of the parser node
- Analyze: Execute the node to extract the workflow and identify missing models
- 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:
- Use the āļø Civitai Settings node with "Clear Saved Key"
- Or manually delete the settings file
Node Reference
šØ Civitai Workflow Parser
Inputs:
image
(IMAGE, optional): Drag & drop image inputimage_path
(STRING, optional): Manual path to image fileauto_download
(BOOLEAN): Enable automatic downloadscheck_only
(BOOLEAN): Safe mode - analyze onlycivitai_api_key
(STRING, optional): API key overridecomfyui_models_path
(STRING, optional): Custom models pathprefer_safetensors
(BOOLEAN): Prefer .safetensors formatcreate_backup
(BOOLEAN): Backup existing files
Outputs:
workflow_json
(STRING): Extracted workflow JSONmissing_models
(STRING): List of missing modelsdownload_status
(STRING): Status and progress infomodel_info
(STRING): Summary of all models
š„ Civitai Model Downloader
Inputs:
workflow_json
(STRING): Workflow from parser nodemissing_models
(STRING): Missing models from parser nodedownload_models
(BOOLEAN): Confirmation to downloadcivitai_api_key
(STRING, optional): API key overridecomfyui_models_path
(STRING, optional): Custom models pathprefer_safetensors
(BOOLEAN): Prefer .safetensors formatcreate_backup
(BOOLEAN): Backup existing files
Outputs:
download_status
(STRING): Download results summarydownload_summary
(STRING): Detailed download information
āļø Civitai Settings
Inputs:
action
(CHOICE): Get Current Key | Save New Key | Clear Saved Keynew_api_key
(STRING, optional): New API key to save
Outputs:
status
(STRING): Operation resultcurrent_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:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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.