ComfyUI client based on the WebSockets API example.
Isomorphic: works in Node.js (>= 22, or any version with the ws package installed) and in browsers / Electron renderers. No static Node-only imports — WebSocket is the platform global, fs is only touched by saveImages() (Node-only), and the default logger is console (inject any pino-like logger via options.logger).
See example in examples/generate.
To install @artifyfun/comfy-ui-client in an existing project:
npm install @artifyfun/comfy-ui-clientimport { ComfyUIClient } from '@artifyfun/comfy-ui-client';
import type { Prompt } from '@artifyfun/comfy-ui-client';
// Your prompt / workflow
const prompt: Prompt = {
'3': {
class_type: 'KSampler',
inputs: {
cfg: 8,
denoise: 1,
latent_image: ['5', 0],
model: ['4', 0],
negative: ['7', 0],
positive: ['6', 0],
sampler_name: 'euler',
scheduler: 'normal',
seed: 8566257,
steps: 20,
},
},
'4': {
class_type: 'CheckpointLoaderSimple',
inputs: {
ckpt_name: 'v1-5-pruned-emaonly.cpkt',
},
},
'5': {
class_type: 'EmptyLatentImage',
inputs: {
batch_size: 1,
height: 512,
width: 512,
},
},
'6': {
class_type: 'CLIPTextEncode',
inputs: {
clip: ['4', 1],
text: 'masterpiece best quality girl',
},
},
'7': {
class_type: 'CLIPTextEncode',
inputs: {
clip: ['4', 1],
text: 'bad hands',
},
},
'8': {
class_type: 'VAEDecode',
inputs: {
samples: ['3', 0],
vae: ['4', 2],
},
},
'9': {
class_type: 'SaveImage',
inputs: {
filename_prefix: 'ComfyUI',
images: ['8', 0],
},
},
};
// Set the text prompt for our positive CLIPTextEncode
prompt['6'].inputs.text = 'masterpiece best quality man';
// Set the seed for our KSampler node
prompt['3'].inputs.seed = 5;
// Create client
const serverAddress = '127.0.0.1:8188';
// Create client (options are optional)
const serverAddress = '127.0.0.1:8188'; // or https://comfy.example.com
const clientId = 'baadbabe-b00b-4206-9420-deadd00d1337';
const client = new ComfyUIClient(serverAddress, clientId, {
// apiToken: '...', // Bearer auth for multi-user servers
// requestTimeoutMs: 60000, // HTTP request timeout (default 60s)
// logger: console, // inject your own pino-like logger
});
// Connect to server (rejects on failure / timeout)
await client.connect();
// Generate images with progress reporting, per-node callbacks,
// and a timeout. Rejects on execution_error / interrupted /
// disconnect / timeout instead of hanging forever.
const images = await client.getImages(prompt, {
timeoutMs: 10 * 60_000,
onProgress: (p) => console.log(`progress: ${p.value}/${p.max}`),
onExecuting: (d) => {
if (d.node) console.log(`executing node ${d.node}`);
},
});
// Save images to file (parallel, preserves subfolders)
const outputDir = './tmp/output';
await client.saveImages(images, outputDir);
// Disconnect
client.disconnect();new ComfyUIClient(serverAddress, clientId, options?)| Option | Type | Default | Description |
|---|---|---|---|
serverAddress |
string |
— | host:port; http(s):// / ws(s):// detected automatically |
clientId |
string |
— | Session id used on the WebSocket connection |
options.apiToken |
string |
— | Sent as Authorization: Bearer (multi-user servers) |
options.requestTimeoutMs |
number |
60000 |
Per-request HTTP timeout; 0 disables |
options.logger |
LoggerLike |
pino (info) |
pino-like logger (console works) |
connect(timeoutMs?)/disconnect()/isConnected()— WebSocket lifecycle.connectrejects on connection failure or timeout.getImages(prompt, options?)— queue a workflow, wait for completion, download image outputs.getOutputs(prompt, options?)— same, but downloads all output kinds (images, videos, audio).waitForPrompt(prompt, options?)— queue and wait, resolving with the history entry (no downloads).saveImages(images, outputDir)— write downloaded outputs to disk in parallel, preserving subfolders.
GetImagesOptions:
| Option | Type | Description |
|---|---|---|
timeoutMs |
number |
Overall execution timeout (0/undefined = none) |
onProgress |
(p: ProgressData) => void |
Sampling progress (value / max) |
onExecuting |
(d: ExecutingData) => void |
Node execution events (node === null = done) |
signal |
AbortSignal |
Cancel waiting (does not stop server execution) |
client.on(event, handler) / client.off(event, handler):
status, progress, executing, executing_cached, execution_start,
execution_success, execution_error, execution_interrupted,
preview (parsed binary previews), disconnected.
getEmbeddings(),getExtensions()getSystemStats(),getStats()(newer servers)getPrompt()— queue remainingqueuePrompt(prompt),interrupt()getQueue(),editQueue({ clear?, delete?, delete_iterative? })freeMemory({ unload_models?, free_memory? })—POST /freegetHistory(promptId?, maxItems?),editHistory({ clear?, delete? })getObjectInfo(nodeClass?),getObjectInfoFor(nodeClasses[])— subset viaPOST /object_info(newer servers)viewMetadata(folderName, filename)getImage({ filename, subfolder, type, channel?, download? })—GET /view; also accepts positional(filename, subfolder, type)uploadImage(image, filename, { overwrite?, type?, subfolder? }?)uploadMask(image, filename, originalRef, { overwrite? }?)
All failures throw ComfyUIClientError with .status (HTTP status, when
applicable) and .payload (raw server error, e.g. node_errors).
Aligned with ComfyUI master (server.py):
- Completion is detected via the
execution_successWS message (new servers) with fallback to the legacyexecuting+node === nullsignal. - History keys are prompt ids; outputs include
images,videos(formerlygifs), andaudio. - Binary WS previews are parsed (8-byte header: event type, format, width,
height) and emitted as
previewevents.
This project is licensed under the MIT License.