Struct ComfyClient 

pub struct ComfyClient { /* private fields */ }

Async client for a ComfyUI server instance.

Provides REST methods for prompt queuing, history retrieval, image download, and model discovery. Supports both WebSocket-based real-time progress tracking and polling-based fallback.

Example

use comfyui_rs::ComfyClient;

let client = ComfyClient::new("http://127.0.0.1:8188");
let healthy = client.health().await?;

Implementations

impl ComfyClient

pub fn new(endpoint: impl Into<String>) -> Self

Create a new client pointing at the given ComfyUI endpoint.

pub fn with_http_client(self, client: Client) -> Self

Use a custom reqwest::Client (for connection pooling, timeouts, TLS).

pub fn with_client_id(self, id: impl Into<String>) -> Self

Set the client ID used for WebSocket filtering and prompt association.

pub fn endpoint(&self) -> &str

Returns the configured endpoint URL.

pub fn client_id(&self) -> &str

Returns the configured client ID.

pub async fn health(&self) -> Result<bool>

Check whether ComfyUI is reachable. Any HTTP response (even 500) means the server is running. Only connection/timeout failures return false.

pub async fn queue_prompt(&self, workflow: &Value) -> Result<String>

Queue a workflow for execution. Returns the prompt_id.

pub async fn history(&self, prompt_id: &str) -> Result<Option<PromptHistory>>

Fetch the history entry for a prompt. Returns None if not yet available.

pub async fn image(&self, img: &ImageRef) -> Result<Vec<u8>>

Download an output image by its reference. Returns raw bytes.

pub async fn queue_status(&self) -> Result<QueueStatus>

Get the current ComfyUI queue state (running + pending counts).

pub async fn free_memory(&self, unload_models: bool) -> Result<()>

Free VRAM. If unload_models is true, all models are unloaded.

pub async fn interrupt(&self) -> Result<()>

Interrupt the currently running generation.

pub async fn upload_image( &self, image_bytes: &[u8], filename: &str, overwrite: bool, ) -> Result<String>

Upload an image to ComfyUI’s input directory via /upload/image. Returns the filename as stored by ComfyUI.

pub async fn checkpoints(&self) -> Result<Vec<String>>

List available checkpoint models from ComfyUI.

pub async fn samplers(&self) -> Result<Vec<String>>

List available sampler algorithms from ComfyUI.

pub async fn schedulers(&self) -> Result<Vec<String>>

List available scheduler algorithms from ComfyUI.

pub async fn wait_for_completion( &self, prompt_id: &str, timeout: Duration, ) -> Result<GenerationOutcome>

Poll /history until the prompt completes, fails, or times out.

pub async fn wait_for_completion_ws<F>( &self, prompt_id: &str, timeout: Duration, on_progress: F, ) -> Result<GenerationOutcome>

where F: FnMut(ProgressUpdate),

Wait for completion using ComfyUI’s WebSocket for real-time step progress. Calls on_progress for each sampling step. Falls back to polling automatically if the WebSocket connection fails.

pub async fn queue_prompt_traced( &self, workflow: &Value, trace_ctx: Option<&TraceCtx>, ) -> Result<String>

Queue a workflow for execution with optional trace context.

Behaves identically to queue_prompt but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn history_traced( &self, prompt_id: &str, trace_ctx: Option<&TraceCtx>, ) -> Result<Option<PromptHistory>>

Fetch prompt history with optional trace context.

Behaves identically to history but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn image_traced( &self, img: &ImageRef, trace_ctx: Option<&TraceCtx>, ) -> Result<Vec<u8>>

Download an output image with optional trace context.

Behaves identically to image but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn queue_status_traced( &self, trace_ctx: Option<&TraceCtx>, ) -> Result<QueueStatus>

Get queue status with optional trace context.

Behaves identically to queue_status but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn upload_image_traced( &self, image_bytes: &[u8], filename: &str, overwrite: bool, trace_ctx: Option<&TraceCtx>, ) -> Result<String>

Upload an image with optional trace context.

Behaves identically to upload_image but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn interrupt_traced(&self, trace_ctx: Option<&TraceCtx>) -> Result<()>

Interrupt the current generation with optional trace context.

Behaves identically to interrupt but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn free_memory_traced( &self, unload_models: bool, trace_ctx: Option<&TraceCtx>, ) -> Result<()>

Free VRAM with optional trace context.

Behaves identically to free_memory but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn wait_for_completion_traced( &self, prompt_id: &str, timeout: Duration, trace_ctx: Option<&TraceCtx>, ) -> Result<GenerationOutcome>

Wait for prompt completion (polling) with optional trace context.

Behaves identically to wait_for_completion but logs the trace ID when a stack_ids::TraceCtx is provided.

pub async fn wait_for_completion_ws_traced<F>( &self, prompt_id: &str, timeout: Duration, on_progress: F, trace_ctx: Option<&TraceCtx>, ) -> Result<GenerationOutcome>

where F: FnMut(ProgressUpdate),

Wait for completion via WebSocket with optional trace context.

Behaves identically to wait_for_completion_ws but logs the trace ID when a stack_ids::TraceCtx is provided.

Trait Implementations

impl Clone for ComfyClient

fn clone(&self) -> ComfyClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ComfyClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.