代码: comfyui 标题 : "@happyvertical/comfyui: ComfyUI API 客户端" 侧边栏 标签: "@happyvertical/comfyui" 侧边栏( p): 10
@ happyvertical/comfyui (英语)
一个基于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)
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
url | string | - 说吧 | ComfyUI 服务器 URL(例如, http://localhost:8188(中文(简体) ) |
clientId | string | 自动生成 | 唯一客户端标识符 |
timeout | number | 600000 | 请求超时( 毫秒) |
方法
| 方法 | 说明 |
|---|---|
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工作流程JSONnodeMapping- 将参数名称映射到节点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的一部分,根据麻省理工学院的许可证获得许可——见 自由主义 详细文件.