【ComfyUI API 自动化利器：comfyui_xy Python 库使用详解】

项目地址 ：https://github.com/xy200303/ComfyUiApi

PyPI地址 ：https://pypi.org/project/comfyui-xy/

在 AIGC 领域，ComfyUI 凭借其强大的节点式工作流赢得了众多开发者的青睐。然而，当我们需要将 ComfyUI 集成到自己的应用中，或者进行批量化、自动化任务时，直接使用官方 API 可能会显得有些繁琐。

为了解决这个问题，我开发了一个轻量级的 Python 客户端库 ------ comfyui_xy。它封装了 ComfyUI 的核心 API，让你能够像调用普通 Python 函数一样，轻松实现上传图片、修改工作流、排队任务以及获取生成结果。

本文将详细介绍 comfyui_xy 的安装与使用方法，带你快速上手 ComfyUI 自动化。

1. 安装

首先，通过 pip 安装该库：

bash 复制代码

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 最简示例：文生图

下面是一个简单的示例，展示如何加载工作流并生成图片。

python 复制代码

import json
import random
from comfyui_xy 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：

python 复制代码

# 连接远程 HTTPS 服务器
client = ComfyUiClient(url="https://u12345.autodl.com:12345")

# 或者普通的 HTTP 服务器
# client = ComfyUiClient(url="http://192.168.1.100:8188")

3.2 图生图：上传图片与遮罩

在图生图（Img2Img）或重绘（Inpainting）任务中，我们需要先上传图片。

python 复制代码

# 上传图片
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 对象处理这些结果。

python 复制代码

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 高级控制

库中还封装了一些常用的系统级操作：

中断任务 ：
python 复制代码
```
client.interrupt()
```

查看队列 ：

python 复制代码

queue_info = client.get_queue()
print(f"排队中: {queue_info['queue_pending']}, 运行中: {queue_info['queue_running']}")

获取历史记录 ：
python 复制代码
```
history = client.get_history_all()
```

查询节点信息 ：

python 复制代码

# 获取 KSampler 的输入输出定义
info = client.get_object_info("KSampler")

4. 总结

comfyui_xy 旨在简化 Python 与 ComfyUI 的交互过程，让你无需处理复杂的 WebSocket 连接和 HTTP 请求细节。无论是构建自己的 AI 应用后端，还是编写自动化测试脚本，它都能助你一臂之力。

项目开源地址 ：https://github.com/xy200303/ComfyUiApi

如果你觉得好用，欢迎给个 Star！如果有任何问题，也欢迎在 Issues 中反馈。