worker-comfyui

ComfyUI as a serverless API on RunPod

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:

[!NOTE]

Size Limits: RunPod endpoints have request size limits (e.g., 10MB for /run, 20MB for /runsync). Large base64 input images can exceed these limits. See RunPod Docs.

Output

[!WARNING]

Breaking Change in Output Format (5.0.0+)

Versions < 5.0.0 returned the primary image data (S3 URL or base64 string) directly within an output.message field. Starting with 5.0.0, the output format has changed significantly, see below

{
  "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:

[!NOTE] The output.images field provides a list of all generated images (excluding temporary ones).

• If S3 upload is not configured (default), type will be "base64" and data will contain the base64 encoded image string.
• If S3 upload is configured, type will be "s3_url" and data will contain the S3 URL. See the Configuration Guide for an S3 example response.
• Clients interacting with the API need to handle this list-based structure under output.images.

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