# ComfyUI Node Reference

This reference documents the most commonly used ComfyUI nodes for image
generation workflows in the Oshun platform.

## Table of Contents

- [Core Nodes](#core-nodes) — checkpoint loading and the KSampler samplers
- [Loading Nodes](#loading-nodes) — LoRA, ControlNet, VAE, CLIP, and upscale-model loaders
- [Conditioning Nodes](#conditioning-nodes) — text encoding and ControlNet application
- [Latent Nodes](#latent-nodes)
- [VAE Nodes](#vae-nodes)
- [Image Nodes](#image-nodes)
- [Upscaling Nodes](#upscaling-nodes)
- [Utility Nodes](#utility-nodes)
- [Custom Manager Nodes](#custom-manager-nodes)

---

## Core Nodes

### CheckpointLoaderSimple

Loads a Stable Diffusion checkpoint file.

```json
{
  "class_type": "CheckpointLoaderSimple",
  "inputs": {
    "ckpt_name": "sd_xl_base_1.0.safetensors"
  }
}
```

| Input       | Type   | Description                                  |
| ----------- | ------ | -------------------------------------------- |
| `ckpt_name` | string | Checkpoint filename from models/checkpoints/ |

| Output | Index | Type  | Description             |
| ------ | ----- | ----- | ----------------------- |
| MODEL  | 0     | MODEL | Diffusion model         |
| CLIP   | 1     | CLIP  | Text encoder            |
| VAE    | 2     | VAE   | Variational autoencoder |

**Supported Checkpoints:**

| Model             | VRAM | Resolution | Notes           |
| ----------------- | ---- | ---------- | --------------- |
| sd_xl_base_1.0    | 8GB  | 1024x1024  | SDXL base model |
| sd_xl_refiner_1.0 | 8GB  | 1024x1024  | SDXL refiner    |
| sd_v1-5           | 4GB  | 512x512    | SD 1.5          |
| sd_v2-1           | 5GB  | 768x768    | SD 2.1          |
| flux_dev          | 24GB | Variable   | Flux.1 Dev      |

---

### KSampler

The primary sampling node for generating images.

```json
{
  "class_type": "KSampler",
  "inputs": {
    "seed": 12345,
    "steps": 30,
    "cfg": 7.5,
    "sampler_name": "euler_ancestral",
    "scheduler": "normal",
    "denoise": 1.0,
    "model": ["1", 0],
    "positive": ["2", 0],
    "negative": ["3", 0],
    "latent_image": ["4", 0]
  }
}
```

| Input          | Type         | Description                           |
| -------------- | ------------ | ------------------------------------- |
| `seed`         | int          | Random seed for reproducibility       |
| `steps`        | int          | Number of sampling steps (1-150)      |
| `cfg`          | float        | Classifier-free guidance scale (1-30) |
| `sampler_name` | string       | Sampling algorithm                    |
| `scheduler`    | string       | Noise schedule                        |
| `denoise`      | float        | Denoising strength (0.0-1.0)          |
| `model`        | MODEL        | Diffusion model connection            |
| `positive`     | CONDITIONING | Positive prompt conditioning          |
| `negative`     | CONDITIONING | Negative prompt conditioning          |
| `latent_image` | LATENT       | Input latent (empty or encoded)       |

| Output | Index | Type   | Description    |
| ------ | ----- | ------ | -------------- |
| LATENT | 0     | LATENT | Sampled latent |

**Sampler Options:**

| Sampler           | Speed  | Quality | Notes                      |
| ----------------- | ------ | ------- | -------------------------- |
| `euler`           | Fast   | Good    | Basic Euler method         |
| `euler_ancestral` | Fast   | Good    | Adds noise, more variation |
| `heun`            | Medium | Better  | 2nd order method           |
| `dpm_2`           | Medium | Better  | DPM-Solver 2nd order       |
| `dpm_2_ancestral` | Medium | Better  | DPM-2 with noise           |
| `dpmpp_2m`        | Fast   | Better  | DPM++ 2M                   |
| `dpmpp_2m_sde`    | Medium | Best    | DPM++ 2M with SDE          |
| `dpmpp_3m_sde`    | Slow   | Best    | DPM++ 3M with SDE          |
| `ddim`            | Fast   | Good    | Deterministic              |
| `uni_pc`          | Fast   | Better  | UniPC sampler              |

**Scheduler Options:**

| Scheduler      | Description                         |
| -------------- | ----------------------------------- |
| `normal`       | Linear noise schedule               |
| `karras`       | Karras noise schedule (recommended) |
| `exponential`  | Exponential schedule                |
| `sgm_uniform`  | SGM uniform schedule                |
| `simple`       | Simple schedule                     |
| `ddim_uniform` | DDIM uniform                        |

---

### KSamplerAdvanced

Advanced sampler with additional control.

```json
{
  "class_type": "KSamplerAdvanced",
  "inputs": {
    "add_noise": "enable",
    "noise_seed": 12345,
    "steps": 30,
    "cfg": 7.5,
    "sampler_name": "dpmpp_2m_sde",
    "scheduler": "karras",
    "start_at_step": 0,
    "end_at_step": 30,
    "return_with_leftover_noise": "disable",
    "model": ["1", 0],
    "positive": ["2", 0],
    "negative": ["3", 0],
    "latent_image": ["4", 0]
  }
}
```

| Additional Inputs            | Type           | Description                  |
| ---------------------------- | -------------- | ---------------------------- |
| `add_noise`                  | enable/disable | Whether to add initial noise |
| `noise_seed`                 | int            | Separate seed for noise      |
| `start_at_step`              | int            | Starting step (for img2img)  |
| `end_at_step`                | int            | Ending step                  |
| `return_with_leftover_noise` | enable/disable | Keep noise for chaining      |

---

## Loading Nodes

### LoraLoader

Loads and applies LoRA weights to model and CLIP.

```json
{
  "class_type": "LoraLoader",
  "inputs": {
    "model": ["1", 0],
    "clip": ["1", 1],
    "lora_name": "my_lora.safetensors",
    "strength_model": 0.8,
    "strength_clip": 0.8
  }
}
```

| Input            | Type   | Description                         |
| ---------------- | ------ | ----------------------------------- |
| `model`          | MODEL  | Input model                         |
| `clip`           | CLIP   | Input CLIP                          |
| `lora_name`      | string | LoRA filename                       |
| `strength_model` | float  | Model weight strength (-2.0 to 2.0) |
| `strength_clip`  | float  | CLIP weight strength (-2.0 to 2.0)  |

| Output | Index | Type  | Description         |
| ------ | ----- | ----- | ------------------- |
| MODEL  | 0     | MODEL | LoRA-enhanced model |
| CLIP   | 1     | CLIP  | LoRA-enhanced CLIP  |

**Stacking LoRAs:**

```json
{
  "1": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" }
  },
  "2": {
    "class_type": "LoraLoader",
    "inputs": {
      "model": ["1", 0],
      "clip": ["1", 1],
      "lora_name": "style_lora.safetensors",
      "strength_model": 0.7,
      "strength_clip": 0.7
    }
  },
  "3": {
    "class_type": "LoraLoader",
    "inputs": {
      "model": ["2", 0],
      "clip": ["2", 1],
      "lora_name": "detail_lora.safetensors",
      "strength_model": 0.5,
      "strength_clip": 0.5
    }
  }
}
```

---

### ControlNetLoader

Loads a ControlNet model.

```json
{
  "class_type": "ControlNetLoader",
  "inputs": {
    "control_net_name": "controlnet-canny-sdxl-1.0.safetensors"
  }
}
```

| Input              | Type   | Description         |
| ------------------ | ------ | ------------------- |
| `control_net_name` | string | ControlNet filename |

| Output      | Index | Type        | Description      |
| ----------- | ----- | ----------- | ---------------- |
| CONTROL_NET | 0     | CONTROL_NET | ControlNet model |

**Common ControlNets:**

| ControlNet          | Type    | Description          |
| ------------------- | ------- | -------------------- |
| controlnet-canny    | Edge    | Canny edge detection |
| controlnet-depth    | Depth   | Depth estimation     |
| controlnet-openpose | Pose    | Human pose           |
| controlnet-scribble | Sketch  | Hand-drawn sketches  |
| controlnet-softedge | Edge    | Soft edge detection  |
| controlnet-lineart  | Line    | Line art             |
| controlnet-tile     | Tile    | Tile/upscale         |
| controlnet-inpaint  | Inpaint | Inpainting           |

---

### VAELoader

Loads a standalone VAE.

```json
{
  "class_type": "VAELoader",
  "inputs": {
    "vae_name": "sdxl_vae.safetensors"
  }
}
```

| Input      | Type   | Description  |
| ---------- | ------ | ------------ |
| `vae_name` | string | VAE filename |

| Output | Index | Type | Description             |
| ------ | ----- | ---- | ----------------------- |
| VAE    | 0     | VAE  | Variational autoencoder |

---

### CLIPLoader

Loads a standalone CLIP model.

```json
{
  "class_type": "CLIPLoader",
  "inputs": {
    "clip_name": "clip_l.safetensors",
    "type": "stable_diffusion"
  }
}
```

---

### UpscaleModelLoader

Loads an upscaling model.

```json
{
  "class_type": "UpscaleModelLoader",
  "inputs": {
    "model_name": "RealESRGAN_x4plus.pth"
  }
}
```

| Output        | Index | Type          | Description    |
| ------------- | ----- | ------------- | -------------- |
| UPSCALE_MODEL | 0     | UPSCALE_MODEL | Upscaler model |

**Common Upscalers:**

| Upscaler                | Scale | Type    | Notes              |
| ----------------------- | ----- | ------- | ------------------ |
| RealESRGAN_x4plus       | 4x    | General | Good all-around    |
| RealESRGAN_x4plus_anime | 4x    | Anime   | Anime/illustration |
| 4x_NMKD-Siax            | 4x    | Photo   | Photorealistic     |
| 4x-UltraSharp           | 4x    | Photo   | Sharp details      |
| 8x_NMKD-Superscale      | 8x    | General | Extreme upscale    |

---

## Conditioning Nodes

### CLIPTextEncode

Encodes text prompts to CLIP embeddings.

```json
{
  "class_type": "CLIPTextEncode",
  "inputs": {
    "text": "A beautiful sunset over mountains, highly detailed, 8k",
    "clip": ["1", 1]
  }
}
```

| Input  | Type   | Description |
| ------ | ------ | ----------- |
| `text` | string | Prompt text |
| `clip` | CLIP   | CLIP model  |

| Output       | Index | Type         | Description     |
| ------------ | ----- | ------------ | --------------- |
| CONDITIONING | 0     | CONDITIONING | Text embeddings |

**Prompt Tips:**

- Use commas to separate concepts
- Add quality boosters: "highly detailed, 8k, masterpiece"
- Specify style: "digital art, oil painting, photograph"
- Add negative prompts in a separate node

---

### CLIPTextEncodeSDXL

SDXL-specific text encoder with dual prompts.

```json
{
  "class_type": "CLIPTextEncodeSDXL",
  "inputs": {
    "text_g": "A beautiful sunset over mountains",
    "text_l": "detailed landscape, golden hour lighting",
    "clip": ["1", 1],
    "width": 1024,
    "height": 1024,
    "crop_w": 0,
    "crop_h": 0,
    "target_width": 1024,
    "target_height": 1024
  }
}
```

| Input                        | Type   | Description                  |
| ---------------------------- | ------ | ---------------------------- |
| `text_g`                     | string | Global/main prompt (CLIP-G)  |
| `text_l`                     | string | Local/detail prompt (CLIP-L) |
| `width/height`               | int    | Original image dimensions    |
| `crop_w/crop_h`              | int    | Crop offset                  |
| `target_width/target_height` | int    | Target dimensions            |

---

### ConditioningCombine

Combines multiple conditioning inputs.

```json
{
  "class_type": "ConditioningCombine",
  "inputs": {
    "cond_1": ["2", 0],
    "cond_2": ["3", 0]
  }
}
```

---

### ConditioningSetArea

Sets conditioning to a specific area (for regional prompts).

```json
{
  "class_type": "ConditioningSetArea",
  "inputs": {
    "conditioning": ["2", 0],
    "width": 512,
    "height": 512,
    "x": 0,
    "y": 0,
    "strength": 1.0
  }
}
```

---

### ControlNetApply / ControlNetApplyAdvanced

Applies ControlNet conditioning.

```json
{
  "class_type": "ControlNetApply",
  "inputs": {
    "conditioning": ["2", 0],
    "control_net": ["5", 0],
    "image": ["6", 0],
    "strength": 0.8
  }
}
```

```json
{
  "class_type": "ControlNetApplyAdvanced",
  "inputs": {
    "positive": ["2", 0],
    "negative": ["3", 0],
    "control_net": ["5", 0],
    "image": ["6", 0],
    "strength": 0.8,
    "start_percent": 0.0,
    "end_percent": 1.0
  }
}
```

| Input           | Type  | Description                      |
| --------------- | ----- | -------------------------------- |
| `strength`      | float | ControlNet influence (0.0-2.0)   |
| `start_percent` | float | When to start applying (0.0-1.0) |
| `end_percent`   | float | When to stop applying (0.0-1.0)  |

---

## Latent Nodes

### EmptyLatentImage

Creates an empty latent for txt2img.

```json
{
  "class_type": "EmptyLatentImage",
  "inputs": {
    "width": 1024,
    "height": 1024,
    "batch_size": 1
  }
}
```

| Input        | Type | Description                           |
| ------------ | ---- | ------------------------------------- |
| `width`      | int  | Image width (must be divisible by 8)  |
| `height`     | int  | Image height (must be divisible by 8) |
| `batch_size` | int  | Number of images to generate          |

**Resolution Guidelines:**

| Model  | Optimal   | Minimum | Maximum   |
| ------ | --------- | ------- | --------- |
| SD 1.5 | 512x512   | 256x256 | 768x768   |
| SD 2.1 | 768x768   | 512x512 | 1024x1024 |
| SDXL   | 1024x1024 | 768x768 | 2048x2048 |
| Flux   | 1024x1024 | 512x512 | 2048x2048 |

---

### LatentUpscale

Upscales latent images.

```json
{
  "class_type": "LatentUpscale",
  "inputs": {
    "samples": ["5", 0],
    "upscale_method": "nearest-exact",
    "width": 2048,
    "height": 2048,
    "crop": "disabled"
  }
}
```

| Input            | Type   | Description                                     |
| ---------------- | ------ | ----------------------------------------------- |
| `upscale_method` | string | nearest-exact, bilinear, area, bicubic, bislerp |
| `width/height`   | int    | Target dimensions                               |
| `crop`           | string | disabled, center                                |

---

### LatentComposite

Composites two latent images.

```json
{
  "class_type": "LatentComposite",
  "inputs": {
    "samples_to": ["5", 0],
    "samples_from": ["6", 0],
    "x": 0,
    "y": 0,
    "feather": 64
  }
}
```

---

### SetLatentNoiseMask

Sets a mask for partial denoising (inpainting).

```json
{
  "class_type": "SetLatentNoiseMask",
  "inputs": {
    "samples": ["5", 0],
    "mask": ["10", 0]
  }
}
```

---

## VAE Nodes

### VAEDecode

Decodes latents to RGB images.

```json
{
  "class_type": "VAEDecode",
  "inputs": {
    "samples": ["5", 0],
    "vae": ["1", 2]
  }
}
```

| Input     | Type   | Description      |
| --------- | ------ | ---------------- |
| `samples` | LATENT | Latent to decode |
| `vae`     | VAE    | VAE model        |

| Output | Index | Type  | Description       |
| ------ | ----- | ----- | ----------------- |
| IMAGE  | 0     | IMAGE | Decoded RGB image |

---

### VAEEncode

Encodes RGB images to latents.

```json
{
  "class_type": "VAEEncode",
  "inputs": {
    "pixels": ["8", 0],
    "vae": ["1", 2]
  }
}
```

| Input    | Type  | Description |
| -------- | ----- | ----------- |
| `pixels` | IMAGE | RGB image   |
| `vae`    | VAE   | VAE model   |

| Output | Index | Type   | Description    |
| ------ | ----- | ------ | -------------- |
| LATENT | 0     | LATENT | Encoded latent |

---

### VAEEncodeForInpaint

Encodes image with mask for inpainting.

```json
{
  "class_type": "VAEEncodeForInpaint",
  "inputs": {
    "pixels": ["8", 0],
    "vae": ["1", 2],
    "mask": ["9", 0],
    "grow_mask_by": 6
  }
}
```

| Input          | Type | Description           |
| -------------- | ---- | --------------------- |
| `mask`         | MASK | Inpainting mask       |
| `grow_mask_by` | int  | Expand mask by pixels |

---

## Image Nodes

### LoadImage

Loads an image from disk or URL.

```json
{
  "class_type": "LoadImage",
  "inputs": {
    "image": "input_image.png"
  }
}
```

| Output | Index | Type  | Description           |
| ------ | ----- | ----- | --------------------- |
| IMAGE  | 0     | IMAGE | Loaded image          |
| MASK   | 1     | MASK  | Alpha channel as mask |

---

### SaveImage

Saves images to disk.

```json
{
  "class_type": "SaveImage",
  "inputs": {
    "filename_prefix": "ComfyUI",
    "images": ["7", 0]
  }
}
```

| Input             | Type   | Description            |
| ----------------- | ------ | ---------------------- |
| `filename_prefix` | string | Output filename prefix |
| `images`          | IMAGE  | Images to save         |

---

### PreviewImage

Previews images without saving.

```json
{
  "class_type": "PreviewImage",
  "inputs": {
    "images": ["7", 0]
  }
}
```

---

### ImageScale

Scales images.

```json
{
  "class_type": "ImageScale",
  "inputs": {
    "image": ["8", 0],
    "upscale_method": "bicubic",
    "width": 2048,
    "height": 2048,
    "crop": "disabled"
  }
}
```

---

### ImageInvert

Inverts image colors.

```json
{
  "class_type": "ImageInvert",
  "inputs": {
    "image": ["8", 0]
  }
}
```

---

### ImageBlend

Blends two images.

```json
{
  "class_type": "ImageBlend",
  "inputs": {
    "image1": ["8", 0],
    "image2": ["9", 0],
    "blend_factor": 0.5,
    "blend_mode": "normal"
  }
}
```

| Input          | Type   | Description                                   |
| -------------- | ------ | --------------------------------------------- |
| `blend_factor` | float  | Blend amount (0.0-1.0)                        |
| `blend_mode`   | string | normal, multiply, screen, overlay, soft_light |

---

## Upscaling Nodes

### ImageUpscaleWithModel

Upscales using an AI model.

```json
{
  "class_type": "ImageUpscaleWithModel",
  "inputs": {
    "upscale_model": ["10", 0],
    "image": ["8", 0]
  }
}
```

| Input           | Type          | Description      |
| --------------- | ------------- | ---------------- |
| `upscale_model` | UPSCALE_MODEL | Loaded upscaler  |
| `image`         | IMAGE         | Image to upscale |

---

### UltimateSDUpscale

Advanced upscaling with tiled sampling.

```json
{
  "class_type": "UltimateSDUpscale",
  "inputs": {
    "image": ["8", 0],
    "model": ["1", 0],
    "positive": ["2", 0],
    "negative": ["3", 0],
    "vae": ["1", 2],
    "upscale_by": 2,
    "seed": 12345,
    "steps": 20,
    "cfg": 7.5,
    "sampler_name": "euler_ancestral",
    "scheduler": "normal",
    "denoise": 0.3,
    "tile_width": 512,
    "tile_height": 512,
    "mask_blur": 8,
    "tile_padding": 32
  }
}
```

---

## Utility Nodes

### PrimitiveNode

Provides a constant value.

```json
{
  "class_type": "PrimitiveNode",
  "inputs": {},
  "widgets_values": [12345]
}
```

---

### Reroute

Organizes workflow connections.

```json
{
  "class_type": "Reroute",
  "inputs": {
    "": ["5", 0]
  }
}
```

---

### Note

Adds documentation to workflows (no execution).

```json
{
  "class_type": "Note",
  "inputs": {},
  "widgets_values": ["This is a workflow note"]
}
```

---

## Custom Manager Nodes

These nodes are from popular custom node packs.

### Efficient Loader (Efficiency Nodes)

Combined checkpoint + VAE + LoRA loading.

```json
{
  "class_type": "Efficient Loader",
  "inputs": {
    "ckpt_name": "sd_xl_base_1.0.safetensors",
    "vae_name": "Baked VAE",
    "clip_skip": -1,
    "lora_name": "None",
    "lora_model_strength": 1,
    "lora_clip_strength": 1,
    "positive": "A beautiful landscape",
    "negative": "blurry, low quality",
    "batch_size": 1
  }
}
```

---

### KSampler (Efficient)

Optimized sampler with built-in preview.

```json
{
  "class_type": "KSampler (Efficient)",
  "inputs": {
    "seed": 12345,
    "steps": 30,
    "cfg": 7.5,
    "sampler_name": "euler_ancestral",
    "scheduler": "normal",
    "denoise": 1,
    "preview_method": "auto",
    "model": ["1", 0],
    "positive": ["1", 1],
    "negative": ["1", 2],
    "latent_image": ["1", 3],
    "optional_vae": ["1", 4]
  }
}
```

---

### IPAdapter

IP-Adapter for image-based conditioning.

```json
{
  "class_type": "IPAdapterApply",
  "inputs": {
    "model": ["1", 0],
    "ipadapter": ["10", 0],
    "image": ["11", 0],
    "weight": 0.8,
    "noise": 0.0,
    "weight_type": "standard"
  }
}
```

---

### FaceDetailer (Impact Pack)

Automatic face detection and enhancement.

```json
{
  "class_type": "FaceDetailer",
  "inputs": {
    "image": ["8", 0],
    "model": ["1", 0],
    "clip": ["1", 1],
    "vae": ["1", 2],
    "positive": ["2", 0],
    "negative": ["3", 0],
    "bbox_detector": ["20", 0],
    "sam_model": ["21", 0],
    "guide_size": 384,
    "guide_size_for": "bbox",
    "max_size": 1024,
    "seed": 12345,
    "steps": 20,
    "cfg": 7.5,
    "sampler_name": "euler_ancestral",
    "scheduler": "normal",
    "denoise": 0.4
  }
}
```

---

## Related Documentation

- [Workflow Documentation](./workflows.md)
- [Performance Tuning](./performance-tuning.md)
- [Custom Node Development](./custom-nodes.md)