worker-comfyui

ComfyUI 作为无服务器 API，在 RunPod 上运行

---

本项目允许您在 RunPod 平台上将 ComfyUI 工作流作为无服务器 API 端点运行。通过 API 调用提交工作流，并以 base64 字符串或 S3 URL 的形式接收生成的图像。

目录

• 快速入门
• 可用的 Docker 镜像
• API 规范
• 使用方法
• 获取工作流 JSON
• 更多文档

---

快速入门

1. 🐳 为您的无服务器端点选择一个 可用的 Docker 镜像，例如 runpod/worker-comfyui:<version>-sd3。
2. 📄 按照 部署指南 设置您的 RunPod 模板和端点。
3. ⚙️ 您可以使用环境变量对工作器进行可选配置（例如用于 S3 上传），请参阅完整的 配置指南。
4. 🧪 从 test_resources/workflows/ 中选择一个示例工作流，或者 获取您自己的工作流 JSON。
5. 🚀 按照下面的 使用方法 步骤与您部署的端点交互。

可用的 Docker 镜像

这些镜像可在 Docker Hub 上找到，仓库名为 runpod/worker-comfyui：

• runpod/worker-comfyui:<version>-base：纯净的 ComfyUI 安装，不含任何模型。
• runpod/worker-comfyui:<version>-flux1-schnell：包含 FLUX.1 schnell 所需的检查点、文本编码器和 VAE。
• runpod/worker-comfyui:<version>-flux1-dev：包含 FLUX.1 dev 所需的检查点、文本编码器和 VAE。
• runpod/worker-comfyui:<version>-sdxl：包含 Stable Diffusion XL 所需的检查点和 VAE。
• runpod/worker-comfyui:<version>-sd3：包含 Stable Diffusion 3 medium 所需的检查点。

请将 <version> 替换为当前的发布标签，最新版本可在 发行页面 查看。

API 规范

该工作器暴露了标准的 RunPod 无服务器端点（/run、/runsync、/health）。默认情况下，图像会以 base64 字符串的形式返回。您可以通过设置特定的环境变量来配置工作器，使其将图像上传到 S3 存储桶（详见 配置指南）。

对于需要等待任务完成并直接返回结果的同步请求，请使用 /runsync 端点。而对于异步请求，则应使用 /run 端点，它会立即返回一个作业 ID；您需要单独轮询 /status 端点来获取结果。

输入

{
  "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..."
      }
    ]
  }
}

下表描述了 input 对象中的字段：

字段路径	类型	必填	描述
input	对象	是	包含请求数据的顶层对象。
input.workflow	对象	是	以 所需格式 导出的 ComfyUI 工作流。
input.images	数组	否	可选的输入图像数组。每张图像都会被上传到 ComfyUI 的 input 目录，并可以在工作流中通过其 name 引用。
input.comfy_org_api_key	字符串	否	可选的每请求 Comfy.org API 密钥，用于 API 节点。如果同时设置了此键和 COMFY_ORG_API_KEY 环境变量，则优先使用前者。

input.images 对象

input.images 数组中的每个对象必须包含以下字段：

字段名	类型	必填	描述
name	字符串	是	用于在工作流中引用该图像的文件名（例如通过“加载图像”节点）。数组内必须唯一。
image	字符串	是	图像的 base64 编码字符串。数据 URI 前缀（如 data:image/png;base64,）是可选的，系统会正确处理。

[!NOTE]

大小限制： RunPod 端点对请求大小有限制（例如 /run 为 10MB，/runsync 为 20MB）。较大的 base64 格式输入图像可能会超出这些限制。更多信息请参阅 RunPod 文档。

输出

[!WARNING]

输出格式的重大变更（5.0.0 及以上版本）

版本 < 5.0.0 会直接在 output.message 字段中返回主图像数据（S3 URL 或 base64 字符串）。 自 5.0.0 起，输出格式发生了显著变化，详情如下所示。

{
  "id": "sync-uuid-string",
  "status": "COMPLETED",
  "output": {
    "images": [
      {
        "filename": "ComfyUI_00001_.png",
        "type": "base64",
        "data": "iVBORw0KGgoAAAANSUhEUg..."
      }
    ]
  },
  "delayTime": 123,
  "executionTime": 4567
}

字段路径	类型	是否必填	描述
output	对象	是	顶层对象，包含作业执行结果。
output.images	对象数组	否	如果工作流生成了图像，则存在此字段。包含一个对象列表，每个对象代表一张输出图像。
output.errors	字符串数组	否	如果处理过程中发生了非致命错误或警告（例如 S3 上传失败、数据缺失），则存在此字段。

output.images

output.images 数组中的每个对象具有以下结构：

字段名称	类型	描述
filename	字符串	ComfyUI 在生成过程中分配的原始文件名。
type	字符串	表示数据的格式。可以是 "base64" 或 "s3_url"（如果已配置 S3 上传）。
data	字符串	包含 base64 编码的图像字符串，或者已上传图像文件的 S3 URL。

[!NOTE] output.images 字段提供了所有生成图像的列表（不包括临时图像）。

• 如果未配置 S3 上传（默认情况），type 将为 "base64"，data 将包含 base64 编码的图像字符串。
• 如果已配置 S3 上传，type 将为 "s3_url"，data 将包含 S3 URL。有关 S3 示例响应，请参阅配置指南。
• 与 API 交互的客户端需要处理 output.images 下的列表结构。

使用方法

要与您部署的 RunPod 端点进行交互：

1. 获取 API 密钥： 在 RunPod 的用户设置中生成密钥（“API 密钥”部分）。
2. 获取端点 ID： 您可以在无服务器端点页面或您的端点“概览”页面上找到端点 ID。

生成图像（同步示例）

将工作流发送到 /runsync 端点（等待完成）。请替换 <api_key> 和 <endpoint_id>。-d 参数应包含上述输入 JSON。

curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"input":{"workflow":{... 您的工作流 JSON ...}}}' \
  https://api.runpod.ai/v2/<endpoint_id>/runsync

您也可以使用 /run 端点提交异步任务，然后轮询 /status 来查看任务何时完成。或者您可以在请求中添加 webhook，以便在任务完成后收到通知。

完整的输入示例请参考 test_input.json。

获取工作流 JSON

要获取适用于 API 的正确 workflow JSON：

1. 在浏览器中打开 ComfyUI。
2. 在顶部导航栏中选择“工作流 > 导出（API）”。
3. 将下载一个 workflow.json 文件。请将该文件的内容用作 API 请求中 input.workflow 字段的值。

SSH 访问

要启用对工作器的 SSH 访问，请将 PUBLIC_KEY 环境变量设置为您自己的 SSH 公钥。工作器将自动启动 SSH 服务器。请确保在您的 RunPod 模板中开放 端口 22，以便您可以连接。

更多文档

• 部署指南： 在 RunPod 上部署的详细步骤。
• 配置指南： 环境变量的完整列表（包括 S3 设置）。
• 定制指南： 添加自定义模型和节点（网络卷、Docker 构建）。
• 开发指南： 搭建本地开发与测试环境。
• CI/CD 指南： 关于自动化 Docker 构建和发布流程的信息。
• 致谢： 致谢与感谢

worker-comfyui 快速上手指南

本指南帮助中国开发者在 RunPod 平台上快速部署并使用 ComfyUI 作为无服务器（Serverless）API。

环境准备

在开始之前，请确保满足以下要求：

• RunPod 账号：拥有有效的 RunPod 账户并已完成充值。
• API 密钥：在 RunPod 控制台的 User Settings 中生成 API Key。
• 基础工具：本地安装了 curl 或 Postman 等 API 测试工具，以及能够编辑 JSON 文件的编辑器。
• 网络环境：由于模型下载和 Docker 拉取涉及海外资源，建议配置稳定的网络环境或使用代理加速。

安装步骤

本项目无需在本地安装复杂依赖，核心步骤是在 RunPod 云端配置 Serverless 端点。

1. 选择 Docker 镜像

登录 RunPod 控制台，创建新的 Serverless Endpoint 时，选择以下官方预构建镜像之一（将 <version> 替换为 Releases 页面 上的最新版本号）：

• 基础版 (无预装模型): runpod/worker-comfyui:<version>-base
• FLUX.1 Schnell: runpod/worker-comfyui:<version>-flux1-schnell
• FLUX.1 Dev: runpod/worker-comfyui:<version>-flux1-dev
• Stable Diffusion XL: runpod/worker-comfyui:<version>-sdxl
• Stable Diffusion 3 Medium: runpod/worker-comfyui:<version>-sd3

2. 部署端点

1. 进入 RunPod Console -> Serverless -> New Endpoint。
2. 输入端点名称，选择上述 Docker 镜像。
3. 选择 GPU 类型（推荐 A10G, A100 或 H100）。
4. （可选）配置环境变量：如需将生成的图片自动上传至 S3，请参考 Configuration Guide 设置 S3_BUCKET_NAME 等相关变量。
5. 点击 Deploy 启动端点。
6. 部署完成后，复制 Endpoint ID 备用。

基本使用

第一步：获取工作流 JSON

API 需要标准的 ComfyUI 工作流 JSON 格式：

1. 在浏览器打开本地或在线 ComfyUI。
2. 点击右上角菜单 Workflow > Export (API)。
3. 下载 workflow.json 文件，其内容即为 API 请求中的 workflow 字段值。

第二步：调用 API 生成图片

使用 curl 命令向你的端点发送同步请求（/runsync），等待任务完成并直接返回结果。

请替换以下占位符：

• <api_key>: 你的 RunPod API Key
• <endpoint_id>: 你的端点 ID
• {... your workflow JSON ...}: 第一步中获取的工作流内容

curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "workflow": {
        "6": {
          "inputs": {
            "text": "a ball on the table",
            "clip": ["30", 1]
          },
          "class_type": "CLIPTextEncode",
          "_meta": {
            "title": "CLIP Text Encode (Positive Prompt)"
          }
        }
      }
    }
  }' \
  https://api.runpod.ai/v2/<endpoint_id>/runsync

第三步：解析返回结果

成功响应（Status 200）将返回如下 JSON 结构。生成的图片位于 output.images 数组中：

{
  "id": "sync-uuid-string",
  "status": "COMPLETED",
  "output": {
    "images": [
      {
        "filename": "ComfyUI_00001_.png",
        "type": "base64",
        "data": "iVBORw0KGgoAAAANSUhEUg..." 
      }
    ]
  },
  "delayTime": 123,
  "executionTime": 4567
}

• type: "base64" 表示数据为 Base64 编码字符串（默认）；若配置了 S3，则为 "s3_url"。
• data: 包含具体的图片数据或下载链接。

注意：RunPod 对请求大小有限制（同步请求约 20MB）。如果需要传入大图作为底图，请确保 Base64 编码后的尺寸未超限，或考虑使用异步请求 (/run) 配合 Webhook。