Skip to content

COMFYUI_API.md

Latest commit

 

History

History
146 lines (119 loc) · 9.66 KB

COMFYUI_API.md

File metadata and controls

146 lines (119 loc) · 9.66 KB

Comfy UI API end-points

Sourced and made digestible after extensive internet searches, forum browsing, issue trackers, and insufficient documentation

HTTP Endpoints

Endpoint Method Purpose Example Response Example Test Command Implementation Status
/prompt POST Submit workflow {"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde", "number": 1, "node_errors": {}} Header: http://127.0.0.1:8189/prompt
Body: {"prompt": {…},"client_id":"df1465dc01f6446aa65e117c151c44d0"}		 ✅ Used
/queue GET Get current queue status {"queue_running": [{"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde", "number": 1}], "queue_pending": [{"prompt_id": "7a973e1f-58b9-42d6-b3c5-e7adef5632dc", "number": 2}]} http GET http://127.0.0.1:8189/queue ✅ Used
/history GET Get execution history {"6f962d0e-40d9-45e8-b378-7247258cadde": {"prompt": {...}, "outputs": {...}, "status": "complete"}} http GET http://127.0.0.1:8189/history ✅ Used
/history/{prompt_id} GET Get specific execution {"prompt": {...}, "outputs": {...}, "status": "complete"} http GET http://127.0.0.1:8189/history/6f962d0e-40d9-45e8-b378-7247258cadde ✅ Used
/view GET View generated images Binary image data (PNG/JPEG) http GET http://127.0.0.1:8189/view?filename=ComfyUI_00042_.png --output image.png ✅ Used
/upload/image POST Upload input image {"name": "uploaded_image.png", "subfolder": "", "type": "input"} http -f POST curl -X POST -F "image=@/path/to/your/image.jpg" http://localhost:8189/upload/image ✅ Used
/upload/mask POST Upload mask image {"name": "uploaded_mask.png", "subfolder": "", "type": "mask"} http -f POST http://127.0.0.1:8189/upload/mask image@/path/to/mask.png ❌ Not Used
/object_info GET Get node information {"CheckpointLoaderSimple": {"input": {...}, "output": {...}}, "KSampler": {...}} (Large JSON with all node types) http GET http://127.0.0.1:8189/object_info ❌ Not Used
/system_stats GET Get system statistics {"cuda": {"gpu": "NVIDIA GeForce RTX 3080", "vram_total": 10240, "vram_free": 8192}, "system": {"cpu_percent": 25.6, "ram_total": 32768, "ram_free": 16384}} http GET http://127.0.0.1:8189/system_stats ✅ Used
/extensions GET List installed extensions {"extensions": ["ComfyUI-Manager", "ComfyUI-Impact-Pack"]} http GET http://127.0.0.1:8189/extensions ❌ Not used
/interrupt POST Stop execution {"success": true} http POST http://127.0.0.1:8189/interrupt ✅ Used

WebSocket Messages

Message Type Direction Purpose Example Message Implementation Status
status Server→Client System status {"type": "status", "data": {"status": {"exec_info": {"queue_remaining": 1}}, "sid": "4921363473c149bfaab99efa190033b3"}} ✅ Used to get session ID
execution_start Server→Client Execution begins {"type": "execution_start", "data": {"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Monitored in script
execution_cached Server→Client Results from cache {"type": "execution_cached", "data": {"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde", "nodes": ["1", "2", "3"]}} ✅ Monitored in script
executing Server→Client Current node {"type": "executing", "data": {"node": "5", "prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Monitored and displayed
progress Server→Client Generation progress {"type": "progress", "data": {"value": 10, "max": 20, "prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Monitored with percentage & for preview image data grabbing
executed Server→Client Node completion {"type": "executed", "data": {"node": "5", "output": {"images": [...]}, "prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Monitored in script
execution_error Server→Client Error reporting {"type": "execution_error", "data": {"node": "5", "exception_message": "CUDA out of memory", "prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Basic error handling
execution_complete Server→Client Execution finished {"type": "execution_complete", "data": {"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Used to detect completion
Client message Client→Server Set client ID {"client_id": "test_client"} ✅ Used for connection tracking
Client message Client→Server Subscribe to updates {"op": "subscribe_to_prompt", "data": {"prompt_id": "6f962d0e-40d9-45e8-b378-7247258cadde"}} ✅ Used for monitoring

Execution Flow Diagram

If mermaid is not visisble in your markdown renderer, checkout the png /svg / UML

sequenceDiagram
    title ComfyUI API Interaction Flow
    
    actor Client
    participant WS as WebSocket Server
    participant HTTP as HTTP Server
    participant Engine as Execution Engine
    participant Storage as Image Storage
    
    %% Connection & Initialization
    rect rgb(240, 240, 255)
        Note over Client, Storage: Connection & Initialization
        Client->>WS: Connect to ws://host:port/ws
        WS-->>Client: Status message with session_id
        Client->>WS: Set client_id (using session_id)
    end
    
    %% Workflow Submission
    rect rgb(240, 255, 240)
        Note over Client, Storage: Workflow Submission
        Client->>HTTP: POST /prompt with workflow JSON
        HTTP-->>Client: Response with prompt_id
        Client->>WS: Subscribe to prompt updates
    end
    
    %% Execution Process
    rect rgb(255, 240, 240)
        Note over Client, Storage: Execution Process
        WS-->>Client: execution_start event
        Note right of Client: Workflow begins processing
        
        alt Cached Results Available
            WS-->>Client: execution_cached event
            Note right of Client: Some nodes use cached results
        end
        
        loop Node Execution
            WS-->>Client: executing event (node X)
            Engine->>Engine: Process node
            
            opt If KSampler or generation node
                loop For each step
                    WS-->>Client: progress event (step N/total)
                    Engine->>Engine: Generation step
                end
            end
            
            WS-->>Client: executed event (node X complete)
            Note right of Client: Node output available
        end
    end
    
    %% Completion & Output
    rect rgb(255, 255, 240)
        Note over Client, Storage: Completion & Output
        WS-->>Client: execution_complete event
        Engine->>Storage: Save generated images
    end
    
    %% Optional Image Retrieval
    rect rgb(240, 255, 255)
        Note over Client, Storage: Optional Image Retrieval
        Client->>HTTP: GET /view?filename=output.png
        HTTP->>Storage: Retrieve image
        Storage-->>HTTP: Image data
        HTTP-->>Client: Binary image data
    end
    
    %% Optional Error Handling
    rect rgb(255, 240, 255)
        Note over Client, Storage: Optional Error Handling
        alt If Error Occurs
            WS-->>Client: execution_error event
            Note right of Client: Contains error details
        end
    end
    
    %% Optional Cancellation
    rect rgb(245, 245, 245)
        Note over Client, Storage: Optional Cancellation
        alt If User Cancels
            Client->>HTTP: POST /interrupt
            HTTP->>Engine: Stop execution
            WS-->>Client: Status update (execution stopped)
        end
    end
Loading

Credits & Sources

Descending order of discovery

  1. Official ComfyUI Github:ISSUE:2110
  2. Official ComfyUI Github: ComfyUI's script_examples
  3. Official ComfyUI docs: docs.comfy.org/essentials/comms_routes
  4. Official ComfyUI docs: docs.comfy.org/essentials/comfyui-server/comms_messages#built-in-message-types
  5. Medium Article: ComfyUI : WebSockets API : Part 1
  6. Medium Article: ComfyUI : WebSockets API : Part 2
  7. Medium Article: ComfyUI : WebSockets API : Part 3