Drive ComfyUI from Python. No node graph.

Six workflow profiles

Image (SDXL + Qwen-Image txt2img, edit, ControlNet), video, 3D meshes (Hunyuan3D-2), audio (ACE-Step 1.5 music + stem separation), inference (caption, tag, detect, segment, OCR) and provenance — one client, one retrieval path.

Verified node graphs

Every node type this library emits is checked against the live ComfyUI catalog. Ask a server what it is missing before you spend a run — dependency errors name the node and the pack that provides it, not a bare validation failure.

26 video presets, 9 families

LTX-Video, Hunyuan 1.5 (t2v and true i2v), Wan, Mochi, SVD, AnimateDiff and CogVideoX, each with curated resolution, frame count and step settings. Six of the nine run on stock ComfyUI core nodes — no wrapper packs.

AI prompt intelligence

Analyse and enhance prompts with a local Ollama before generating. Detects intent, style and subject, then rewrites the prompt and builds a matching negative. Entirely optional and entirely local.

Modular by design

The core is around 2MB with no heavy dependencies. AI, WebSocket, the web UI, health checks, validation and tracing are opt-in extras that load lazily on first use.

Install

pip install comfy-headless[standard]

Generate an image

from comfy_headless import ComfyClient

client = ComfyClient()  # connects to localhost:8188
result = client.generate_image(
    "a photorealistic forest at golden hour",
    preset="hd",
)
print(result["images"])

Generate video

from comfy_headless import ComfyClient, get_recommended_preset

client = ComfyClient()
preset = get_recommended_preset(vram_gb=16)  # sized to your card
result = client.generate_video(
    "a slow pan across a mountain range",
    preset=preset,
)
print(result["videos"])

Generate a 3D mesh

# Hunyuan3D-2, all core nodes — no wrapper packs
result = client.generate_3d("character.png", preset="detail")
glb = client.get_file(**result["meshes"][0])
open("character.glb", "wb").write(glb)

Generate music

# ACE-Step 1.5 — MIT weights, all core nodes
result = client.generate_audio(
    tags="lo-fi, jazz, mellow, rainy night",
    preset="music", seconds=30,
)
flac = client.get_file(**result["audios"][0])

Ask about an image

r = client.run_inference("photo.png", task="caption")
print(r["text"])

r = client.run_inference(
    "photo.png", task="detect", text_input="the red car"
)
print(r["text"])  # bounding boxes as JSON

Re-run a PNG’s graph

from comfy_headless import extract_prompt_graph

graph = extract_prompt_graph("output.png")
result = client.rerun_from_png("output.png")

Check before you run

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

report = client.check_workflow_dependencies(workflow)
print(report["missing_packs"])  # empty means ready

# or raise MissingNodePackError
client.require_workflow_dependencies(workflow)

Launch the web UI

# Requires comfy-headless[ui]
comfy-headless
# -> http://localhost:7861

For users

Presets and optional AI prompt enhancement mean good results without prompt-engineering expertise. Launch the web UI and start generating immediately.

For developers

A clean Python API with escape hatches to the raw graph. Structured errors carrying a code, message and hint; circuit-breaker retry; WebSocket progress hooks.

For pipelines

Headless operation, modular installs and environment-driven configuration make it easy to embed in automation, CI image testing, or batch generation.