Overview#
This documentation covers the Lilith platform's integration with ComfyUI through RunComfy's serverless API. It includes guides for the API client, workflow development, custom nodes, and operational best practices.
Technical Documentation#
API & Client#
- RunComfy API Client - Core HTTP client for RunComfy API with retries, rate limiting, and job polling
- Workflow Builder - Fluent API for building workflow overrides with prompt templates and seed management
- Deployment Registry - Deployment configuration management, versioning, and health monitoring
Development#
- Custom Node Development - Creating custom ComfyUI nodes for Lilith platform
- Workflow Development Guide - Best practices for designing and testing workflows
Operations#
- Troubleshooting Guide - Common errors, debugging techniques, and solutions
- Performance Optimization - GPU selection, caching, batch processing, and cost optimization
API Reference#
- API Endpoints - Complete API endpoint documentation with examples
- Postman Collection - Ready-to-use Postman collection for API testing
Quick Start#
1. Install Dependencies#
bash
npm install @lilith/lib
2. Configure Client#
typescript
import { createRunComfyClientFromEnv } from '@lilith/lib/comfyui';
// Set environment variables
// RUNCOMFY_API_KEY=your-api-key
const client = createRunComfyClientFromEnv();
3. Run Inference#
typescript
import { createWorkflowBuilder, COMMON_NODE_IDS } from '@lilith/lib/comfyui';
// Build workflow overrides
const builder = createWorkflowBuilder();
builder
.setPrompt(
COMMON_NODE_IDS.POSITIVE_PROMPT,
'sacred mandala, golden, intricate'
)
.setNegativePrompt(COMMON_NODE_IDS.NEGATIVE_PROMPT, 'blurry, low quality')
.setSamplerParams(COMMON_NODE_IDS.KSAMPLER, { seed: 42, steps: 30, cfg: 7.5 })
.setResolution(COMMON_NODE_IDS.EMPTY_LATENT_IMAGE, 'square-1024');
// Run inference
const result = await client.runInference('sacred-mandala-v1', builder.build());
// Access outputs
console.log(`Generated ${result.outputs.length} images`);
result.outputs.forEach((output) => {
console.log(`Download: ${output.url}`);
});
Architecture Overview#
text
┌─────────────────────────────────────────────────────────────────┐
│ Lilith Platform │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ BFF Service │───▶│ AI Service │───▶│ ComfyUI Service │ │
│ └─────────────┘ └──────────────┘ └────────┬────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ @lilith/lib/comfyui │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ RunComfyClient │ WorkflowBuilder │ DeploymentRegistry │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
└──────────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────┐
│ RunComfy API │
│ (Serverless) │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ GPU Workers │
│ (A4000-H100) │
└─────────────────────┘
Custom Node Packages#
| Package | Description | Nodes |
|---|---|---|
sacred_geometry |
Sacred geometry pattern generation | 7 |
consciousness |
Consciousness/meditation visualization | 5 |
spiritual_styles |
Spiritual art style transfer | 6 |
lilith |
Platform integration (CDN, metadata) | 5 |
Total: 23 custom nodes
See Custom Node Development for details.
Pre-configured Deployments#
| Category | Deployments | GPU Range |
|---|---|---|
| Sacred Art | Mandala, Yantra | A4000-A5000 |
| Fractal | Mandelbrot, Julia | A5000-A6000 |
| Avatar | Generation, Cosmetic | A4000-A5000 |
| Video | Meditation, Lecture | A100 |
| Utility | Upscale, Style Transfer | A4000-A5000 |
See Deployment Registry for complete list.
Environment Variables#
| Variable | Description | Required |
|---|---|---|
RUNCOMFY_API_KEY |
RunComfy API authentication key | Yes |
RUNCOMFY_BASE_URL |
API base URL | No |
RUNCOMFY_TIMEOUT_MS |
Request timeout (ms) | No |
RUNCOMFY_DEBUG |
Enable debug logging | No |
LILITH_CDN_URL |
Lilith CDN base URL | No |
LILITH_STORAGE_URL |
Lilith storage service URL | No |
Support#
- Documentation Issues: Open issue in documentation repo
- API Issues: Contact RunComfy support with job ID
- Platform Issues: Internal Lilith engineering team