# 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.