Comfy Headless Handbook
Welcome to the Comfy Headless Handbook. This guide covers everything you need to go from zero to generating images and videos programmatically through ComfyUI — without ever touching a node graph.
What is Comfy Headless?
Section titled “What is Comfy Headless?”Comfy Headless is a Python library that wraps ComfyUI’s full power behind a clean, developer-friendly API. Instead of wiring nodes together in a visual editor, you write a few lines of Python and let the library handle workflow compilation, model selection, and prompt optimization.
| Problem | How Comfy Headless Solves It |
|---|---|
| ComfyUI’s node interface is overwhelming | Simple presets and a clean Python API abstract the complexity away |
| Prompt engineering is hard | AI-powered prompt enhancement via Ollama rewrites prompts for better results |
| Video generation is complex | One-line video generation with curated model presets |
| No idea what settings to use | VRAM-aware recommendations pick the best settings automatically |
Who is this for?
Section titled “Who is this for?”- Users who want great results without prompt engineering expertise. Launch the Gradio UI and start generating immediately.
- Developers who need a clean Python API with proper error handling, WebSocket progress hooks, and circuit-breaker retry logic for production integration.
- Pipeline builders who want headless operation, modular installs, and configurable settings for automation workflows, CI image testing, or batch generation.
Handbook contents
Section titled “Handbook contents”| Page | What you will learn |
|---|---|
| Getting Started | Installation options, modular extras, and prerequisites |
| Usage | Library usage, AI enhancement, video generation, and the web UI |
| Video Models | Supported video models, presets, and VRAM requirements |
| Configuration | Feature flags, WebSocket progress, and runtime settings |
| API Reference | Core classes, error handling, and the full public API surface |
| Architecture | Project structure, module responsibilities, and ComfyUI node requirements |
| For Beginners | New to Comfy Headless? Start here |
Philosophy
Section titled “Philosophy”Comfy Headless follows three design principles:
- Output-first — the library exists to produce images and videos. Every abstraction serves that goal.
- Modular by design — the core is approximately 2 MB with zero heavy dependencies. Add extras only when you need them.
- Honest defaults — preset recommendations are VRAM-aware and transparent. The library never hides trade-offs.
Quick taste
Section titled “Quick taste”pip install comfy-headless[standard]from comfy_headless import ComfyClient
client = ComfyClient()result = client.generate_image("a beautiful sunset over mountains")print(f"Generated: {result['images']}")That is all it takes. Read on to learn about modular installation, AI prompt enhancement, video model presets, and more.