fabricatio-comfyui

Async ComfyUI API client for Fabricatio — submit workflow graphs, poll for completion, and download generated images. Built on httpx with full Pydantic-typed API coverage.

Architecture

The package is split into small, single-responsibility modules composed through nominal inheritance — no plugin dicts, no hasattr, no duck typing:

Pre-built workflow templates (Txt2Img, Txt2ImgWithDownload) are also available as a quick starting point.

Installation

pip install fabricatio[comfyui]
# or
uv pip install fabricatio[comfyui]

Configuration

Configure the ComfyUI server URL via environment, .env, fabricatio.toml, or pyproject.toml:

FABRICATIO_COMFYUI__BASE_URL=http://127.0.0.1:8188
FABRICATIO_COMFYUI__TIMEOUT=300

Or in fabricatio.toml:

[comfyui]
base_url = "http://127.0.0.1:8188"
timeout = 300

The config dataclass supports two fields:

Access config at runtime: from fabricatio_comfyui import comfyui_config

Usage

Standalone client

Use ComfyuiHTTPClient directly as an async context manager — no Fabricatio dependency beyond config:

import asyncio
from fabricatio_comfyui import ComfyuiHTTPClient


async def main() -> None:
    async with ComfyuiHTTPClient.create() as client:
        resp = await client.queue_prompt(workflow)
        result = await client.wait_for_completion(resp.prompt_id)
        if result.succeeded:
            await client.download_images(result, "./outputs")
        for img in result.all_images:
            image_bytes = await client.get_image(img.filename)


asyncio.run(main())

Capability mixin (with a Role)

Mix Comfyui into a Role to get acomfyui_* predicate-verb methods (following the same a-prefix convention as UseLLM.aask):

import asyncio
from fabricatio import Role
from fabricatio_comfyui import Comfyui


class ImageRole(Role, Comfyui):
    """Role with ComfyUI image generation capability."""


async def main() -> None:
    role = ImageRole(name="ComfyUI Worker")
    result = await role.acomfyui_generate(workflow, download_dir="./outputs")
    for img in result.all_images:
        print(img.filename)


asyncio.run(main())

Action (in a WorkFlow)

Use ComfyuiGenerateImage and ComfyuiUploadImage as composable steps:

from fabricatio import WorkFlow
from fabricatio_comfyui import ComfyuiGenerateImage, ComfyuiUploadImage

GenerateImage = WorkFlow(
    name="ComfyUI Generate",
    steps=(ComfyuiGenerateImage(workflow=WORKFLOW, download_dir="./outputs"),),
)

UploadThenGenerate = WorkFlow(
    name="Img2Img Pipeline",
    steps=(
        ComfyuiUploadImage(image_path="./input.png"),
        ComfyuiGenerateImage(workflow=IMG2IMG_WORKFLOW),
    ),
)

Upload an image (img2img)

result = await role.acomfyui_upload("./input_photo.png")
print(result.name)  # filename on the server

Built-in workflow templates

Two minimal templates are provided as quick starting points. In practice, you should export your own workflows via "Save (API Format)" from the ComfyUI interface.

from fabricatio_comfyui.workflows import Txt2Img, Txt2ImgWithDownload

API Reference

ComfyuiHTTPClient / Comfyui capability

The HTTP client owns single REST endpoints only. The capability mixin owns orchestration (queue → poll → download). All capability methods are prefixed with acomfyui_, following the a-prefix predicate-verb convention used by UseLLM.

Actions

Models

All API responses are deserialized into frozen Pydantic models. Key types:

Workflow types (PEP 695)

License

MIT — see the LICENSE file.