@happyvertical/comfyui

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5350

ComfyUI API 客户端,用于工作流程管弦和视频生成

中文使用文档
文档目录19 节
  1. 代码: comfyui 标题 : "@happyvertical/comfyui: ComfyUI API 客户端" …
  2. 概览
  3. 特征
  4. 安装
  5. 快速启动
  6. 基本用途
  7. 进展跟踪
  8. 文件上传
  9. 系统状态
  10. API 参考
  11. 舒适度
  12. 注入WorkflowParams 图像
  13. 类型
  14. 错误
  15. 使用大小写
  16. AI 视频生成管道
  17. 批量图像生成
  18. 所需资源
  19. 许可证

代码: comfyui 标题 : "@happyvertical/comfyui: ComfyUI API 客户端" 侧边栏 标签: "@happyvertical/comfyui" 侧边栏( p): 10

@ happyvertical/comfyui (英语)

License: MIT

一个基于WebSocket的客户端,用于"HE SDK"中的ComfyUI工作流程管弦和视频生成.

概览

这个 @happyvertical/comfyui 软件包为通过WebSocket与ComfyUI服务器交互提供了TypeScript客户端. 它支持工作流程执行,进度监测和输出下载AI动力图像和视频生成管道.

特征

  • WebSocket 连接: 与ComfyUI服务器的实时通信
  • 工作流程执行: 排队并执行ComfyUI工作流程
  • 进展监测: 跟踪详细事件的执行进展情况
  • 参数喷出: 动态向工作流程节点注入值
  • 输出下载: 获取生成的图像和视频
  • 队列管理: 监测和管理执行队列
  • 系统Stats: 查询服务器状态和能力
  • 文件上传: 为工作流程输入上传图像和其他文件

安装

# Install with bun (recommended)
bun add @happyvertical/comfyui

# Or with npm
npm install @happyvertical/comfyui

# Or with pnpm
pnpm add @happyvertical/comfyui

快速启动

基本用途

import { ComfyUIClient, injectWorkflowParams } from '@happyvertical/comfyui';

// Create client
const client = new ComfyUIClient({
  url: 'http://localhost:8188',
});

// Connect to server
await client.connect();

// Load and modify workflow
const workflow = JSON.parse(fs.readFileSync('workflow.json', 'utf-8'));
const modifiedWorkflow = injectWorkflowParams(
  workflow,
  {
    seedImage: '3',
    prompt: '6',
  },
  {
    seedImage: 'input/anchor.png',
    prompt: 'professional news anchor speaking',
  }
);

// Queue prompt and wait for completion
const result = await client.queuePrompt(modifiedWorkflow);
const history = await client.waitForCompletion(result.promptId);

// Download output
const output = history.outputs['SaveVideo'];
if (output?.videos?.[0]) {
  const video = await client.downloadOutput(output.videos[0].filename);
  fs.writeFileSync('output.mp4', video);
}

await client.disconnect();

进展跟踪

const history = await client.waitForCompletion(promptId, {
  onProgress: (event) => {
    switch (event.type) {
      case 'progress':
        console.log(`Progress: ${event.value}/${event.max}`);
        break;
      case 'executing':
        console.log(`Executing node: ${event.node}`);
        break;
      case 'execution_cached':
        console.log(`Cached nodes: ${event.nodes.join(', ')}`);
        break;
    }
  },
});

文件上传

// Upload image for workflow input
const imageBuffer = fs.readFileSync('input.png');
const uploadResult = await client.uploadImage(imageBuffer, 'input.png');

console.log(`Uploaded: ${uploadResult.name}`);

系统状态

// Get system stats
const stats = await client.getSystemStats();
console.log(`Queue: ${stats.queue.running}/${stats.queue.pending}`);

// Get queue status
const queue = await client.getQueueStatus();
console.log(`Running: ${queue.running.length}, Pending: ${queue.pending.length}`);

API 参考

舒适度

与ComfyUI服务器互动的主要客户类.

构造器

new ComfyUIClient(options: ComfyUIClientOptions)
选项类型默认说明
urlstring- 说吧ComfyUI 服务器 URL(例如, http://localhost:8188(中文(简体) )
clientIdstring自动生成唯一客户端标识符
timeoutnumber600000请求超时( 毫秒)

方法

方法说明
connect()建立 WebSocket 连接
disconnect()关闭 WebSocket 连接
queuePrompt(workflow)列出执行工作流程
waitForCompletion(promptId, options?)等待进度跟踪迅速完成
getHistory(promptId)获取行刑记录以提示
getQueueStatus()获取当前队列状态
getSystemStats()获取服务器系统统计
uploadImage(buffer, filename, options?)上传图像文件
downloadOutput(filename, subfolder?, type?)下载已生成的输出文件
interruptExecution()中断当前执行
clearQueue()清除所有待定的队列项目

注入WorkflowParams 图像

用于向工作流程节点注入动态值的功能.

function injectWorkflowParams(
  workflow: ComfyWorkflow,
  nodeMapping: NodeMapping,
  values: Record<string, unknown>
): ComfyWorkflow

参数

  • workflow - ComfyUI工作流程JSON
  • nodeMapping - 将参数名称映射到节点ID(例如, { seedImage: '3' }(中文(简体) )
  • values - 注入值(例如, { seedImage: 'path/to/image.png' }(中文(简体) )

类型

interface ComfyUIClientOptions {
  url: string;
  clientId?: string;
  timeout?: number;
}

interface PromptResult {
  promptId: string;
  number: number;
  nodeErrors?: Record<string, unknown>;
}

interface HistoryEntry {
  promptId: string;
  outputs: Record<string, NodeOutput>;
  status: { completed: boolean; messages?: unknown[] };
}

interface ProgressEvent {
  type: 'progress' | 'executing' | 'executed' | 'execution_cached' | 'execution_error';
  promptId?: string;
  node?: string;
  value?: number;
  max?: number;
  nodes?: string[];
}

错误

ComfyUI推出的非-2xx响应 ComfyUIRequestError (单位:千美元) ApiError 从 @happyvertical/utils) (中文(简体) ). 它携带 status, (中文(简体) ), method, (中文(简体) ), path 编辑 回应 body (分出JSON,或作生文. ComfyUI 拒绝一个提示 失败验证, 如缺少模型文件, 包含 HTTP 400; 那么错误 暴露尸体的痕迹 node_errors 作为 nodeErrors 联 合 国 error 对象为 promptError。消息保留 ComfyUI request failed: <status> <body> 语句.

import { ComfyUIRequestError } from '@happyvertical/comfyui';

try {
  await client.queuePrompt(workflow);
} catch (error) {
  if (error instanceof ComfyUIRequestError && error.nodeErrors) {
    console.error('Prompt rejected:', error.nodeErrors);
  }
  throw error;
}

使用大小写

AI 视频生成管道

import { ComfyUIClient, injectWorkflowParams } from '@happyvertical/comfyui';

async function generateVideo(seedImage: string, audioFile: string) {
  const client = new ComfyUIClient({ url: 'http://localhost:8188' });
  await client.connect();

  try {
    // Upload inputs
    await client.uploadImage(fs.readFileSync(seedImage), 'seed.png');
    await client.uploadImage(fs.readFileSync(audioFile), 'audio.wav');

    // Load lip-sync workflow
    const workflow = JSON.parse(fs.readFileSync('lipsync-workflow.json', 'utf-8'));
    const modified = injectWorkflowParams(workflow, {
      seedImage: '3',
      audioFile: '5',
    }, {
      seedImage: 'input/seed.png',
      audioFile: 'input/audio.wav',
    });

    // Execute with progress
    const result = await client.queuePrompt(modified);
    const history = await client.waitForCompletion(result.promptId, {
      onProgress: (e) => {
        if (e.type === 'progress') {
          console.log(`Rendering: ${Math.round((e.value! / e.max!) * 100)}%`);
        }
      },
    });

    // Download output
    const output = history.outputs['SaveVideo'];
    return await client.downloadOutput(output.videos[0].filename);
  } finally {
    await client.disconnect();
  }
}

批量图像生成

async function generateBatch(prompts: string[]) {
  const client = new ComfyUIClient({ url: 'http://localhost:8188' });
  await client.connect();

  const results = [];
  for (const prompt of prompts) {
    const workflow = injectWorkflowParams(baseWorkflow, { prompt: '6' }, { prompt });
    const result = await client.queuePrompt(workflow);
    const history = await client.waitForCompletion(result.promptId);
    results.push(history);
  }

  await client.disconnect();
  return results;
}

所需资源

  • 运行和可访问的 ComfyUI 服务器
  • 节点.js 20+或 Bun
  • 运行时的 WebSocket 支持

许可证

这个包是HE SDK的一部分,根据麻省理工学院的许可证获得许可——见 自由主义 详细文件.

版本与发布记录

@happyvertical/comfyui 共发布 132 个版本,首次发布于 2026/06/23;过去 12 个月发布了 132 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/comfyui 的常见问题

@happyvertical/comfyui 是什么?

ComfyUI API 客户端,用于工作流程管弦和视频生成

如何安装 @happyvertical/comfyui?

在项目目录运行 npm install @happyvertical/comfyui,或使用 pnpm add / yarn add / bun add。

@happyvertical/comfyui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/comfyui 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/comfyui 可以商用吗?

@happyvertical/comfyui 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/comfyui 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/comfyui 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,350 次,日均约 178 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/comfyui 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 132 个版本,其中过去 12 个月发布了 132 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。