comfyui-gateway

ComfyUI Gateway

Overview

REST API gateway for ComfyUI servers. Workflow management, job queuing, webhooks, caching, auth, rate limiting, and image delivery (URL + base64).

When to Use This Skill

• When the user mentions "comfyui" or related topics
• When the user mentions "comfy ui" or related topics
• When the user mentions "stable diffusion api gateway" or related topics
• When the user mentions "gateway comfyui" or related topics
• When the user mentions "api gateway imagens" or related topics
• When the user mentions "queue imagens" or related topics

Do Not Use This Skill When

• The task is unrelated to comfyui gateway
• A simpler, more specific tool can handle the request
• The user needs general-purpose assistance without domain expertise

How It Works

A production-grade REST API gateway that transforms any ComfyUI server into a universal,

secure, and scalable service. Supports workflow templates with placeholders, job queuing

with priorities, webhook callbacks, result caching, and multiple storage backends.

Architecture Overview

┌─────────────┐     ┌──────────────────────────────────┐     ┌──────────┐
│   Clients    │────▶│        ComfyUI Gateway           │────▶│ ComfyUI  │
│ (curl, n8n,  │     │                                  │     │ Server   │
│  Claude,     │     │  ┌─────────┐  ┌──────────────┐  │     │ (local/  │
│  Lovable,    │     │  │ Fastify │  │ BullMQ Queue │  │     │  remote) │
│  Supabase)   │     │  │ API     │──│ (or in-mem)  │  │     └──────────┘
│              │◀────│  └─────────┘  └──────────────┘  │
│              │     │  ┌─────────┐  ┌──────────────┐  │     ┌──────────┐
│              │     │  │ Auth +  │  │ Storage      │  │────▶│ S3/MinIO │
│              │     │  │ RateL.  │  │ (local/S3)   │  │     │(optional)│
│              │     │  └─────────┘  └──────────────┘  │     └──────────┘
└─────────────┘     └──────────────────────────────────┘

Components

| Component | Purpose | File(s) |

|-----------|---------|---------|

| API Gateway | REST endpoints, validation, CORS | src/api/ |

| Worker | Processes jobs, talks to ComfyUI | src/worker/ |

| ComfyUI Client | HTTP + WebSocket to ComfyUI | src/comfyui/ |

| Workflow Manager | Template storage, placeholder rendering | src/workflows/ |

| Storage Provider | Local disk + S3-compatible | src/storage/ |

| Cache | Hash-based deduplication | src/cache/ |

| Notifier | Webhook with HMAC signing | src/notifications/ |

| Auth | API key + JWT + rate limiting | src/auth/ |

| DB | SQLite (better-sqlite3) or Postgres | src/db/ |

| CLI | Init, add-workflow, run, worker | src/cli/ |

Quick Start

## 1. Install

cd comfyui-gateway
npm install

## 2. Configure

cp .env.example .env

## 3. Initialize

npx tsx src/cli/index.ts init

## 4. Add A Workflow

npx tsx src/cli/index.ts add-workflow ./workflows/sdxl_realism_v1.json \
  --id sdxl_realism_v1 --schema ./workflows/sdxl_realism_v1.schema.json

## 5. Start (Api + Worker In One Process)

npm run dev

## Or Separately:

npm run start:api   # API only
npm run start:worker # Worker only

Environment Variables

All configuration is via .env — nothing is hardcoded:

| Variable | Default | Description |

|----------|---------|-------------|

| PORT | 3000 | API server port |

| HOST | 0.0.0.0 | API bind address |

| COMFYUI_URL | http://127.0.0.1:8188 | ComfyUI server URL |

| COMFYUI_TIMEOUT_MS | 300000 | Max wait for ComfyUI (5min) |

| API_KEYS | "" | Comma-separated API keys (key:role) |

| JWT_SECRET | "" | JWT signing secret (empty = JWT disabled) |

| REDIS_URL | "" | Redis URL (empty = in-memory queue) |

| DATABASE_URL | ./data/gateway.db | SQLite path or Postgres URL |

| STORAGE_PROVIDER | local | local or s3 |

| STORAGE_LOCAL_PATH | ./data/outputs | Local output directory |

| S3_ENDPOINT | "" | S3/MinIO endpoint |

| S3_BUCKET | "" | S3 bucket name |

| S3_ACCESS_KEY | "" | S3 access key |

| S3_SECRET_KEY | "" | S3 secret key |

| S3_REGION | us-east-1 | S3 region |

| WEBHOOK_SECRET | "" | HMAC signing secret for webhooks |

| WEBHOOK_ALLOWED_DOMAINS | * | Comma-separated allowed callback domains |

| MAX_CONCURRENCY | 1 | Parallel jobs per GPU |

| MAX_IMAGE_SIZE | 2048 | Maximum dimension (width or height) |

| MAX_BATCH_SIZE | 4 | Maximum batch size |

| CACHE_ENABLED | true | Enable result caching |

| CACHE_TTL_SECONDS | 86400 | Cache TTL (24h) |

| RATE_LIMIT_MAX | 100 | Requests per window |

| RATE_LIMIT_WINDOW_MS | 60000 | Rate limit window (1min) |

| LOG_LEVEL | info | Pino log level |

| PRIVACY_MODE | false | Redact prompts from logs |

| CORS_ORIGINS | * | Allowed CORS origins |

| NODE_ENV | development | Environment |

Health & Capabilities

GET /health
→ { ok: true, version, comfyui: { reachable, url, models? }, uptime }

GET /capabilities
→ { workflows: [...], maxSize, maxBatch, formats, storageProvider }

Workflows (Crud)

GET    /workflows            → list all workflows
POST   /workflows            → register new workflow
GET    /workflows/:id        → workflow details + input schema
PUT    /workflows/:id        → update workflow
DELETE /workflows/:id        → remove workflow

Jobs

POST   /jobs                 → create job (returns jobId immediately)
GET    /jobs/:jobId          → status + progress + outputs
GET    /jobs/:jobId/logs     → sanitized execution logs
POST   /jobs/:jobId/cancel   → request cancellation
GET    /jobs                 → list jobs (filters: status, workflowId, after, before, limit)

Outputs

GET    /outputs/:jobId       → list output files + metadata
GET    /outputs/:jobId/:file → download/stream file

Job Lifecycle

queued → running → succeeded
                 → failed
                 → canceled

1. Client POSTs to /jobs with workflowId + inputs

2. Gateway validates, checks cache, checks idempotency

3. If cache hit → returns existing outputs immediately (status: cache_hit)

4. Otherwise → enqueues job, returns jobId + pollUrl

5. Worker picks up job, renders workflow template, submits to ComfyUI

6. Worker polls ComfyUI for progress (or listens via WebSocket)

7. On completion → downloads outputs, stores them, updates DB

8. If callbackUrl → sends signed webhook POST

9. Client polls /jobs/:jobId or receives webhook

Workflow Templates

Workflows are ComfyUI JSON with {{placeholder}} tokens. The gateway resolves

these at runtime using the job's inputs and params:

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": "{{seed}}",
      "steps": "{{steps}}",
      "cfg": "{{cfg}}",
      "sampler_name": "{{sampler}}",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "{{prompt}}",
      "clip": ["4", 1]
    }
  }
}

Each workflow has an inputSchema (Zod) that validates what the client sends.

Security Model

• API Keys: X-API-Key header; keys configured via API_KEYS env var as key1:admin,key2:user
• JWT: Optional; when JWT_SECRET is set, accepts Authorization: Bearer <token>
• Roles: admin (full CRUD on workflows + jobs), user (create jobs, read own jobs)
• Rate Limiting: Per key + per IP, configurable window and max
• Webhook Security: HMAC-SHA256 signature in X-Signature header
• Callback Allowlist: Only approved domains receive webhooks
• Privacy Mode: When enabled, prompts are redacted from logs and DB
• Idempotency: metadata.requestId prevents duplicate processing
• CORS: Configurable allowed origins
• Input Validation: Zod schemas on every endpoint; max size/batch enforced

Comfyui Integration

The gateway communicates with ComfyUI via its native HTTP API:

| ComfyUI Endpoint | Gateway Usage |

|------------------|---------------|

| POST /prompt | Submit rendered workflow |

| GET /history/{id} | Poll job completion |

| GET /view?filename=... | Download generated images |

| GET /object_info | Discover available nodes/models |

| WS /ws?clientId=... | Real-time progress (optional) |

The client auto-detects ComfyUI version and adapts:

• Tries WebSocket first for progress, falls back to polling
• Handles both /history response formats
• Detects OOM errors and classifies them with recommendations

Cache Strategy

Cache key = SHA-256 of workflowId + sorted(inputs) + sorted(params) + checkpoint.

On cache hit, the gateway returns a "virtual" job with pre-existing outputs — no GPU

computation needed. Cache is stored alongside job data in the DB with configurable TTL.

Error Classification

| Error Code | Meaning | Retry? |

|------------|---------|--------|

| COMFYUI_UNREACHABLE | Cannot connect to ComfyUI | Yes (with backoff) |

| COMFYUI_OOM | Out of memory on GPU | No (reduce dimensions) |

| COMFYUI_TIMEOUT | Execution exceeded timeout | Maybe (increase timeout) |

| COMFYUI_NODE_ERROR | Node execution failed | No (check workflow) |

| VALIDATION_ERROR | Invalid inputs | No (fix request) |

| WORKFLOW_NOT_FOUND | Unknown workflowId | No (register workflow) |

| RATE_LIMITED | Too many requests | Yes (wait) |

| AUTH_FAILED | Invalid/missing credentials | No (fix auth) |

| CACHE_HIT | (Not an error) Served from cache | N/A |

Bundled Workflows

Three production-ready workflow templates are included:

1. Sdxl_Realism_V1 — Photorealistic Generation

• Checkpoint: SDXL base
• Optimized for: Portraits, landscapes, product shots
• Default: 1024x1024, 30 steps, cfg 7.0

2. Sprite_Transparent_Bg — Game Sprites With Alpha

• Checkpoint: SD 1.5 or SDXL
• Optimized for: 2D game assets, transparent backgrounds
• Default: 512x512, 25 steps, cfg 7.5

3. Icon_512 — App Icons With Optional Upscale

• Checkpoint: SDXL base
• Optimized for: Square icons, clean edges
• Default: 512x512, 20 steps, cfg 6.0, optional 2x upscale

Observability

• Structured Logs: Pino JSON logs with correlationId on every request
• Metrics: Jobs queued/running/succeeded/failed, avg processing time, cache hit rate
• Audit Log: Admin actions (workflow CRUD, key management) logged with timestamp + actor

Cli Reference

npx tsx src/cli/index.ts init                    # Create dirs, .env.example
npx tsx src/cli/index.ts add-workflow <file>      # Register workflow template
  --id <id> --name <name> --schema <schema.json>
npx tsx src/cli/index.ts list-workflows           # Show registered workflows
npx tsx src/cli/index.ts run                      # Start API server
npx tsx src/cli/index.ts worker                   # Start job worker
npx tsx src/cli/index.ts health                   # Check ComfyUI connectivity

Troubleshooting

Read references/troubleshooting.md for detailed guidance on:

• ComfyUI not reachable (firewall, wrong port, Docker networking)
• OOM errors (reduce resolution, batch, or steps)
• Slow generation (GPU utilization, queue depth, model loading)
• Webhook failures (DNS, SSL, timeout, domain allowlist)
• Redis connection issues (fallback to in-memory)
• Storage permission errors (local path, S3 credentials)

Integration Examples

Read references/integration.md for ready-to-use examples with:

• curl commands for every endpoint
• n8n webhook workflow
• Supabase Edge Function caller
• Claude Code / Claude.ai integration
• Python requests client
• JavaScript fetch client

File Structure