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

• 🐳 Choose one of the available Docker images for your serverless endpoint (e.g., runpod/worker-comfyui:<version>-sd3).
• 📄 Follow the Deployment Guide to set up your RunPod template and endpoint.
• ⚙️ Optionally configure the worker (e.g., for S3 upload) using environment variables - see the full Configuration Guide.
• 🧪 Pick an example workflow from test_resources/workflows/ or get your own.
• 🚀 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.

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": "inputimage1.png",
        "image": "data:image/png;base64,iVBOR..."
      }
    ]
  }
}

The following tables describe the fields within the input object:

| Field Path | Type | Required | Description | | ------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | input | Object | Yes | Top-level object containing request data. | | input.workflow | Object | Yes | The ComfyUI workflow exported in the required format. | | input.images | Array | No | Optional array of input images. Each image is uploaded to ComfyUI's input directory and can be referenced by its name in the workflow. | | input.comfyorgapikey | String | No | Optional per-request Comfy.org API key for API Nodes. Overrides the COMFYORGAPIKEY environment variable if both are set. |

input.images Object

Each object within the input.images array must contain:

| Field Name | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | name | String | Yes | Filename used to reference the image in the workflow (e.g., via a "Load Image" node). Must be unique within the array. | | image | String | Yes | Base64 encoded string of the image. A data URI prefix (e.g., data:image/png;base64,) is optional and will be handled correctly. |

[!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": "ComfyUI00001.png",
        "type": "base64",
        "data": "iVBORw0KGgoAAAANSUhEUg..."
      }
    ]
  },
  "delayTime": 123,
  "executionTime": 4567
}

| Field Path | Type | Required | Description | | --------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | output | Object | Yes | Top-level object containing the results of the job execution. | | output.images | Array of Objects | No | Present if the workflow generated images. Contains a list of objects, each representing one output image. | | output.errors | Array of Strings | No | Present if non-fatal errors or warnings occurred during processing (e.g., S3 upload failure, missing data). |

output.images

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

| Field Name | Type | Description | | ---------- | ------ | ----------------------------------------------------------------------------------------------- | | filename | String | The original filename assigned by ComfyUI during generation. | | type | String | Indicates the format of the data. Either "base64" or "s3_url" (if S3 upload is configured). | | data | String | Contains either the base64 encoded image string or the S3 URL for the uploaded image file. |

[!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 "s3url" and data will contain the S3 URL. See the Configuration Guide for an S3 example response.

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