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 " \
  -H "Content-Type: application/json" \
  -d '{"input":{"workflow":{... your workflow JSON ...}}}' \
  https://api.runpod.ai/v2//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.

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