comfyui-xy 0.2.0

A Python client library for interacting with ComfyUI API

ComfyUI API Client

English | 中文

A Python client library for interacting with ComfyUI API. This library provides a convenient wrapper to queue workflows, upload images/masks, and retrieve generated results (images, videos, audio, etc.) programmatically.

Features

• Workflow Management: Queue workflows easily and wait for results.
• File Management: Upload input images and masks directly to ComfyUI.
• Generic Output Handling: Automatically handles various output types (Images, Videos/GIFs, Audio).
• Execution Control: Interrupt running tasks, check queue status, and view history.
• Node Info: Retrieve definitions for ComfyUI nodes.

Installation

pip install comfyui_xy

How to Get Workflow JSON

To use this API, you need the workflow in API Format, which is different from the standard JSON saved by ComfyUI.

1. Enable Dev Mode Options:

   • In ComfyUI web interface, click the Settings (gear icon) in the menu.
   • Check the option "Enable Dev mode Options".

2. Save as API Format:

   • Once Dev Mode is enabled, you will see a new button in the menu: "Save (API Format)".
   • Click this button to save your workflow as a JSON file (e.g., workflow_api.json).
   • Use this JSON file with the ComfyUiClient.

Quick Start

import json
from comfyui_xy import ComfyUiClient

# 1. Initialize Client
client = ComfyUiClient(url="http://127.0.0.1:8188")

# 2. Load Workflow
# You should export the workflow in "API Format" from ComfyUI
with open("workflow_api.json", "r", encoding="utf-8") as f:
    workflow = json.load(f)

# 3. Modify Parameters (Optional)
# e.g., Change the seed in KSampler (Node ID "3")
import random
workflow["3"]["inputs"]["seed"] = random.randint(1, 1000000000)

# 4. Run Workflow
print("Queueing workflow...")
results = client.process_workflow(workflow)

# 5. Handle Results
for i, result in enumerate(results):
    print(f"Received file: {result.filename} ({result.file_type})")
    
    # Save to disk
    result.save(f"output_{i}_{result.filename}")
    
    # Show if it's an image
    if result.file_type == "image":
        result.show()

Detailed Usage

1. Initialization

from comfyui_xy import ComfyUiClient

# Default local server (http://127.0.0.1:8188)
client = ComfyUiClient() 

# Specify URL
client = ComfyUiClient(url="http://127.0.0.1:8188")

# Remote server with HTTPS
client = ComfyUiClient(url="https://my-comfyui-server.com:8188")

2. Uploading Files

You can upload images or masks before running a workflow. These files are saved in the input directory of ComfyUI.

# Upload an image
# Returns the filename used by ComfyUI (useful for setting node inputs)
image_name = client.upload_image("path/to/my_image.png")

# Upload a mask
mask_name = client.upload_mask("path/to/my_mask.png")

# Example: Set the uploaded image in a LoadImage node (e.g., Node ID "10")
workflow["10"]["inputs"]["image"] = image_name

3. Processing Workflows

The process_workflow method is a high-level helper that:

1. Queues the prompt.
2. Waits for execution to finish.
3. Downloads all generated files.

results = client.process_workflow(workflow)

Return Value: It returns a list of ComfyResponse objects.

4. Handling Responses (ComfyResponse)

The ComfyResponse object wraps the raw data returned by ComfyUI.

• Attributes:

  • data: Raw bytes of the file.
  • filename: Original filename on server.
  • file_type: Type of file (e.g., 'image', 'video', 'audio').
  • image: A PIL.Image object (if the file is a valid image).

• Methods:

  • save(path=None): Save file to disk. If path is None, uses filename.
  • show(): Opens the image in the default viewer (only for images).

5. Advanced Controls

Interrupt Execution:

client.interrupt()

Get System Status:

# Get Queue Status (Pending/Running tasks)
queue_info = client.get_queue()

# Get Full History
history = client.get_history_all()

# Get Node Information
node_info = client.get_object_info("KSampler")

Async Support

You can use AsyncComfyUiClient for asynchronous operations using aiohttp.

import asyncio
from comfyui_xy import AsyncComfyUiClient

async def main():
    async with AsyncComfyUiClient(url="http://127.0.0.1:8188") as client:
        # Most methods are awaitable
        results = await client.process_workflow(workflow)

if __name__ == "__main__":
    asyncio.run(main())

Examples

Check the examples/ directory for more complete scripts:

• basic_workflow.py: Simple Text-to-Image generation.
• image_to_image.py: Uploading an image and processing it.
• advanced_control.py: Inspecting queue and system info.

License

MIT