comfy-api-helper
v2.0.1
Published
A Typescript helper library to make using the ComfyUI API easier
Readme
Comfy API Helper
A lightweight TypeScript helper library for generating images from a local ComfyUI instance.
Version 2.0.0 introduces a simpler, more reliable execution model built around ComfyUI's WebSocket events instead of queue/history polling. This makes repeated identical workflow runs work correctly, including cached executions.
What's new in 2.0
- Switched to WebSocket-based execution tracking
- Properly correlates requests with ComfyUI using
clientId/client_id - Handles cached workflow executions correctly
- Clearer user-facing error messages for:
- connection failures
- malformed/rejected workflows
- workflows that run but do not produce usable image outputs
- Refactored internal structure into:
src/index.tssrc/helpers.tssrc/types.ts
Installation
Using npm:
npm install comfy-api-helperUsing Bun:
bun add comfy-api-helperUsing pnpm:
pnpm add comfy-api-helperRequirements
- Node.js
>=18 - A running ComfyUI instance
- A workflow exported from ComfyUI in API format
- Any models and custom nodes required by that workflow installed in your ComfyUI instance
Quick start
Export a workflow from ComfyUI using:
File -> Export (API)
Then call generateImages(...) with that workflow object and your ComfyUI endpoint.
import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import workflow from './workflow.json' with { type: 'json' };
const COMFY_ENDPOINT = 'http://127.0.0.1:8188';
const images = await generateImages(workflow, COMFY_ENDPOINT);
fs.writeFileSync('output.png', images[0]);Usage
This library is designed for workflows that produce one or more saved or previewed image outputs.
If you want to modify prompts, checkpoints, seeds, or other inputs programmatically, a good pattern is to wrap your exported workflow JSON in a small factory function.
Example: procedural workflow builder
import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import { workflowApiFactory } from './workflow';
const COMFY_ENDPOINT = 'http://127.0.0.1:8188';
const CHECKPOINT = 'Illustrious/novaAnimeXL_ilV120.safetensors';
const PROMPT =
'cute anime girl with massive fluffy fennec ears and a big fluffy tail';
const workflow = workflowApiFactory(PROMPT, CHECKPOINT);
const images = await generateImages(workflow, COMFY_ENDPOINT);
fs.writeFileSync('output.png', images[0]);Example: direct workflow JSON
import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import workflow from './workflow.json' with { type: 'json' };
const COMFY_ENDPOINT = 'http://127.0.0.1:8188';
const images = await generateImages(workflow, COMFY_ENDPOINT);
fs.writeFileSync('output.png', images[0]);See the example/ directory for a working end-to-end example.
API
generateImages(workflow, comfyEndpoint, outputFormat?)
Generates one or more images and returns them as buffers.
Parameters
workflow- A ComfyUI workflow object exported with
File -> Export (API)
- A ComfyUI workflow object exported with
comfyEndpoint- Your ComfyUI server URL, for example
http://127.0.0.1:8188
- Your ComfyUI server URL, for example
outputFormat- Optional
'png' | 'webp'- Defaults to
'png'
Returns
Promise<Buffer[]>Notes
- Returns an array because a workflow may produce multiple images
- The workflow must produce at least one saved or previewed image output
- Output images are normalized to either
pngorwebp
generateImageToDataUri(workflow, comfyEndpoint, outputFormat?)
Generates images and returns them as data URIs.
Returns
Promise<string[]>Useful for directly assigning to image tags in web apps.
generateImageToBase64String(workflow, comfyEndpoint, outputFormat?)
Generates images and returns them as raw base64 strings.
Returns
Promise<string[]>Error handling
This library throws ComfyApiError with user-facing messages intended to explain what went wrong and how to fix it.
Connection failed
Example causes:
- ComfyUI is not running
- the endpoint URL is wrong
- the connection dropped during execution
Example message:
Could not connect to ComfyUI at "http://127.0.0.1:8188". Make sure ComfyUI is running and that the endpoint URL is correct.Malformed workflow
Example causes:
- the workflow object is invalid or empty
- the workflow was not exported in API format
- ComfyUI rejected the workflow because a model or node input is invalid
- required custom nodes or models are missing
When ComfyUI returns structured validation errors, the library formats them into a more readable message.
Example:
The provided workflow is malformed or incompatible with your ComfyUI setup, so ComfyUI rejected it. Make sure you exported the workflow using File -> Export (API), and that all required nodes and models are installed.
ComfyUI said:
Prompt outputs failed validation
- CheckpointLoaderSimple 4 for output 10: ckpt_name: 'bad-model-name.safetensors' not in [...]
ComfyUI error type: prompt_outputs_failed_validationUnsupported workflow output
Example causes:
- the workflow completed but did not save or preview any images
- ComfyUI reported image output metadata that could not be used
- the generated image could not be downloaded or converted
Example message:
The workflow ran in ComfyUI, but this script could not extract an image from it. No image outputs were reported during execution. This usually means the workflow does not save or preview any images. To use this script, the workflow must produce at least one saved or previewed image output.Migration notes from 1.x
Version 2.0 includes a few important behavior changes:
generateImage(...)has been replaced bygenerateImages(...)- return values are now arrays:
Promise<Buffer[]>Promise<string[]>
- execution tracking now uses WebSocket events instead of queue/history polling
- repeated identical workflow submissions now work correctly with ComfyUI caching
If you previously expected a single image, update your code from:
const image = await generateImage(workflow, endpoint);
fs.writeFileSync('output.png', image);to:
const images = await generateImages(workflow, endpoint);
fs.writeFileSync('output.png', images[0]);Development
Build the package:
bun run buildRun the example locally:
bun run example/example.tsThe build outputs the distributable files to dist/.
Publishing
The package is configured so that publishing includes:
dist/**/*README.mdLICENSE
A build runs automatically before publish via prepublishOnly.
License
MIT
