Overview#
The RunComfy API Client (services/lib/comfyui/RunComfyClient.ts) provides a
complete TypeScript interface for interacting with the RunComfy serverless
ComfyUI API. It includes automatic retries, rate limiting, job polling, and
comprehensive error handling.
Installation#
The client is part of the @lilith/lib package:
typescript
import {
RunComfyClient,
createRunComfyClient,
createRunComfyClientFromEnv,
} from '@lilith/lib/comfyui';
Configuration#
Client Configuration Options#
typescript
interface RunComfyClientConfig {
/** RunComfy API key (required) */
apiKey: string;
/** Base URL for the API (default: https://api.runcomfy.com/v1) */
baseUrl?: string;
/** Request timeout in milliseconds (default: 120000, max: 600000) */
timeoutMs?: number;
/** Retry configuration */
retry?: Partial<RetryConfig>;
/** Rate limiting configuration */
rateLimit?: Partial<RateLimitConfig>;
/** Custom headers to include in all requests */
headers?: Record<string, string>;
/** Enable debug logging */
debug?: boolean;
}
Retry Configuration#
typescript
interface RetryConfig {
maxRetries: number; // Default: 3
baseDelayMs: number; // Default: 1000
maxDelayMs: number; // Default: 30000
backoffMultiplier: number; // Default: 2
jitterFactor: number; // Default: 0.1
retryableCodes: RunComfyErrorCode[];
}
Rate Limit Configuration#
typescript
interface RateLimitConfig {
requestsPerMinute: number; // Default: 100
maxConcurrent: number; // Default: 10
queueExcess: boolean; // Default: true
}
Creating a Client#
Method 1: Direct Configuration#
typescript
const client = createRunComfyClient({
apiKey: 'your-api-key',
baseUrl: 'https://api.runcomfy.com/v1',
timeoutMs: 120000,
debug: true,
retry: {
maxRetries: 3,
baseDelayMs: 1000,
},
rateLimit: {
requestsPerMinute: 100,
maxConcurrent: 10,
},
});
Method 2: From Environment Variables#
typescript
// Reads from:
// - RUNCOMFY_API_KEY (required)
// - RUNCOMFY_BASE_URL (optional)
// - RUNCOMFY_TIMEOUT_MS (optional)
// - RUNCOMFY_DEBUG (optional)
const client = createRunComfyClientFromEnv();
Core Operations#
Queue an Inference Job#
typescript
const response = await client.queueInference(
'deployment-id',
{
// Workflow overrides (node ID -> input values)
'6': { inputs: { text: 'A sacred mandala' } },
'3': { inputs: { seed: 12345, steps: 30 } },
},
{
webhookUrl: 'https://your-webhook.com/callback',
priority: JobPriority.NORMAL,
metadata: { userId: 'user-123' },
timeoutSeconds: 300,
}
);
console.log(`Job queued: ${response.jobId}`);
console.log(`Queue position: ${response.queuePosition}`);
Poll Job Until Completion#
typescript
const result = await client.pollJob(jobId, {
pollingConfig: {
initialIntervalMs: 1000,
maxIntervalMs: 10000,
intervalMultiplier: 1.5,
maxDurationMs: 600000,
},
onProgress: (event) => {
console.log(`Progress: ${event.data.progress}%`);
if (event.data.currentNode) {
console.log(`Processing node: ${event.data.currentNode.class}`);
}
},
});
// Access outputs
for (const output of result.outputs) {
console.log(`Output: ${output.filename} (${output.type})`);
console.log(`URL: ${output.url}`);
}
Run Inference (Queue + Poll)#
typescript
// Combined operation: queues job and waits for completion
const result = await client.runInference('deployment-id', overrides, {
priority: JobPriority.HIGH,
timeoutSeconds: 300,
onProgress: (event) => console.log(`Progress: ${event.data.progress}%`),
});
Check Job Status#
typescript
const status = await client.getJobStatus(jobId);
console.log(`Status: ${status.status}`);
console.log(`Progress: ${status.progress}%`);
Get Job Result#
typescript
const result = await client.getJobResult(jobId);
if (result.status === JobStatus.COMPLETED) {
result.outputs.forEach((output) => {
console.log(`${output.filename}: ${output.url}`);
});
}
Cancel a Job#
typescript
const { success, message } = await client.cancelJob(jobId);
console.log(success ? 'Job cancelled' : `Failed: ${message}`);
Deployment Management#
List Deployments#
typescript
const deployments = await client.listDeployments();
deployments.forEach((d) => {
console.log(
`${d.name} (${d.deploymentId}): ${d.active ? 'Active' : 'Inactive'}`
);
});
Get Deployment Details#
typescript
const deployment = await client.getDeployment('deployment-id');
console.log(`GPU Type: ${deployment.gpuType}`);
console.log(`Max Concurrent: ${deployment.maxConcurrent}`);
Get Deployment Status#
typescript
const status = await client.getDeploymentStatus('deployment-id');
console.log(`Health: ${status.healthy ? 'Healthy' : 'Unhealthy'}`);
console.log(`Current Jobs: ${status.currentJobs}`);
console.log(`GPU Utilization: ${status.gpuUtilization}%`);
Error Handling#
Error Types#
typescript
// Base error class
class RunComfyError extends Error {
code: RunComfyErrorCode;
statusCode: number;
requestId?: string;
details?: Record<string, unknown>;
retryAfter?: number;
isRetryable(): boolean;
}
// Specific error types
class AuthenticationError extends RunComfyError {}
class RateLimitError extends RunComfyError {}
class TimeoutError extends RunComfyError {}
Error Codes#
typescript
enum RunComfyErrorCode {
// Authentication
UNAUTHORIZED = 'UNAUTHORIZED',
FORBIDDEN = 'FORBIDDEN',
INVALID_API_KEY = 'INVALID_API_KEY',
// Request errors
BAD_REQUEST = 'BAD_REQUEST',
INVALID_DEPLOYMENT = 'INVALID_DEPLOYMENT',
INVALID_WORKFLOW = 'INVALID_WORKFLOW',
INVALID_OVERRIDES = 'INVALID_OVERRIDES',
// Resource errors
NOT_FOUND = 'NOT_FOUND',
JOB_NOT_FOUND = 'JOB_NOT_FOUND',
DEPLOYMENT_NOT_FOUND = 'DEPLOYMENT_NOT_FOUND',
// Processing errors
WORKFLOW_ERROR = 'WORKFLOW_ERROR',
NODE_ERROR = 'NODE_ERROR',
TIMEOUT = 'TIMEOUT',
OUT_OF_MEMORY = 'OUT_OF_MEMORY',
GPU_ERROR = 'GPU_ERROR',
// Rate limiting
RATE_LIMITED = 'RATE_LIMITED',
QUOTA_EXCEEDED = 'QUOTA_EXCEEDED',
// Server errors
INTERNAL_ERROR = 'INTERNAL_ERROR',
SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
MAINTENANCE = 'MAINTENANCE',
}
Handling Errors#
typescript
try {
const result = await client.runInference('deployment-id', overrides);
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof RateLimitError) {
console.error(`Rate limited. Retry after ${error.retryAfter}s`);
} else if (error instanceof TimeoutError) {
console.error('Job timed out');
} else if (error instanceof RunComfyError) {
console.error(`Error: ${error.code} - ${error.message}`);
if (error.isRetryable()) {
// Implement retry logic
}
}
}
Monitoring & Metrics#
Get Client Metrics#
typescript
const metrics = client.getMetrics();
console.log(`Total Requests: ${metrics.totalRequests}`);
console.log(
`Success Rate: ${(metrics.successfulRequests / metrics.totalRequests) * 100}%`
);
console.log(`Jobs Completed: ${metrics.jobsCompleted}`);
console.log(`Avg Processing Time: ${metrics.avgProcessingTimeMs}ms`);
console.log(`Rate Limit Hits: ${metrics.rateLimitHits}`);
Reset Metrics#
typescript
client.resetMetrics();
Rate Limiter Stats#
typescript
const stats = client.getRateLimiterStats();
console.log(`Available Tokens: ${stats.tokens}`);
console.log(`Active Requests: ${stats.activeRequests}`);
console.log(`Queued Requests: ${stats.queueLength}`);
Health Check#
typescript
const health = await client.healthCheck();
console.log(`API Healthy: ${health.healthy}`);
console.log(`Latency: ${health.latencyMs}ms`);
Job Event Types#
typescript
type JobEventType =
| 'queued' // Job added to queue
| 'started' // Processing began
| 'progress' // Progress update
| 'completed' // Successfully completed
| 'failed' // Job failed
| 'cancelled'; // Job was cancelled
interface JobEvent {
type: JobEventType;
jobId: string;
timestamp: string;
data: JobResult | JobStatusResponse;
}
Best Practices#
1. Reuse Client Instances#
typescript
// Create once at application startup
const client = createRunComfyClientFromEnv();
// Reuse across requests
export { client };
2. Handle Timeouts Appropriately#
typescript
// Set appropriate timeout based on workflow complexity
const result = await client.runInference('complex-workflow', overrides, {
timeoutSeconds: 600, // 10 minutes for complex workflows
pollingConfig: {
maxDurationMs: 660000, // Slightly longer than job timeout
},
});
3. Use Webhooks for Long-Running Jobs#
typescript
// Queue job with webhook instead of polling
const response = await client.queueInference('deployment-id', overrides, {
webhookUrl: 'https://api.lilith.ai/webhooks/comfyui',
});
// Handle webhook in your endpoint
app.post('/webhooks/comfyui', async (req) => {
const { jobId, status, outputs, error } = req.body;
// Process completion
});
4. Implement Graceful Degradation#
typescript
async function generateWithFallback(prompt: string) {
try {
return await client.runInference('premium-deployment', {
/* ... */
});
} catch (error) {
if (
error instanceof RunComfyError &&
error.code === 'SERVICE_UNAVAILABLE'
) {
// Fall back to simpler deployment
return await client.runInference('basic-deployment', {
/* ... */
});
}
throw error;
}
}
5. Monitor Rate Limits#
typescript
const stats = client.getRateLimiterStats();
if (stats.queueLength > 50) {
console.warn('High queue length - consider scaling back requests');
}
Environment Variables#
| Variable | Description | Required | Default |
|---|---|---|---|
RUNCOMFY_API_KEY |
API authentication key | Yes | - |
RUNCOMFY_BASE_URL |
API base URL | No | https://api.runcomfy.com/v1 |
RUNCOMFY_TIMEOUT_MS |
Request timeout | No | 120000 |
RUNCOMFY_DEBUG |
Enable debug logging | No | false |