168 lines
6.6 KiB
Markdown
168 lines
6.6 KiB
Markdown
# ComfyUI Upsampler Nodes
|
|
|
|
ComfyUI custom nodes for integrating with the Upsampler API to enhance and upscale images using AI.
|
|
|
|
## Features
|
|
|
|
Three different upscaling methods:
|
|
|
|
1. **Smart Upscale** - Enhances images by intelligently regenerating at a higher resolution
|
|
2. **Dynamic Upscale** - Preserves the overall composition while forcing new details
|
|
3. **Precise Upscale** - Upscales and sharpens while completely preserving the original structure
|
|
|
|
## Installation
|
|
|
|
1. Clone or download this repository to your ComfyUI custom_nodes directory:
|
|
```
|
|
cd ComfyUI/custom_nodes
|
|
git clone <this-repo-url> comfyui-upsampler
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```
|
|
pip install -r comfyui-upsampler/requirements.txt
|
|
```
|
|
|
|
3. Restart ComfyUI
|
|
|
|
## Setup Required
|
|
|
|
### 1. Get Upsampler API Key
|
|
|
|
1. Visit https://upsampler.com/
|
|
2. Create an account and generate an API key
|
|
3. Add credits to your account for processing
|
|
|
|
### 2. Image Hosting Setup
|
|
|
|
The Upsampler API requires images to be accessible via public URLs. The nodes now include **automatic image hosting** with multiple options:
|
|
|
|
#### Option A: ImgBB (Recommended - Free & Reliable, up to 32MB)
|
|
|
|
1. **Get a free API key**:
|
|
- Visit https://api.imgbb.com/
|
|
- Sign up and generate an API key
|
|
- Free tier: Up to 100 images/day, 32MB per image
|
|
|
|
2. **Configure the API key** (choose one method):
|
|
|
|
**Method 1: Node Parameter**
|
|
- Add your ImgBB API key to the "imgbb_api_key" field in each node
|
|
|
|
**Method 2: Environment Variable**
|
|
- Set environment variable: `IMGBB_API_KEY=your_api_key_here`
|
|
- Windows: `set IMGBB_API_KEY=your_api_key_here`
|
|
- Linux/Mac: `export IMGBB_API_KEY=your_api_key_here`
|
|
|
|
#### Option B: Free Services (Automatic Fallback, larger files supported)
|
|
|
|
If no ImgBB API key is provided, the nodes will automatically try:
|
|
- **Catbox.moe**: Up to 200MB, no API key needed, permanent storage
|
|
- **0x0.st**: Simple file sharing service
|
|
- **PostImages**: Image hosting service
|
|
|
|
**Perfect for large images (32MB-200MB) without needing any API keys!**
|
|
|
|
**Note**: Free services may be less reliable and have usage limits.
|
|
|
|
#### Option C: Your Own Server
|
|
For production use, implement your own hosting solution by modifying the `_upload_image_temp()` method in `nodes.py`.
|
|
|
|
## Usage
|
|
|
|
1. Add one of the Upsampler nodes to your ComfyUI workflow:
|
|
- 🔍 Upsampler Smart Upscale
|
|
- ⚡ Upsampler Dynamic Upscale
|
|
- 🎯 Upsampler Precise Upscale
|
|
|
|
2. Connect an IMAGE input to the node
|
|
|
|
3. Configure the parameters:
|
|
- **API Key**: Your Upsampler API key
|
|
- **ImgBB API Key** (optional): Your ImgBB API key for reliable image hosting
|
|
- **Input Image Type**: Choose "realism", "anime", or "universal"
|
|
- **Upscale Factor**: How much to upscale (1.0-4.0 for Smart/Dynamic, 1.0-16.0 for Precise)
|
|
- **Max Parallel Jobs**: How many tiles to submit simultaneously (1-15). Leave at 1 for sequential processing.
|
|
- Additional parameters specific to each method
|
|
|
|
4. The node will:
|
|
- Upload your image to a public URL
|
|
- Submit the upscaling job to Upsampler API
|
|
- Poll for completion with progress updates
|
|
- Download and return the upscaled image
|
|
|
|
## Node Parameters
|
|
|
|
### Smart Upscale
|
|
- `imgbb_api_key`: ImgBB API key for reliable image hosting (optional)
|
|
- `global_creativity` (0-10): How much the AI can change the original image
|
|
- `detail` (0-10): Level of detail enhancement
|
|
- `description`: Text prompt to guide the upscaling process
|
|
- `should_enhance_faces`: Better preserve and enhance facial features
|
|
- `should_preserve_blur`: Preserve existing blur in the image
|
|
- `max_parallel_jobs` (1-15): Tiles submitted in parallel; higher values finish sooner but must stay within Upsampler rate and queue limits
|
|
|
|
### Dynamic Upscale
|
|
- `imgbb_api_key`: ImgBB API key for reliable image hosting (optional)
|
|
- `global_creativity` (0-10): How much the AI can change the original image
|
|
- `resemblance` (0-10): How closely to adhere to original image structure
|
|
- `detail` (0-10): Level of detail enhancement
|
|
- `description`: Text prompt to guide the upscaling process
|
|
- `should_enhance_faces`: Better preserve and enhance facial features
|
|
- `should_preserve_hands`: Better preserve hand structures
|
|
- `should_preserve_blur`: Preserve existing blur in the image
|
|
- `max_parallel_jobs` (1-15): Tiles submitted in parallel; honours `UPSAMPLER_MAX_CONCURRENCY` and API queue limits
|
|
|
|
### Precise Upscale
|
|
- `imgbb_api_key`: ImgBB API key for reliable image hosting (optional)
|
|
- `should_enhance_faces`: Apply face restoration techniques
|
|
- `should_preserve_blur`: Preserve existing blur in the image
|
|
- `max_parallel_jobs` (1-15): Tiles submitted in parallel; honours `UPSAMPLER_MAX_CONCURRENCY` and API queue limits
|
|
|
|
## Advanced Configuration
|
|
|
|
- `UPSAMPLER_MAX_CONCURRENCY`: Optional environment override for the concurrency cap (default comes from each node's `max_parallel_jobs`, clamped to 1-15).
|
|
- `UPSAMPLER_MAX_RETRIES`: Additional attempts after the initial Upsampler failure when the error is retryable (default: 2).
|
|
- `UPSAMPLER_RETRY_DELAY`: Seconds to wait before retrying a failed tile (default: 10).
|
|
|
|
These variables apply across every Upsampler node in a workflow and complement the per-node `max_parallel_jobs` control. Increase them gradually to stay within Upsampler's published rate and queue limits (90 POSTs/minute, 6000/hour; 240 status checks/minute).
|
|
|
|
## Pricing
|
|
|
|
Credits are consumed based on output image size:
|
|
- **Smart/Dynamic Upscale**: 1 credit per megapixel (minimum 1 credit)
|
|
- **Precise Upscale**: 1 credit per 4 megapixels (minimum 1 credit)
|
|
|
|
## Troubleshooting
|
|
|
|
1. **Image upload errors**:
|
|
- Get an ImgBB API key for reliable hosting
|
|
- Check your internet connection
|
|
- Try again if free services are temporarily unavailable
|
|
|
|
2. **"All free hosting services failed"**:
|
|
- Use ImgBB with an API key (recommended)
|
|
- Set the `IMGBB_API_KEY` environment variable
|
|
- Or add the key to the node parameter
|
|
|
|
3. **API authentication errors**:
|
|
- Check your Upsampler API key is correct and has credits
|
|
- Verify account status at https://upsampler.com/
|
|
|
|
4. **Rate limit errors**:
|
|
- The API currently allows up to 90 requests/minute (6000/hour) for upscale endpoints and 240 requests/minute for status checks
|
|
- High `max_parallel_jobs` values can hit these limits quickly; wait before retrying or lower concurrency
|
|
|
|
5. **Job failures**:
|
|
- Check the error message for specific issues
|
|
- Common issues: invalid parameters or insufficient credits
|
|
- Verify image format and size constraints
|
|
|
|
## API Documentation
|
|
|
|
For full API documentation, visit: https://upsampler.com/api
|
|
|
|
## License
|
|
|
|
This custom node implementation is provided as-is. Please refer to Upsampler's terms of service for API usage.
|