ComfyUI/docs/api/prompt-schema.md

ComfyUI Prompt API Schema Documentation

Overview

This document describes the JSON Schema for ComfyUI's /prompt API endpoint. The schema provides formal validation and documentation for the prompt format used when submitting workflows via the API.

Schema Location

• Schema File: schemas/prompt.json
• Schema ID: https://github.com/comfyanonymous/ComfyUI/schemas/prompt.json

Quick Start

Validating a Prompt

import json
import jsonschema

with open('schemas/prompt.json') as f:
    schema = json.load(f)

with open('your_prompt.json') as f:
    prompt = json.load(f)

# Validate
jsonschema.validate(prompt, schema)
print("✅ Prompt is valid!")

Format Overview

The prompt format is a JSON object containing:

{
  "prompt": {
    "node_id_1": { /* node definition */ },
    "node_id_2": { /* node definition */ },
    ...
  },
  "extra_data": { /* optional */ },
  "client_id": "optional-client-id"
}

Node Structure

Each node has:

• class_type: The node class (e.g., "KSampler", "CLIPTextEncode")
• inputs: Input parameters
• _meta: Optional metadata

Input Values

Inputs can be:

1. Direct values: Numbers, strings, booleans, arrays, objects
2. Node links: ["node_id", output_index] to reference another node

Examples

Basic Text-to-Image

{
  "prompt": {
    "3": {
      "class_type": "KSampler",
      "inputs": {
        "seed": 123456789,
        "steps": 20,
        "cfg": 8.0,
        "sampler_name": "euler",
        "scheduler": "normal",
        "denoise": 1.0,
        "model": ["4", 0],
        "positive": ["6", 0],
        "negative": ["7", 0],
        "latent_image": ["5", 0]
      }
    },
    "4": {
      "class_type": "CheckpointLoaderSimple",
      "inputs": {
        "ckpt_name": "model.safetensors"
      }
    },
    "5": {
      "class_type": "EmptyLatentImage",
      "inputs": {
        "width": 512,
        "height": 512,
        "batch_size": 1
      }
    },
    "6": {
      "class_type": "CLIPTextEncode",
      "inputs": {
        "text": "beautiful scenery",
        "clip": ["4", 1]
      }
    },
    "7": {
      "class_type": "CLIPTextEncode",
      "inputs": {
        "text": "text, watermark",
        "clip": ["4", 1]
      }
    },
    "8": {
      "class_type": "VAEDecode",
      "inputs": {
        "samples": ["3", 0],
        "vae": ["4", 2]
      }
    },
    "9": {
      "class_type": "SaveImage",
      "inputs": {
        "filename_prefix": "ComfyUI",
        "images": ["8", 0]
      }
    }
  }
}

Workflow vs Prompt Format

Workflow Format (UI Internal)

Used by the web interface for saving/loading workflows.

{
  "last_node_id": 9,
  "last_link_id": 5,
  "nodes": [...],
  "links": [...],
  "groups": [...]
}

Prompt Format (API)

Used by the /prompt API endpoint for execution.

{
  "prompt": {
    "3": { "class_type": "KSampler", "inputs": {...} },
    ...
  }
}

Key Differences:

• Workflow contains UI metadata (positions, colors)
• Prompt is execution-focused (just nodes and connections)
• Workflow is converted to prompt format before execution

Common Node Types

Loaders

• CheckpointLoaderSimple: Load model checkpoints
• VAELoader: Load VAE models
• LoraLoader: Load LoRA models

Encoders

• CLIPTextEncode: Encode text prompts
• CLIPTextEncodeSDXL: SDXL text encoding

Samplers

• KSampler: Standard sampling
• KSamplerAdvanced: Advanced sampling options

Image Operations

• EmptyLatentImage: Create empty latent
• VAEDecode: Decode latent to image
• VAEDecodeTiled: Tiled decoding for large images
• SaveImage: Save output image

Future Enhancements

Dynamic Schemas

Future versions may support:

• Node-specific validation based on installed custom nodes
• Input type validation beyond basic JSON types
• Required vs optional input validation
• Dependency checking between nodes

IDE Integration

The schema enables:

• Auto-completion in IDEs (VS Code, PyCharm, etc.)
• Real-time validation during development
• Documentation tooltips

Contributing

To extend the schema:

1. Add new node types to the definitions
2. Include examples for complex use cases
3. Update documentation with validation rules
4. Test with existing prompts

References

• ComfyUI API Documentation
• JSON Schema Specification
• Original Feature Request #8899