comfyui-core

ComfyUI Core Knowledge

Workflow JSON Format (API Format)

ComfyUI workflows are JSON objects mapping string node IDs to node definitions:

{
  "1": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" },
    "_meta": { "title": "Load Checkpoint" }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": { "text": "a cat", "clip": ["1", 1] },
    "_meta": { "title": "Positive Prompt" }
  }
}

Key Rules

• Node IDs are strings of integers ("1", "2", etc.)
• class_type is the exact Python class name of the node
• inputs contains both widget values (scalars) and connections (arrays)
• Connections use the format ["sourceNodeId", outputIndex] — a 2-element array where:
  • First element: string node ID of the source node
  • Second element: integer index into the source node's output list (0-based)
• _meta is optional, used for display titles only

Connection Examples

"model": ["1", 0]       // Connect to node 1's first output (MODEL)
"clip": ["1", 1]        // Connect to node 1's second output (CLIP)
"vae": ["1", 2]         // Connect to node 1's third output (VAE)
"positive": ["2", 0]    // Connect to node 2's first output (CONDITIONING)
"samples": ["5", 0]     // Connect to node 5's first output (LATENT)
"images": ["6", 0]      // Connect to node 6's first output (IMAGE)

Important: API Format vs Web UI Format

• API format (for execution/analysis): { "1": { class_type, inputs }, "2": { ... } } — compact, used by enqueue_workflow, validate_workflow, modify_workflow, etc.
• Web UI format (for saving and frontend editing): { "nodes": [...], "links": [...] } — includes layout positions, sizes, groups, and visual metadata so ComfyUI's canvas can open and edit it
• Execution tools expect and return API format
• Saving tools must use Web UI format so saved workflows stay readable and editable in the ComfyUI frontend — an API-format save "exists" in the library but loads blank in the canvas, which strands users (and tempts agents into creating yet another new workflow instead of reopening the old one)
• get_workflow defaults to format="api" for analysis/execution; use format="ui" when loading a workflow to re-save or edit in the canvas
• Muted/bypassed nodes are preserved with _meta.mode: "muted" — these are inactive but visible for understanding the workflow
• Get/Set virtual wire nodes are preserved with _meta.title and Constant key for tracing data flow