fabricatio-comfyui

Async ComfyUI API client for Fabricatio — generate images from typed parameters and download results. Built on httpx with full Pydantic-typed API coverage.

Design: bundled workflows only

The package owns its workflow JSON files (workflows/*.json). Callers never pass raw workflow graphs — they supply high-level knobs (prompt, negative_prompt, width, height, seed, steps, cfg) and the package selects and parameterises a bundled template (Workflow.from_template(name) / Workflow.default()). This keeps the public surface fully statically typed: no dict[str, Any] workflow injection anywhere in capability or action signatures.

Architecture

Installation

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

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.comfyui] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.comfyui] in pyproject.toml, or via FABRICATIO_EXT__COMFYUI__<FIELD_UPPER> environment variables.

[ext.comfyui]
base_url = "http://127.0.0.1:8188"
timeout = 300.0

Access at runtime: from fabricatio_comfyui.config import comfyui_config.

Usage

Capability mixin (with a Role)

Mix Comfyui into a Role to get the 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(
        "masterpiece, best quality, a mountain landscape",
        negative_prompt="worst quality, blurry",
        width=1024,
        height=768,
        download_dir="./outputs",
    )
    for img in result.all_images:
        print(img.filename)


asyncio.run(main())

Standalone client

The HTTP client is a lower-level transport; it accepts Workflow instances built from the bundled templates:

import asyncio
from fabricatio_comfyui import ComfyuiHTTPClient, Workflow


async def main() -> None:
    wf = Workflow.default()
    wf.set_positive_prompt("a mountain landscape")

    async with ComfyuiHTTPClient.create() as client:
        resp = await client.queue_prompt(wf)
        result = await client.wait_for_completion(resp.prompt_id)
        if result.succeeded:
            await client.download_images(result, "./outputs")


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(
            prompt="masterpiece, best quality",
            download_dir="./outputs",
        ),
    ),
)

Built-in workflow templates

Pre-built WorkFlow templates are available as quick starting points:

from fabricatio_comfyui.workflows import Txt2Img, Txt2ImgWithDownload

Both run the bundled default.json graph; wire your own prompt through the step's fields when composing custom pipelines.

API Reference

Capability methods

acomfyui_generate keyword parameters: negative_prompt, width, height, seed, steps, cfg, template (bundled template name), download_dir, timeout.

Client methods (ComfyuiHTTPClient / ComfyuiClientBase)

Actions

Models

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

Workflow types (PEP 695)

License

MIT — see the LICENSE file.