在 AIGC 领域，ComfyUI 凭借其强大的节点式工作流赢得了众多开发者的青睐。然而，当我们需要将 ComfyUI 集成到自己的应用中，或者进行批量化、自动化任务时，直接使用官方 API 可能会显得有些繁琐。
为了解决这个问题，我开发了一个轻量级的 Python 客户端库 —— comfyui_xy。它封装了 ComfyUI 的核心 API，让你能够像调用普通 Python 函数一样，轻松实现上传图片、修改工作流、排队任务以及获取生成结果。
本文将详细介绍 comfyui_xy 的安装与使用方法，带你快速上手 ComfyUI 自动化。
1. 安装
首先，通过 pip 安装该库：
pip install comfyui_xy
2. 快速入门
2.1 准备工作：获取 API 格式工作流
在使用 API 之前，你需要获取 ComfyUI 的工作流 JSON。注意：这与平时保存的 JSON 不同。
- 打开 ComfyUI 网页界面。
- 点击菜单中的 Settings（齿轮图标）。
- 勾选 "Enable Dev mode Options"。
- 回到菜单，点击 "Save (API Format)" 按钮，保存为
workflow_api.json。
2.2 最简示例：文生图
下面是一个简单的示例，展示如何加载工作流并生成图片。
import json
import random
from comfyui_api import ComfyUiClient
# 1. 初始化客户端 (默认连接本地 http://127.0.0.1:8188)
client = ComfyUiClient()
# 2. 加载你导出的 API 格式工作流
with open("workflow_api.json", "r", encoding="utf-8") as f:
workflow = json.load(f)
# 3. 动态修改参数
# 假设 KSampler 是节点 "3"，我们要修改它的 seed
workflow["3"]["inputs"]["seed"] = random.randint(1, 1000000000)
# 4. 执行工作流
# process_workflow 会自动排队、等待执行完成、并下载结果
print("正在执行任务...")
results = client.process_workflow(workflow)
# 5. 保存结果
for i, result in enumerate(results):
print(f"生成文件: {result.filename} ({result.file_type})")
result.save(f"output_{i}.png") # 保存到本地
if result.file_type == "image":
result.show() # 如果是图片，直接弹出预览
3. 核心功能详解
3.1 连接远程服务器
如果你的 ComfyUI 部署在远程服务器（例如 AutoDL 或云服务器），支持 HTTPS：
# 连接远程 HTTPS 服务器
client = ComfyUiClient(url="https://u12345.autodl.com:12345")
# 或者普通的 HTTP 服务器
# client = ComfyUiClient(url="http://192.168.1.100:8188")
3.2 图生图：上传图片与遮罩
在图生图（Img2Img）或重绘（Inpainting）任务中，我们需要先上传图片。
# 上传图片
image_name = client.upload_image("test.jpg")
print(f"图片已上传，服务器文件名为: {image_name}")
# 上传遮罩
mask_name = client.upload_mask("mask.png")
# 将上传后的文件名填入工作流节点
# 假设 LoadImage 节点 ID 为 "10"
workflow["10"]["inputs"]["image"] = image_name
3.3 处理多种输出类型
ComfyUI 不仅生成图片，还可能生成视频（AnimateDiff）、音频等。comfyui_xy 统一使用 ComfyResponse 对象处理这些结果。
results = client.process_workflow(workflow)
for result in results:
# result.data: 原始二进制数据
# result.file_type: 'image', 'video', 'audio' 等
if result.file_type == "video":
result.save("output_video.mp4")
elif result.file_type == "image":
result.save("output_image.png")
3.4 高级控制
库中还封装了一些常用的系统级操作：
- 中断任务：
client.interrupt() - 查看队列：
queue_info = client.get_queue() print(f"排队中: {queue_info['queue_pending']}, 运行中: {queue_info['queue_running']}") - 获取历史记录：
history = client.get_history_all() - 查询节点信息：
# 获取 KSampler 的输入输出定义 info = client.get_object_info("KSampler")
4. 总结
comfyui_xy 旨在简化 Python 与 ComfyUI 的交互过程，让你无需处理复杂的 WebSocket 连接和 HTTP 请求细节。无论是构建自己的 AI 应用后端，还是编写自动化测试脚本，它都能助你一臂之力。
项目开源地址：https://github.com/xy200303/ComfyUiApi
如果你觉得好用，欢迎给个 Star！如果有任何问题，也欢迎在 Issues 中反馈。
