Skip to content

🔥 ComfyUI-OneAPI: Transform Complex Multi-Step Workflow API Calls → Just One API | 工作流极简化API调用

License

Notifications You must be signed in to change notification settings

puke3615/ComfyUI-OneAPI

Repository files navigation

ComfyUI-OneAPI ✨

ComfyUI-OneAPI is a plugin that provides simple REST API interfaces for ComfyUI, allowing you to execute complex ComfyUI workflows through a single API request.

中文文档

🎯 Why ComfyUI-OneAPI?

ComfyUI-OneAPI Comparison

✨ Core Features

  • Extreme Simplicity - Execute complex ComfyUI workflows with just ONE API request
  • Dynamic Parameters - Replace workflow parameters dynamically through node title markers
  • Multi-Source Support - Support JSON objects, local files, and URLs as workflow inputs
  • Smart Output Management - Automatically categorize and organize multiple output nodes
  • UI Integration - Built-in right-click menus for workflow saving and parameter setting
  • Flexible Marking System - Support input markers ($param.field) and output markers ($output.name)

🚀 Core Advantages

  • 95% Code Reduction - From hundreds of lines of complex logic to a single API call
  • Unified Error Handling - Built-in comprehensive exception handling and error recovery
  • Parameterized Workflows - Dynamic parameter replacement through node title markers
  • Intelligent File Processing - Auto-handle image uploads, URL downloads, temp file management
  • Auto-categorized Results - Smart classification of different output types
  • Zero Learning Curve - Keep ComfyUI workflows unchanged, just add simple markers

⚡️ Quick Start

📦 Installation

  1. Open terminal/command line
  2. Navigate to ComfyUI's custom_nodes directory:
    cd ComfyUI/custom_nodes
  3. Clone this repository:
    git clone https://github.com/puke3615/ComfyUI-OneAPI.git
  4. Restart ComfyUI

🚀 Execute Workflow with Just One Request

curl -X POST "http://localhost:8188/oneapi/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": {...}  # Supports JSON object, local filename, or URL
  }'

📝 Simplest Request Format

{
  "workflow": {...}  # Supports JSON object, local filename, or URL
}

📤 Common Response Format

{
  "status": "completed",
  "images": ["http://server/image1.png", "http://server/image2.png"]
}

🔥 Advanced Usage

1️⃣ Dynamic Parameter Replacement - No More Workflow Edits 🔄

Add markers in node titles to easily replace parameters:

// Request
{
  "workflow": {...},
  "params": {
    "prompt": "cute cat",
    "input_image": "https://example.com/image.jpg"
  }
}

✨ How to Mark Nodes:

  • 📝 Text Prompt: Add $prompt.text to CLIPTextEncode node title
  • 🖼️ Input Image: Add $input_image to LoadImage node title

2️⃣ Distinguish Multiple Outputs - Handle Complex Workflows 🧩

When your workflow has multiple SaveImage nodes, easily distinguish different outputs:

// Response
{
  "status": "completed",
  "images": ["http://server/image1.png", "http://server/image2.png"],
  "images_by_var": {
    "background": ["http://server/image1.png"],
    "character": ["http://server/image2.png"]
  }
}

✨ How to Mark Output Nodes:

  • 💾 Add $output.background or $output.character to SaveImage node titles

📋 Advanced Features

🖥️ UI Features

This plugin adds convenient UI features to ComfyUI's interface:

📝 Save Workflow as API

How to use:

  1. Right-click on the canvas (empty area)
  2. Select "🚀 Save Workflow as API"
  3. Enter a workflow name in the dialog
  4. Choose whether to overwrite if the file exists
  5. Click "Save"

The workflow will be saved to user/default/api_workflows/ directory as a JSON file that can be used with the API.

🏷️ Set Node Input Parameters

How to use:

  1. Select a single node in the workflow
  2. Right-click on the node
  3. Select "🚀 Set Node Input"
  4. Choose which field you want to parameterize from the list
  5. Enter a variable name for the parameter
  6. The node's title will be automatically updated with the parameter marker

Example:

  • Select a CLIPTextEncode node
  • Choose "text" field
  • Enter "prompt" as variable name
  • Node title will be updated to include $prompt.text

This feature makes it easy to mark nodes for parameter replacement without manually editing node titles.

🔌 API Parameters

POST /oneapi/v1/execute

Request Body:
{
    "workflow": {...},               // Supports JSON object, local filename, or URL
    "params": {...},                 // Optional: Parameter mapping
    "wait_for_result": true/false,   // Optional: Wait for results (default true)
    "timeout": 300                   // Optional: Timeout in seconds
}

🏷️ Node Title Marker Rules

⬇️ Input Parameter Markers

  1. 🖼️ LoadImage node: Use $image_param format
  2. 🔄 Other nodes: Use $param.field_name format

Examples:

  • $input_image - LoadImage node uses params.input_image as the image
  • $prompt.text - Replaces text field with params.prompt

⬆️ Output Markers

Add markers to SaveImage node titles:

  • Format: $output.name (e.g., $output.background)
  • Without markers, node ID is used as the variable name

🔍 Examples

📝 Text-to-Image Example

curl -X POST "http://localhost:8188/oneapi/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "$(cat workflows/example_workflow.json)",  # Supports JSON object, local filename, or URL
    "params": {
        "prompt": "a cute dog with a red hat"
    }
  }'

🖼️ Image-to-Image Example

curl -X POST "http://localhost:8188/oneapi/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "$(cat workflows/example_img2img_workflow.json)",  # Supports JSON object, local filename, or URL
    "params": {
        "prompt": "a cute dog with a red hat",
        "image": "https://example.com/input.jpg"
    }
  }'

⚠️ Notes

  • 🔄 This plugin uses HTTP polling to get results, does not provide WebSocket real-time progress
  • ⏱️ Long-running workflows may cause request timeouts, consider setting appropriate timeout values
  • 🏷️ Parameter mapping and output marking depend on special markers in node titles

/oneapi/v1/execute API - workflow parameter supports three forms

Supported forms for the workflow parameter

    1. Pass workflow as a JSON object (original logic).
    1. Pass a local workflow filename (e.g. 1.json), which will be loaded from user/default/api_workflows/1.json.
    1. Pass a workflow URL (e.g. http://xxx/1.json), which will be downloaded and parsed automatically.

How to distinguish:

  • If workflow is a dict, use it directly.
  • If workflow is a string starting with http:// or https://, treat as URL and download.
  • Otherwise, treat as a local filename and load from user/default/workflows directory.

Examples:

// 1. Pass JSON directly
{"workflow": {"node1": {...}, ...}}

// 2. Pass local filename
// 1.json corresponds to <ComfyUI root>/user/default/api_workflows/1.json
{"workflow": "1.json"}

// 3. Pass URL
{"workflow": "https://example.com/1.json"}

About

🔥 ComfyUI-OneAPI: Transform Complex Multi-Step Workflow API Calls → Just One API | 工作流极简化API调用

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published