comfyui-api

Original：🇺🇸 English

Translated

Connect to a running ComfyUI instance, queue workflows, monitor execution, and retrieve results. Supports both online (REST API) and offline (JSON export) modes. Use when executing ComfyUI workflows or checking server status.

5installs

Sourcemckruz/comfyui-expert

Added on2026-03-01

NPX Install

npx skill4agent add mckruz/comfyui-expert comfyui-api

SKILL.md Content

View Translation Comparison →

ComfyUI API Skill

Connect to ComfyUI's REST API to execute workflows, monitor progress, and retrieve outputs.

Configuration

Default URL:
```
http://127.0.0.1:8188
```
Custom URL: Set in project manifest or pass as parameter
Timeout: 30s for API calls, no timeout for generation polling

Two Modes

Online Mode (ComfyUI Running)

Full API access. Preferred mode for interactive work.

Test connection:
```
GET /system_stats
```
Discover capabilities: Use
```
comfyui-inventory
```
skill
Queue workflow:
```
POST /prompt
```
Poll for results:
```
GET /history/{prompt_id}
```
every 5 seconds
Retrieve outputs:
```
GET /view?filename=...
```

Offline Mode (No Server)

Export workflow JSON for manual loading in ComfyUI.

Generate workflow JSON following ComfyUI's format

Save to

projects/{project}/workflows/{name}.json

Instruct user to drag-drop into ComfyUI

API Operations

Check Server Status

bash

curl http://127.0.0.1:8188/system_stats

Response fields:

```
system.os
```
: Operating system
```
system.comfyui_version
```
: Version string
```
devices[0].name
```
: GPU name
```
devices[0].vram_total
```
: Total VRAM bytes
```
devices[0].vram_free
```
: Free VRAM bytes

Queue a Workflow

bash

curl -X POST http://127.0.0.1:8188/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": WORKFLOW_JSON, "client_id": "video-agent"}'

WORKFLOW_JSON format:

json

{
  "1": {
    "class_type": "LoadCheckpoint",
    "inputs": {
      "ckpt_name": "flux1-dev.safetensors"
    }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "photorealistic portrait...",
      "clip": ["1", 1]
    }
  }
}

Each node is keyed by a string ID. Inputs reference other nodes as

["{node_id}", {output_index}]

.

Response:

json

{"prompt_id": "abc-123-def", "number": 1}

Poll for Completion

bash

curl http://127.0.0.1:8188/history/abc-123-def

Incomplete: Returns

{}

(empty object) Complete: Returns execution data with outputs:

json

{
  "abc-123-def": {
    "outputs": {
      "9": {
        "images": [{"filename": "ComfyUI_00001.png", "subfolder": "", "type": "output"}]
      }
    },
    "status": {"completed": true}
  }
}

Retrieve Output Image

bash

curl "http://127.0.0.1:8188/view?filename=ComfyUI_00001.png&subfolder=&type=output" -o output.png

Upload Reference Image

bash

curl -X POST http://127.0.0.1:8188/upload/image \
  -F "image=@reference.png" \
  -F "subfolder=input" \
  -F "type=input"

Cancel Current Generation

bash

curl -X POST http://127.0.0.1:8188/interrupt

Free VRAM

bash

curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true}'

Polling Strategy

ComfyUI doesn't support WebSocket in CLI context. Use REST polling:

Queue workflow via
```
POST /prompt
```
→ get
```
prompt_id
```
Poll
```
GET /history/{prompt_id}
```
every 5 seconds
On empty response: generation in progress, continue polling
On populated response: check
```
status.completed
```
If
```
completed: true
```
, extract outputs
If error in status, route to
```
comfyui-troubleshooter
```

Timeout: Warn user after 10 minutes of polling. Video generation (Wan 14B) can take 15-30 minutes.

Workflow Validation

Before queuing any workflow:

Read
```
state/inventory.json
```
(via
```
comfyui-inventory
```
)
For each node in workflow: verify
```
class_type
```
exists in installed nodes
For each model reference: verify file exists in installed models
Flag missing items with:
- Node: suggest
```
ComfyUI-Manager
```
  install command
- Model: provide download link from
```
references/models.md
```
- Version mismatch: suggest update

Error Handling

Error	Cause	Action
Connection refused	ComfyUI not running	Switch to offline mode, save JSON
400 Bad Request	Invalid workflow JSON	Validate node connections
500 Internal Error	ComfyUI crash	Suggest restart, check logs
Timeout (no response)	Server overloaded	Wait and retry once

Reference

Full API documentation:

foundation/api-quick-ref.md

comfyui-api

NPX Install

Tags

SKILL.md Content

ComfyUI API Skill

Configuration

Two Modes

Online Mode (ComfyUI Running)

Offline Mode (No Server)

API Operations

Check Server Status

Queue a Workflow

Poll for Completion

Retrieve Output Image

Upload Reference Image

Cancel Current Generation

Free VRAM

Polling Strategy

Workflow Validation

Error Handling

Reference