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.
- Quickstart
- Available Docker Images
- API Specification
- Usage
- Getting the Workflow JSON
- Further Documentation
- 🐳 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.
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.
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": {
"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:
| 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. |
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.
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
}| 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). |
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),
typewill be"base64"anddatawill contain the base64 encoded image string. - If S3 upload is configured,
typewill be"s3_url"anddatawill 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.
To interact with your deployed RunPod endpoint:
- Get API Key: Generate a key in RunPod User Settings (
API Keyssection). - Get Endpoint ID: Find your endpoint ID on the Serverless Endpoints page or on the
Overviewpage of your endpoint.
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>/runsyncYou 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.
To get the correct workflow JSON for the API:
- Open ComfyUI in your browser.
- In the top navigation, select
Workflow > Export (API) - A
workflow.jsonfile will be downloaded. Use the content of this file as the value for theinput.workflowfield in your API requests.
- 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