comfy-headless 3.0.1

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Drive ComfyUI from Python. No node graph.

What this is

comfy-headless builds ComfyUI API-format graphs and runs them. You call a Python function; it emits the JSON node graph, POSTs it to ComfyUI, polls for completion, and hands you the output paths.

That framing matters, because it tells you what can go wrong. The library's entire job is emitting node names and input keys that the target ComfyUI actually has. When ComfyUI renames or drops a node, a graph referencing the old name is rejected at submit with an opaque error — and nothing warns you first.

v3.0 is the release that took that seriously. Every node type this library emits was audited against the live ComfyUI catalog. Nine no longer existed. They're gone, the graphs that used them are rebuilt on verified nodes, and the library can now tell you what a server is missing before you spend a run on it.

Quick start

pip install comfy-headless[standard]

from comfy_headless import ComfyClient

client = ComfyClient()                       # defaults to http://localhost:8188
result = client.generate_image("a beautiful sunset over mountains")
print(result["images"])

generate_image returns a dict with success, prompt_id, images, error, seed and preset. Every generation call in this library returns a dict — there is no result object to unwrap.

Install

pip install comfy-headless              # core only, ~2MB
pip install comfy-headless[standard]    # + AI enhancement + WebSocket (recommended)
pip install comfy-headless[full]        # everything

Requires Python 3.10+ and a running ComfyUI instance.

Check what's active at runtime:

from comfy_headless import FEATURES, list_missing_features

print(FEATURES)                 # {'ai': True, 'websocket': True, 'health': False, ...}
print(list_missing_features())  # {'health': 'pip install comfy-headless[health]', ...}

Images

result = client.generate_image(
    "a cyberpunk street at night",
    negative_prompt="blurry, low quality",
    preset="hd",          # overrides width/height/steps/cfg when set
    seed=42,
)

Eight image presets: draft, fast, quality, hd, portrait, landscape, cinematic, square.

Batch a list of prompts:

result = client.generate_batch(
    ["a red fox", "a snowy owl", "a grey wolf"],
    preset="fast",
)

AI prompt enhancement

Requires the [ai] extra and a local Ollama. These are module-level functions, not client methods:

from comfy_headless import enhance_prompt, analyze_prompt

result = enhance_prompt("a cat", style="balanced")
print(result.enhanced)   # .original .enhanced .negative .additions .reasoning

analysis = analyze_prompt("a cyberpunk city at night")
print(analysis.intent, analysis.styles, analysis.suggested_preset)

Video

from comfy_headless import list_video_presets, get_recommended_preset

print(list_video_presets())                  # 24 presets
print(get_recommended_preset(vram_gb=16))    # picks one that fits

result = client.generate_video(
    "a slow pan across a mountain range",
    preset="ltx_quality",
)
print(result["videos"])

Selection is by preset, not by model — generate_video has no model argument. Any of frames, fps, steps, cfg, width, height can be passed to override the preset.

Image input

Image-to-video, and anything else taking a source image, needs that image to exist inside ComfyUI first. Upload it, then pass the name the server gives back:

ref = client.upload_image("reference.png")
# {"name": "reference.png", "subfolder": "", "type": "input", "ref": "reference.png"}

result = client.generate_video(
    "a cat walking through a garden",
    preset="wan_14b",
    init_image=ref["name"],
)

Read name back from the response rather than reusing the filename you sent — ComfyUI renames on collision, so the two are not always equal. ref is the same value already joined with any subfolder, which is exactly what the graph needs.

Changed in 3.0: init_image is a server-side filename. Earlier versions accepted base64 data and smuggled it through a third-party node that does not exist on a stock ComfyUI install. See the CHANGELOG.

Model families

Six of the nine families run on stock ComfyUI core nodes — no wrapper pack for the model itself. Only AnimateDiff (both variants) and CogVideoX need one. Video output uses Video Helper Suite; frame interpolation uses Frame Interpolation.

VRAM figures are the floor for that family's default resolution, read from VIDEO_MODEL_INFO — not ceilings. More memory buys longer clips and higher resolutions from the same family.

Check before you run

Rather than discovering a missing node at submit time:

workflow = client.build_video_workflow("a cat walking")

report = client.check_workflow_dependencies(workflow)
print(report["missing_packs"])     # what this server is missing
print(report["required_packs"])    # what this graph needs

# or raise MissingNodePackError, naming the class and the pack that provides it
client.require_workflow_dependencies(workflow)

Configuration

Environment variables use the COMFY_HEADLESS_ prefix with __ section delimiters:

Or pass the URL directly: ComfyClient("http://192.168.1.50:8188").

Web UI

comfy-headless                 # launching the UI is the default action

Six tabs: Image, Video, Queue & History, Workflows, Models, Settings. Theme is Ocean Mist — soft teal accents on warm neutral backgrounds.

Programmatically (requires [ui]):

from comfy_headless import launch
launch(port=7861, share=False)

Progress

Blocking calls take an on_progress callback:

client.generate_image("a fox", on_progress=lambda pct, msg: print(f"{pct:.0%} {msg}"))

For real-time updates over WebSocket (requires [websocket]):

import asyncio
from comfy_headless import ComfyWSClient

async def main():
    async with ComfyWSClient() as ws:
        prompt_id = await ws.queue_prompt(workflow)
        return await ws.wait_for_completion(prompt_id)

asyncio.run(main())

Errors

Every exception carries a structured code, message and hint:

from comfy_headless import (
    ComfyHeadlessError,       # base
    ComfyUIConnectionError,   # cannot reach ComfyUI
    ComfyUIOfflineError,      # ComfyUI not responding
    GenerationTimeoutError,
    GenerationFailedError,
    ValidationError,
    UploadError,              # new in 3.0
    MissingNodePackError,     # new in 3.0
)

try:
    client.generate_image("test")
except ComfyUIOfflineError:
    print("Start ComfyUI first")

How it works

your call ─→ build API-format graph ─→ POST /prompt ─→ poll /history ─→ GET /view
                     │
                     └─ validated against GET /object_info

The library talks to seven ComfyUI routes — /system_stats, /object_info, /queue, /history, /prompt, /interrupt, /view — plus /upload/image and /upload/mask for binary input.

/object_info is the authority on what a given server can run. It is a live endpoint, not a versioned artifact: there is no core-node registry to pin against. So the library validates emitted graphs against the target server's actual catalog rather than assuming a fixed node set. check_workflow_dependencies() is that check, and it is load-bearing infrastructure rather than a convenience.

Useful escape hatches when you want the graph itself:

workflow = client.build_txt2img_workflow("a fox")   # the raw API-format dict
prompt_id = client.queue_prompt(workflow)           # submit it yourself
client.wait_for_completion(prompt_id)

Docs

Full handbook: mcp-tool-shop-org.github.io/comfy-headless — getting started, usage, configuration, API reference, video models, architecture.

Security & data scope

• Data touched: connects to a local or remote ComfyUI instance over HTTP/WebSocket. Sends workflow JSON and uploaded images, receives generated media. Optionally connects to a local Ollama for prompt intelligence. Writes output to temp directories with automatic cleanup.
• Data NOT touched: no telemetry, no analytics, no external APIs beyond the ComfyUI and Ollama endpoints you configure. Secrets are masked in all log output via SecretValue.
• Permissions required: network access to your ComfyUI server and optional Ollama server; file write for output and temp directories.
• Uploads: upload_image rejects subfolder traversal attempts. Uploaded files land in ComfyUI's input directory on whichever server you point at — treat that server as trusted.

See SECURITY.md for vulnerability reporting.

Scorecard

Assessed with @mcptoolshop/shipcheck

Related

Part of MCP Tool Shop — open-source ML tooling for local hardware.

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md. Useful areas: additional model families, workflow templates, docs, bug fixes.

If you add a node type, verify it exists in the live ComfyUI catalog first, and declare its pack if it isn't core. That rule is why this release exists.

License

MIT — see LICENSE.

Built by MCP Tool Shop