Manage ComfyUI Workflows and Jobs

ComfyUI Gateway is a REST API gateway for ComfyUI servers, providing workflow management, job queuing, webhooks, caching, auth, rate limiting, and image delivery (URL or base64). Its architecture sits clients (curl, n8n, Claude, Lovable, Supabase) in front of a Fastify API plus a BullMQ (or in-memory) job queue, auth/rate-limiting, and local or S3-compatible storage, which together talk to a local or remote ComfyUI server. Ten named components structure the codebase: API Gateway (REST endpoints, validation, CORS), Worker (job processing, talks to ComfyUI), ComfyUI Client (HTTP + WebSocket), Workflow Manager (template storage, placeholder rendering), Storage Provider (local disk + S3), Cache (hash-based deduplication), Notifier (HMAC-signed webhooks), Auth (API key + JWT + rate limiting), DB (SQLite via better-sqlite3, or Postgres), and a CLI (init, add-workflow, run, worker). Setup:

cd comfyui-gateway
npm install

then cp .env.example .env, npx tsx src/cli/index.ts init, add a workflow with add-workflow plus its JSON schema, and start with npm run dev (combined) or npm run start:api / npm run start:worker separately.

Use this skill when the user mentions ComfyUI, "comfy ui," a stable diffusion API gateway, "gateway comfyui," or image/queue generation via API. It is not for tasks unrelated to a ComfyUI gateway, when a simpler more specific tool would handle the request, or when the user needs general-purpose assistance without this domain's expertise.

A job's lifecycle: a client POSTs to /jobs with a workflowId and inputs; the gateway validates, checks cache, and checks idempotency; a cache hit returns existing outputs immediately with status cache_hit; otherwise the job is enqueued and a jobId/pollUrl returned; a worker picks it up, renders the workflow template, submits to ComfyUI, polls or listens via WebSocket for progress, downloads and stores outputs on completion, and sends a signed webhook if a callbackUrl was given; the client polls /jobs/:jobId or receives the webhook. Job status transitions queued to running to succeeded/failed/canceled. Three bundled, production-ready workflow templates ship by default: sdxl_realism_v1 (SDXL base checkpoint, portraits/landscapes/product shots, 1024x1024 at 30 steps/cfg 7.0), sprite_transparent_bg (SD 1.5 or SDXL, 2D game assets with alpha transparency, 512x512 at 25 steps/cfg 7.5), and icon_512 (SDXL base, square icons with clean edges, 512x512 at 20 steps/cfg 6.0, optional 2x upscale).

Built on Fastify, BullMQ, SQLite/Postgres, and S3-compatible storage in front of a ComfyUI server, with a security model covering API-key/JWT auth and rate limiting, a cache strategy for deduplicating identical requests, and error classification for surfacing ComfyUI/queue/storage failures distinctly. Documented CLI reference, troubleshooting guide, integration examples, and file structure round out the reference material.

Teams building an image-generation API on top of ComfyUI who need production concerns handled - job queuing, caching, webhooks, auth, rate limiting, and S3-compatible output storage - rather than calling ComfyUI's own API directly from application code.