runpod/worker-comfyui repository overview

⁠worker-comfyui

This project allows you to run ComfyUI workflows as a serverless API endpoint on the RunPod platform. Submit workflows via API calls and receive generated images as base64 strings or S3 URLs.

⁠Table of Contents

• Quickstart⁠
• Available Docker Images⁠
• API Specification⁠
• Usage⁠
• Getting the Workflow JSON⁠
• Further Documentation⁠

⁠Quickstart

1. 🐳 Choose one of the available Docker images⁠ for your serverless endpoint (e.g., runpod/worker-comfyui:<version>-sd3).
2. 📄 Follow the Deployment Guide⁠ to set up your RunPod template and endpoint.
3. ⚙️ Optionally configure the worker (e.g., for S3 upload) using environment variables - see the full Configuration Guide⁠.
4. 🧪 Pick an example workflow from test_resources/workflows/⁠ or get your own⁠.
5. 🚀 Follow the Usage⁠ steps below to interact with your deployed endpoint.

⁠Available Docker Images

These images are available on Docker Hub under runpod/worker-comfyui:

• runpod/worker-comfyui:<version>-base: Clean ComfyUI install with no models.
• runpod/worker-comfyui:<version>-flux1-schnell: Includes checkpoint, text encoders, and VAE for FLUX.1 schnell⁠.
• runpod/worker-comfyui:<version>-flux1-dev: Includes checkpoint, text encoders, and VAE for FLUX.1 dev⁠.
• runpod/worker-comfyui:<version>-sdxl: Includes checkpoint and VAEs for Stable Diffusion XL⁠.
• runpod/worker-comfyui:<version>-sd3: Includes checkpoint for Stable Diffusion 3 medium⁠.

Replace <version> with the current release tag, check the releases page⁠ for the latest version.

⁠API Specification

The worker exposes standard RunPod serverless endpoints (/run, /runsync, /health). By default, images are returned as base64 strings. You can configure the worker to upload images to an S3 bucket instead by setting specific environment variables (see Configuration Guide⁠).

Use the /runsync endpoint for synchronous requests that wait for the job to complete and return the result directly. Use the /run endpoint for asynchronous requests that return immediately with a job ID; you'll need to poll the /status endpoint separately to get the result.

⁠Input

{
  "input": {
    "workflow": {
      "6": {
        "inputs": {
          "text": "a ball on the table",
          "clip": ["30", 1]
        },
        "class_type": "CLIPTextEncode",
        "_meta": {
          "title": "CLIP Text Encode (Positive Prompt)"
        }
      }
    },
    "images": [
      {
        "name": "input_image_1.png",
        "image": "data:image/png;base64,iVBOR..."
      }
    ]
  }
}

The following tables describe the fields within the input object:

⁠input.images Object

Each object within the input.images array must contain:

⁠Output

{
  "id": "sync-uuid-string",
  "status": "COMPLETED",
  "output": {
    "images": [
      {
        "filename": "ComfyUI_00001_.png",
        "type": "base64",
        "data": "iVBORw0KGgoAAAANSUhEUg..."
      }
    ]
  },
  "delayTime": 123,
  "executionTime": 4567
}

⁠output.images

Each object in the output.images array has the following structure:

⁠Usage

To interact with your deployed RunPod endpoint:

1. Get API Key: Generate a key in RunPod User Settings⁠ (API Keys section).
2. Get Endpoint ID: Find your endpoint ID on the Serverless Endpoints⁠ page or on the Overview page of your endpoint.

⁠Generate Image (Sync Example)

Send a workflow to the /runsync endpoint (waits for completion). Replace <api_key> and <endpoint_id>. The -d value should contain the JSON input described above⁠.

curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"input":{"workflow":{... your workflow JSON ...}}}' \
  https://api.runpod.ai/v2/<endpoint_id>/runsync

You can also use the /run endpoint for asynchronous jobs and then poll the /status to see when the job is done. Or you add a webhook into your request⁠ to be notified when the job is done.

Refer to test_input.json⁠ for a complete input example.

⁠Getting the Workflow JSON

To get the correct workflow JSON for the API:

1. Open ComfyUI in your browser.
2. In the top navigation, select Workflow > Export (API)
3. A workflow.json file will be downloaded. Use the content of this file as the value for the input.workflow field in your API requests.

⁠SSH Access

To enable SSH access to the worker, set the PUBLIC_KEY environment variable to your SSH public key. The worker will start an SSH server automatically. Make sure to expose port 22 in your RunPod template so you can connect.

⁠Further Documentation

• Deployment Guide⁠: Detailed steps for deploying on RunPod.
• Configuration Guide⁠: Full list of environment variables (including S3 setup).
• Customization Guide⁠: Adding custom models and nodes (Network Volumes, Docker builds).
• Development Guide⁠: Setting up a local environment for development & testing
• CI/CD Guide⁠: Information about the automated Docker build and publish workflows.
• Acknowledgments⁠: Credits and thanks