mixvideo-v2/cargos/uni-comfyui-sdk/README.md

uni-comfyui-sdk

A Rust SDK for ComfyUI Workflow Service & Management API.

Features

• Status Management: Get metrics, server status, and file listings
• Workflow Management: Create, retrieve, and delete workflows
• Workflow Execution: Run workflows and monitor their status
• Server Management: Register, unregister, and manage ComfyUI servers
• Monitoring: Health checks, system stats, and task monitoring
• Type Safety: Strongly typed API with comprehensive error handling

Installation

Add this to your Cargo.toml:

[dependencies]
uni-comfyui-sdk = "0.1.0"

Quick Start

use uni_comfyui_sdk::{UniComfyUIClient, Result};
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client
    let client = UniComfyUIClient::new("http://localhost:8000")?;

    // Get system metrics
    let metrics = client.get_metrics().await?;
    println!("Metrics: {:#?}", metrics);

    // Get all workflows
    let workflows = client.get_all_workflows().await?;
    println!("Found {} workflows", workflows.len());

    // Run a workflow
    let mut data = HashMap::new();
    data.insert("input".to_string(), serde_json::json!("test input"));
    let result = client.run_workflow("my_workflow", None, data).await?;
    println!("Workflow result: {:#?}", result);

    Ok(())
}

API Coverage

Status Endpoints

• get_metrics() - Get queue status overview
• get_servers_status() - Get all configured ComfyUI servers status
• list_server_files(server_index) - List files in server input/output folders

Workflow Endpoints

• get_all_workflows() - Get all workflows
• publish_workflow(data) - Publish a new workflow
• delete_workflow(workflow_name) - Delete a workflow
• get_one_workflow(base_name, version) - Get workflow specification

Run Endpoints

• run_workflow(name, version, data) - Execute workflow asynchronously
• get_run_status(workflow_run_id) - Get workflow execution status

RunX Endpoints

• model_with_multi_dress(version, data) - Model with multiple dresses workflow
• model_with_multi_dress_json_schema() - Get workflow definition

Monitor Endpoints

• monitor_dashboard() - Get monitoring dashboard HTML
• get_system_stats() - Get system statistics
• get_task_stats() - Get task statistics
• get_monitor_server_status() - Get server status information
• get_recent_tasks(limit) - Get recent tasks list
• health_check() - Health check endpoint

ComfyUI Server Management Endpoints

• register_server(request) - Register ComfyUI server
• update_heartbeat(request) - Update server heartbeat
• unregister_server(request) - Unregister ComfyUI server
• get_server_status(server_name) - Get specific server status
• list_all_servers() - Get all servers list
• get_system_health() - Get system overall health status
• force_health_check() - Force health check execution

Error Handling

The SDK provides comprehensive error handling through the ComfyUIError enum:

use uni_comfyui_sdk::{UniComfyUIClient, ComfyUIError};

match client.get_metrics().await {
    Ok(metrics) => println!("Success: {:#?}", metrics),
    Err(ComfyUIError::Http(e)) => println!("HTTP error: {}", e),
    Err(ComfyUIError::Api { status, message }) => {
        println!("API error {}: {}", status, message)
    }
    Err(e) => println!("Other error: {}", e),
}

Data Models

The SDK includes strongly typed models for all API requests and responses:

• ServerRegistrationRequest - Server registration data
• ServerHeartbeatRequest - Server heartbeat data
• ServerStatusResponse - Server status information
• ServerFiles - Server file listings
• FileDetails - Individual file information
• And more...

Examples

See the examples/ directory for more usage examples.

License

MIT