{"id":28156363,"url":"https://github.com/runpod-workers/worker-comfyui","last_synced_at":"2025-12-24T13:47:22.512Z","repository":{"id":199693790,"uuid":"702674692","full_name":"runpod-workers/worker-comfyui","owner":"runpod-workers","description":"ComfyUI as a serverless API on RunPod","archived":false,"fork":false,"pushed_at":"2025-05-09T11:40:34.000Z","size":3305,"stargazers_count":451,"open_issues_count":43,"forks_count":371,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-09T12:35:05.774Z","etag":null,"topics":["ai","comfyui","docker","pod","runpod","sdxl","serverless","stable-diffusion","worker"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runpod-workers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["blib-la"],"patreon":"Blib_la","open_collective":"blibla","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2023-10-09T19:18:26.000Z","updated_at":"2025-05-09T11:39:32.000Z","dependencies_parsed_at":"2024-02-20T17:27:44.208Z","dependency_job_id":"1e23e7b6-2566-4531-b932-72ab8d715490","html_url":"https://github.com/runpod-workers/worker-comfyui","commit_stats":null,"previous_names":["blib-la/runpod-worker-comfy","runpod-workers/worker-comfyui"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runpod-workers%2Fworker-comfyui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runpod-workers%2Fworker-comfyui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runpod-workers%2Fworker-comfyui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runpod-workers%2Fworker-comfyui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runpod-workers","download_url":"https://codeload.github.com/runpod-workers/worker-comfyui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301420,"owners_count":22047901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","comfyui","docker","pod","runpod","sdxl","serverless","stable-diffusion","worker"],"created_at":"2025-05-15T08:00:20.112Z","updated_at":"2025-12-24T13:47:22.504Z","avatar_url":"https://github.com/runpod-workers.png","language":"Python","funding_links":["https://github.com/sponsors/blib-la","https://patreon.com/Blib_la","https://opencollective.com/blibla"],"categories":[],"sub_categories":[],"readme":"# worker-comfyui\n\n\u003e [ComfyUI](https://github.com/comfyanonymous/ComfyUI) as a serverless API on [RunPod](https://www.runpod.io/)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/worker_sitting_in_comfy_chair.jpg\" title=\"Worker sitting in comfy chair\" /\u003e\n\u003c/p\u003e\n\n[![RunPod](https://api.runpod.io/badge/runpod-workers/worker-comfyui)](https://www.runpod.io/console/hub/runpod-workers/worker-comfyui)\n\n---\n\nThis 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.\n\n## Table of Contents\n\n- [Quickstart](#quickstart)\n- [Available Docker Images](#available-docker-images)\n- [API Specification](#api-specification)\n- [Usage](#usage)\n- [Getting the Workflow JSON](#getting-the-workflow-json)\n- [Further Documentation](#further-documentation)\n\n---\n\n## Quickstart\n\n1.  🐳 Choose one of the [available Docker images](#available-docker-images) for your serverless endpoint (e.g., `runpod/worker-comfyui:\u003cversion\u003e-sd3`).\n2.  📄 Follow the [Deployment Guide](docs/deployment.md) to set up your RunPod template and endpoint.\n3.  ⚙️ Optionally configure the worker (e.g., for S3 upload) using environment variables - see the full [Configuration Guide](docs/configuration.md).\n4.  🧪 Pick an example workflow from [`test_resources/workflows/`](./test_resources/workflows/) or [get your own](#getting-the-workflow-json).\n5.  🚀 Follow the [Usage](#usage) steps below to interact with your deployed endpoint.\n\n## Available Docker Images\n\nThese images are available on Docker Hub under `runpod/worker-comfyui`:\n\n- **`runpod/worker-comfyui:\u003cversion\u003e-base`**: Clean ComfyUI install with no models.\n- **`runpod/worker-comfyui:\u003cversion\u003e-flux1-schnell`**: Includes checkpoint, text encoders, and VAE for [FLUX.1 schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell).\n- **`runpod/worker-comfyui:\u003cversion\u003e-flux1-dev`**: Includes checkpoint, text encoders, and VAE for [FLUX.1 dev](https://huggingface.co/black-forest-labs/FLUX.1-dev).\n- **`runpod/worker-comfyui:\u003cversion\u003e-sdxl`**: Includes checkpoint and VAEs for [Stable Diffusion XL](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0).\n- **`runpod/worker-comfyui:\u003cversion\u003e-sd3`**: Includes checkpoint for [Stable Diffusion 3 medium](https://huggingface.co/stabilityai/stable-diffusion-3-medium).\n\nReplace `\u003cversion\u003e` with the current release tag, check the [releases page](https://github.com/runpod-workers/worker-comfyui/releases) for the latest version.\n\n## API Specification\n\nThe 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](docs/configuration.md)).\n\nUse 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.\n\n### Input\n\n```json\n{\n  \"input\": {\n    \"workflow\": {\n      \"6\": {\n        \"inputs\": {\n          \"text\": \"a ball on the table\",\n          \"clip\": [\"30\", 1]\n        },\n        \"class_type\": \"CLIPTextEncode\",\n        \"_meta\": {\n          \"title\": \"CLIP Text Encode (Positive Prompt)\"\n        }\n      }\n    },\n    \"images\": [\n      {\n        \"name\": \"input_image_1.png\",\n        \"image\": \"data:image/png;base64,iVBOR...\"\n      }\n    ]\n  }\n}\n```\n\nThe following tables describe the fields within the `input` object:\n\n| Field Path                | Type   | Required | Description                                                                                                                                |\n| ------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `input`                   | Object | Yes      | Top-level object containing request data.                                                                                                  |\n| `input.workflow`          | Object | Yes      | The ComfyUI workflow exported in the [required format](#getting-the-workflow-json).                                                        |\n| `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. |\n| `input.comfy_org_api_key` | String | No       | Optional per-request Comfy.org API key for API Nodes. Overrides the `COMFY_ORG_API_KEY` environment variable if both are set.              |\n\n#### `input.images` Object\n\nEach object within the `input.images` array must contain:\n\n| Field Name | Type   | Required | Description                                                                                                                       |\n| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `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.            |\n| `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. |\n\n\u003e [!NOTE]\n\u003e\n\u003e **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](https://docs.runpod.io/docs/serverless-endpoint-urls).\n\n### Output\n\n\u003e [!WARNING]\n\u003e\n\u003e **Breaking Change in Output Format (5.0.0+)**\n\u003e\n\u003e Versions `\u003c 5.0.0` returned the primary image data (S3 URL or base64 string) directly within an `output.message` field.\n\u003e Starting with `5.0.0`, the output format has changed significantly, see below\n\n```json\n{\n  \"id\": \"sync-uuid-string\",\n  \"status\": \"COMPLETED\",\n  \"output\": {\n    \"images\": [\n      {\n        \"filename\": \"ComfyUI_00001_.png\",\n        \"type\": \"base64\",\n        \"data\": \"iVBORw0KGgoAAAANSUhEUg...\"\n      }\n    ]\n  },\n  \"delayTime\": 123,\n  \"executionTime\": 4567\n}\n```\n\n| Field Path      | Type             | Required | Description                                                                                                 |\n| --------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- |\n| `output`        | Object           | Yes      | Top-level object containing the results of the job execution.                                               |\n| `output.images` | Array of Objects | No       | Present if the workflow generated images. Contains a list of objects, each representing one output image.   |\n| `output.errors` | Array of Strings | No       | Present if non-fatal errors or warnings occurred during processing (e.g., S3 upload failure, missing data). |\n\n#### `output.images`\n\nEach object in the `output.images` array has the following structure:\n\n| Field Name | Type   | Description                                                                                     |\n| ---------- | ------ | ----------------------------------------------------------------------------------------------- |\n| `filename` | String | The original filename assigned by ComfyUI during generation.                                    |\n| `type`     | String | Indicates the format of the data. Either `\"base64\"` or `\"s3_url\"` (if S3 upload is configured). |\n| `data`     | String | Contains either the base64 encoded image string or the S3 URL for the uploaded image file.      |\n\n\u003e [!NOTE]\n\u003e The `output.images` field provides a list of all generated images (excluding temporary ones).\n\u003e\n\u003e - If S3 upload is **not** configured (default), `type` will be `\"base64\"` and `data` will contain the base64 encoded image string.\n\u003e - If S3 upload **is** configured, `type` will be `\"s3_url\"` and `data` will contain the S3 URL. See the [Configuration Guide](docs/configuration.md#example-s3-response) for an S3 example response.\n\u003e - Clients interacting with the API need to handle this list-based structure under `output.images`.\n\n## Usage\n\nTo interact with your deployed RunPod endpoint:\n\n1.  **Get API Key:** Generate a key in RunPod [User Settings](https://www.runpod.io/console/serverless/user/settings) (`API Keys` section).\n2.  **Get Endpoint ID:** Find your endpoint ID on the [Serverless Endpoints](https://www.runpod.io/console/serverless/user/endpoints) page or on the `Overview` page of your endpoint.\n\n### Generate Image (Sync Example)\n\nSend a workflow to the `/runsync` endpoint (waits for completion). Replace `\u003capi_key\u003e` and `\u003cendpoint_id\u003e`. The `-d` value should contain the [JSON input described above](#input).\n\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer \u003capi_key\u003e\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\":{\"workflow\":{... your workflow JSON ...}}}' \\\n  https://api.runpod.ai/v2/\u003cendpoint_id\u003e/runsync\n```\n\nYou 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](https://docs.runpod.io/serverless/endpoints/send-requests#webhook-notifications) to be notified when the job is done.\n\nRefer to [`test_input.json`](./test_input.json) for a complete input example.\n\n## Getting the Workflow JSON\n\nTo get the correct `workflow` JSON for the API:\n\n1.  Open ComfyUI in your browser.\n2.  In the top navigation, select `Workflow \u003e Export (API)`\n3.  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.\n\n## Further Documentation\n\n- **[Deployment Guide](docs/deployment.md):** Detailed steps for deploying on RunPod.\n- **[Configuration Guide](docs/configuration.md):** Full list of environment variables (including S3 setup).\n- **[Customization Guide](docs/customization.md):** Adding custom models and nodes (Network Volumes, Docker builds).\n- **[Development Guide](docs/development.md):** Setting up a local environment for development \u0026 testing\n- **[CI/CD Guide](docs/ci-cd.md):** Information about the automated Docker build and publish workflows.\n- **[Acknowledgments](docs/acknowledgments.md):** Credits and thanks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunpod-workers%2Fworker-comfyui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunpod-workers%2Fworker-comfyui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunpod-workers%2Fworker-comfyui/lists"}