# Comfyui Api

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-mckruz-comfyui-expert-comfyui-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MCKRUZ](https://agentstack.voostack.com/s/mckruz)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MCKRUZ](https://github.com/MCKRUZ)
- **Source:** https://github.com/MCKRUZ/ComfyUI-Expert/tree/master/skills/comfyui-api

## Install

```sh
agentstack add skill-mckruz-comfyui-expert-comfyui-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

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

### Offline Mode (No Server)

Export workflow JSON for manual loading in ComfyUI.

1. Generate workflow JSON following ComfyUI's format
2. Save to `projects/{project}/workflows/{name}.json`
3. 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:

1. Queue workflow via `POST /prompt` → get `prompt_id`
2. Poll `GET /history/{prompt_id}` every **5 seconds**
3. On empty response: generation in progress, continue polling
4. On populated response: check `status.completed`
5. If `completed: true`, extract outputs
6. 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:

1. Read `state/inventory.json` (via `comfyui-inventory`)
2. For each node in workflow: verify `class_type` exists in installed nodes
3. For each model reference: verify file exists in installed models
4. 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`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MCKRUZ](https://github.com/MCKRUZ)
- **Source:** [MCKRUZ/ComfyUI-Expert](https://github.com/MCKRUZ/ComfyUI-Expert)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mckruz-comfyui-expert-comfyui-api
- Seller: https://agentstack.voostack.com/s/mckruz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.