🔧 Installation

npm install comfyui-sdk

yarn add comfyui-sdk

pnpm add comfyui-sdk

🚀 Quick Start

1. Initialize the Client

import{ComfyUIClient,LogLevel}from'comfyui-sdk'constclient=newComfyUIClient({baseUrl:'http://localhost:8188',// ComfyUI server URLapiKey:'your-api-key-here',// Optional API keytimeout:90_000,// Request timeout (ms)logging:true,// Enable logginglogLevel:LogLevel.INFO// Adjust log verbosity})

2. Define & Execute a Workflow

// A minimal workflow: encode text and load a checkpointconstsimpleWorkflow={1:{inputs:{text:'A serene mountain landscape'},class_type:'CLIPTextEncode'},2:{inputs:{ckpt_name:'sd_base_1.0.safetensors'},class_type:'CheckpointLoaderSimple'}}asyncfunctionrunSimple(){try{constartifacts=awaitclient.run(simpleWorkflow)console.log('Artifacts:',artifacts)}catch(err){console.error('Workflow execution failed:',err)}}runSimple()

3. Upload a File

importfsfrom'node:fs'// Read a local image into a Bufferconstbuffer=fs.readFileSync('input.jpg')asyncfunctionuploadExample(){constresult=awaitclient.uploadFile(buffer,{filename:'input.jpg',// Custom name on serversubfolder:'images',// Place under `uploaded/images/`override:true// Overwrite if file exists})console.log('Uploaded as:',result.name)}uploadExample()

📚 API Reference

ComfyUIClient

Constructor:new ComfyUIClient(options: ClientOptions)

interfaceClientOptions{baseUrl:string// E.g., 'http://localhost:8188'apiKey?:string// Optional API keytimeout?:number// Request timeout in milliseconds (default: 90_000)poll?:{interval?:number// Polling interval in ms (default: 4_000)backoffBase?:number// Exponential backoff base in ms (default: 2_000)backoffCap?:number// Max backoff per retry in ms (default: 15_000)}logging?:boolean// Enable or disable logging (default: false)logLevel?:LogLevel// One of NONE, ERROR, WARN, INFO, DEBUG (default: INFO)}

Methods

run<TNode>(workflow: WorkflowPayload, options?: RunOptions<TNode>): Promise<Artifact[]>

uploadFile(file: Buffer | Blob, options?: UploadOptions): Promise<UploadOutput>

getHistory(promptId: string): Promise<Histories>

ComfyUIPool

Constructor:new ComfyUIPool(instances: InstanceConfig[], options?: PoolOptions)

Methods

lease(): Promise<ClientLease>

createSession(pipeline: ArtifactPipeline): ComfyUISession | null

withSession<T>(fn: (session: ComfyUISession) => Promise<T>, pipeline: ArtifactPipeline): Promise<T>

ArtifactPipeline & Processors

Creating a Pipeline

import{ArtifactPipeline,CosUploader,defineConfig}from'comfyui-sdk'// 1. Define custom or built-in processorsconstuploader=newCosUploader({secretId:'AKID...',secretKey:'SECRET...',bucket:'comfyui-bucket',region:'ap-guangzhou',prefix:'outputs/',signExpires:0,domain:'cdn.example.com'})// 2. Instantiate the pipeline with an ordered list of processorsconstpipeline=newArtifactPipeline([uploader,// ... you can add more custom processors here])

Built-in Processors

⚡ Enhanced Pipeline System

What’s New

📦 Type Definitions

// Artifact can be a binary (Buffer/Blob), text, or JSON resulttypeArtifact=|{kind:'binary',payload:ArrayBuffer|Uint8Array|Buffer|Blob,manifest:BinaryManifest,pipeline?:PipelineState}|{kind:'text',payload:string,manifest:TextManifest,pipeline?:PipelineState}|{kind:'json',payload:unknown,manifest:JsonManifest,pipeline?:PipelineState}interfaceBinaryManifest{filename:stringcontentType:stringsize:number// Additional fields: promptId, nodeId, etc.}interfaceTextManifest{filename:stringcontentType:stringsize:number// Additional metadata}interfaceJsonManifest{filename:stringcontentType:string// Additional metadata}interfacePipelineBus{}typePipelineState=Record<string,unknown>&Partial<PipelineBus>interfaceProcessorOutput<M=unknown>{output:Mnext?:Pick<Artifact,'kind'|'payload'|'manifest'>}abstractclassArtifactProcessor{abstractreadonlyname:stringasyncshouldRun(artifact:Artifact):Promise<boolean>abstractrun(artifact:Artifact):Promise<ProcessorOutput>}interfaceRunOptions<TNode>{node?:TNodeinputs?:Record<string,unknown>}interfaceClientOptions{/* ... as above ... */}interfaceUploadOptions{/* ... as above ... */}interfaceUploadOutput{/* ... as above ... */}interfaceComfyUISession{run:<TNode>(workflow:WorkflowPayload,options?:RunOptions<TNode>)=>Promise<Artifact[]>uploadFile:(data:Buffer|Blob,options?:UploadOptions)=>Promise<UploadOutput>getHistory:(promptId:string)=>Promise<Histories>close:()=>void}classArtifactPipeline{constructor(processors:ArtifactProcessor[])run(artifacts:Artifact[]|Record<string,Artifact>):Promise<Artifact[]|Record<string,Artifact>>}

🛠 Configuration Examples

Development Client

import{ComfyUIClient,LogLevel}from'comfyui-sdk'constdevClient=newComfyUIClient({baseUrl:'http://localhost:8188',logging:true,logLevel:LogLevel.DEBUG,timeout:60_000,poll:{interval:1_000}})

Production Pool

import{ComfyUIPool,LogLevel}from'comfyui-sdk'constprodPool=newComfyUIPool([{baseUrl:'https://comfyui-1.example.com',apiKey:process.env.COMFYUI_API_KEY,maxConcurrency:5,timeout:180_000},{baseUrl:'https://comfyui-2.example.com',apiKey:process.env.COMFYUI_API_KEY,maxConcurrency:3,timeout:180_000}],{logging:true,logLevel:LogLevel.INFO})

📖 Complete Examples

1. End-to-End Text-to-Image Workflow with Pipeline

import{ArtifactPipeline,ComfyUIClient,ComfyUIPool,CosUploader,defineConfig,LogLevel}from'comfyui-sdk'// 1. Configure pool of ComfyUI serversconstpool=newComfyUIPool([{baseUrl:'http://localhost:8188',maxConcurrency:2}],{logging:true,logLevel:LogLevel.INFO})// 2. Build an artifact pipeline: convert to WebP → upload to COS → collect metadataclassWebPConverterextendsArtifactProcessor{readonlyname='webpConverter'asyncrun(artifact:Artifact){if(artifact.kind!=='binary')return{output:{}}constconverted=artifact.payloadasBuffer// pretend conversionreturn{output:{original:artifact.manifest.contentType,converted:'image/webp'},next:{kind:'binary',payload:converted,manifest:{          ...artifact.manifest,contentType:'image/webp',filename:artifact.manifest.filename.replace(/\.\w+$/,'.webp')}}}}}// Tencent COS uploaderconstcosUploader=newCosUploader({secretId:process.env.COS_SECRET_ID!,secretKey:process.env.COS_SECRET_KEY!,bucket:'comfyui-bucket',region:'ap-guangzhou',prefix:'outputs/',signExpires:0,domain:'cdn.example.com'})// Metadata collectorclassMetadataCollectorextendsArtifactProcessor{readonlyname='metadataCollector'asyncrun(artifact:Artifact){constuploadInfo=artifact.pipeline?.cosUploaderconstwebpInfo=artifact.pipeline?.webpConverterconstmetadata={timestamp:newDate().toISOString(),filename:artifact.manifest.filename,size:artifact.kind==='binary' ?(artifact.payloadasBuffer).byteLength :0,uploadUrl:uploadInfo?.url||null,conversion:webpInfo||null}return{output:metadata,next:{kind:'json',payload:metadata,manifest:{from:artifact.manifest.from,promptId:artifact.manifest.promptId,filename:`metadata_${artifact.manifest.filename}.json`,contentType:'application/json'}}}}}// Assemble the pipelineconstpipeline=newArtifactPipeline([newWebPConverter(),cosUploader,newMetadataCollector()])// 3. Define a type-safe text-to-image pipelineconsttextToImageConfig=defineConfig({inputs:[{from:'prompt',to:'6.inputs.text',required:true},{from:'negative_prompt',to:'7.inputs.text',defaultValue:''},{from:'width',to:'5.inputs.width',defaultValue:1024},{from:'height',to:'5.inputs.height',defaultValue:1024},{from:'steps',to:'3.inputs.steps',defaultValue:20},{from:'cfg',to:'3.inputs.cfg',defaultValue:7},{from:'seed',to:'3.inputs.seed',defaultValue:42}]asconst,outputs:[{from:'9',to:'image'},{from:'12',to:'metadata'}]asconst}asconst)// 4. The SDXL text-to-image workflowconstsdxlWorkflow={4:{class_type:'CheckpointLoaderSimple',inputs:{ckpt_name:'sd_xl_base_1.0.safetensors'}},5:{class_type:'EmptyLatentImage',inputs:{width:1024,height:1024,batch_size:1}},6:{class_type:'CLIPTextEncode',inputs:{text:'sunset over ocean',clip:['4',1]}},7:{class_type:'CLIPTextEncode',inputs:{text:'',clip:['4',1]}},3:{class_type:'KSampler',inputs:{seed:42,steps:20,cfg:7,sampler_name:'euler',scheduler:'normal',denoise:1,model:['4',0],positive:['6',0],negative:['7',0],latent_image:['5',0]}},8:{class_type:'VAEDecode',inputs:{samples:['3',0],vae:['4',2]}},9:{class_type:'SaveImage',inputs:{filename_prefix:'ComfyUI',images:['8',0]}},12:{class_type:'SaveJSON',inputs:{data:['8',0],filename:'metadata.json'}}}// 5. Execute within a session so artifacts flow through the pipelineasyncfunctiongenerateImage(){constsession=pool.createSession(pipeline)if(!session)thrownewError('No available clients')try{const{ image, metadata}=awaitsession.run(sdxlWorkflow,{node:textToImageConfig,inputs:{prompt:'A majestic dragon soaring above clouds',width:1920,height:1080,steps:30}})console.log('Final Image Artifact:',image)console.log('Metadata JSON:',metadata)}catch(err){console.error('Generation error:',err)}finally{session.close()}}generateImage()

🔍 Custom Artifact Processors

import{ArtifactProcessor,ProcessorOutput}from'comfyui-sdk'interfaceCustomProcessorOutput{processed:booleanoriginalSize:numberprocessedSize:numbertimestamp:numberdurationMs:number}classCustomImageProcessorextendsArtifactProcessor{readonlyname='customImageProcessor'asyncshouldRun(artifact:Artifact):Promise<boolean>{returnartifact.kind==='binary'}asyncrun(artifact:Artifact):Promise<ProcessorOutput<CustomProcessorOutput>>{conststartTime=Date.now()constbuffer=artifact.payloadasBuffer// Placeholder for real image processingconstprocessedBuffer=awaitthis.processImage(buffer)return{output:{processed:true,originalSize:buffer.byteLength,processedSize:processedBuffer.byteLength,timestamp:Date.now(),durationMs:Date.now()-startTime},next:{kind:'binary',payload:processedBuffer,manifest:{          ...artifact.manifest,filename:`processed_${artifact.manifest.filename}`,contentType:'image/png'}}}}privateasyncprocessImage(buffer:Buffer):Promise<Buffer>{// Insert actual processing here (e.g., resizing, filtering)returnbuffer}}// To enable full type safety on pipeline state:declare module'comfyui-sdk/types'{interfacePipelineBus{customImageProcessor:CustomProcessorOutput}}// Usageconstpipeline=newArtifactPipeline([newCustomImageProcessor(),newCosUploader({/* ...config */})])

🤝 Contributing

📄 License

🔗 Useful Links