ComfyUI power, minus the complexity.
Production-ready headless client for ComfyUI. AI-powered prompt enhancement, 5+ video models, modular installs, and a Gradio UI — all from a clean Python API.
Install
# Recommended for most users
pip install comfy-headless[standard]
# Core only (~2MB, no extras)
pip install comfy-headless
Generate
from comfy_headless import ComfyClient
client = ComfyClient()
result = client.generate_image("a beautiful sunset over mountains")
print(f"Generated: {result['images']}")
Video
from comfy_headless import ComfyClient, VideoModel
client = ComfyClient()
result = client.generate_video(
"a timelapse of clouds over mountains",
model=VideoModel.LTXV,
)
print(f"Video: {result['video']}")
Everything ComfyUI, none of the node graph
A clean API over the full ComfyUI feature set.
AI prompt intelligence
Analyze and enhance prompts with Ollama before generation. The intelligence layer detects style, intent, and subject — then rewrites for better results automatically.
5+ video model presets
LTX-Video 2, Hunyuan 1.5, Wan, AnimateDiff, and more — each with curated default settings. One line to generate video; VRAM-aware preset recommendations included.
Modular by design
Install only what you need. The core is ~2MB with zero heavy deps. Add [ai], [websocket], [ui], or [health] extras individually as your use case grows.
Installation extras
Mix and match — install only the capabilities you need.
Quick start
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",
)
print(result['images'])Generate video
from comfy_headless import ComfyClient, VideoModel, get_recommended_preset
client = ComfyClient()
preset = get_recommended_preset(vram_gb=16) # auto-select by VRAM
result = client.generate_video(
"a slow pan across a mountain range",
model=VideoModel.WAN,
settings=preset,
)
print(result['video'])Launch the Gradio UI
# Requires comfy-headless[ui]
python -m comfy_headless.ui
# → http://localhost:7860Built for every level
From quick experiments to production pipelines.
For users
Simple presets and AI-powered prompt enhancement mean great results without prompt engineering expertise. Launch the Gradio UI and start generating immediately.
For developers
Clean Python API with template-based workflow compilation. Full error taxonomy, circuit-breaker retry logic, and WebSocket progress hooks for production integration.
For pipelines
Headless operation, modular installs, and configurable settings make comfy-headless easy to embed in automation workflows, CI image testing, or batch generation jobs.