RunningHub ComfyUI 工作流执行器

本技能提供通过 API 在 RunningHub 云平台执行 ComfyUI 工作流的工具。

前提条件

1. RunningHub 账户 —— 访问 https://www.runninghub.ai/?inviteCode=kol01-rh124 注册
2. API 访问权限 —— 基础会员或更高等级（免费用户无法使用 API）
3. API Key —— 在 API 控制台中获取您的 32 位字符 API KEY
4. 工作流 ID —— 该工作流必须至少已手动成功运行过一次

获取 API Key

1. 登录 RunningHub
2. 点击右上角您的头像
3. 进入“API 控制台”
4. 复制您的 API KEY（请妥善保管！）

获取工作流 ID

1. 打开目标工作流页面
2. 从 URL 中提取 ID：https://www.runninghub.ai/#/workflow/WORKFLOW_ID
3. 示例：ID 为 1987728214757978114

配置 API Key

方式一：保存至配置文件（推荐）

cd /root/.openclaw/workspace/skills/runninghub-comfyui
python3 scripts/runninghub_client.py --save-key YOUR_API_KEY

API Key 将被保存至 config.json，后续运行时将自动加载。

方式二：环境变量

export RUNNINGHUB_API_KEY=YOUR_API_KEY

方式三：命令行传参（每次执行均需指定）

python3 scripts/runninghub_client.py --api-key YOUR_API_KEY ...

使用方法

提交工作流任务（默认配置）

适用于采用默认配置的工作流：

cd /root/.openclaw/workspace/skills/runninghub-comfyui

python3 scripts/runninghub_client.py 
  --workflow-id 1987728214757978114 
  --action submit

使用自定义图像运行工作流（新增功能！）

上传一张图像，并以此图像作为输入运行工作流：

python3 scripts/runninghub_client.py 
  --workflow-id 1987728214757978114 
  --action run-with-image 
  --image /path/to/your/image.png 
  --node-id 107 
  --field-name image

参数说明：

• --image：本地图像文件路径
• --node-id：图像输入节点 ID（默认值：107）
• --field-name：图像输入字段名（默认值：image）

查询任务状态

python3 scripts/runninghub_client.py 
  --task-id TASK_ID 
  --action query

等待任务完成

python3 scripts/runninghub_client.py 
  --task-id TASK_ID 
  --action wait 
  --poll-interval 5 
  --max-attempts 60

Python API 使用方式

from runninghub_client import RunningHubClient, load_config, get_api_key

# 从配置中获取 API Key
api_key = get_api_key()

# 初始化客户端
client = RunningHubClient(api_key)

# 上传图像并获取 URL
image_url = client.upload_image("/path/to/image.png")
print(f"Image URL: {image_url}")

# 提交带自定义图像的工作流
result = client.submit_workflow_with_image(
    workflow_id="1987728214757978114",
    node_id="107",
    field_name="image",
    image_url=image_url
)

task_id = result["taskId"]

# 等待任务完成
final_result = client.wait_for_completion(task_id)

# 获取输出文件 URL
if final_result.get("status") == "SUCCESS":
    for item in final_result.get("results", []):
        print(f"Output: {item.get('url')}")

API 参考文档

RunningHubClient 类

__init__(api_key: str)

使用您的 API KEY 初始化客户端。

upload_image(image_path: str) -> Optional[str]

将图像文件上传至 RunningHub 并返回其 URL。

返回值：

• 成功时返回图像 URL
• 失败时返回 None

submit_workflow(workflow_id: str, node_info_list: Optional[list]) -> Dict

提交工作流任务以供执行。

参数说明：

• workflow_id：RunningHub 中的工作流 ID
• node_info_list：节点配置列表（可选）

重要提示： 在 node_info_list 中请使用 fieldValue（而非 value）：

node_info_list = [
    {
        "nodeId": "107",
        "fieldName": "image",
        "fieldValue": "https://..."  # ✅ 正确：使用 fieldValue
    }
]

返回值：

{
  "taskId": "TASK_ID",
  "status": "RUNNING",
  "clientId": "CLIENT_ID"
}

submit_workflow_with_image(workflow_id: str, node_id: str, field_name: str, image_url: str) -> Dict

提交带图像输入的工作流（便捷方法）。

示例：

result = client.submit_workflow_with_image(
    "1987728214757978114",  # workflow_id
    "107",                   # node_id
    "image",                 # field_name
    "https://..."            # image_url
)

query_task(task_id: str) -> Dict

查询已提交任务的状态。

返回值：

{
  "status": "RUNNING|SUCCESS|FAILED",
  "results": [
    {"url": "https://...", "filename": "..."}
  ]
}

wait_for_completion(task_id: str, poll_interval: int, max_attempts: int) -> Dict

通过轮询方式等待任务完成。

图像上传

接口地址： POST /openapi/v2/media/upload/binary

请求头（Headers）：

• Authorization: Bearer

请求体（Body）：

• Multipart form-data 格式，包含 file 字段

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "type": "image",
    "download_url": "https://...",
    "fileName": "openapi/...",
    "size": "3490"
  }
}

提交带自定义输入的工作流

接口地址： POST /openapi/v2/run/workflow/{workflow_id}

请求头（Headers）：

• Authorization: Bearer
• Content-Type: application/json

请求体（Request Body）：

{
  "apiKey": "your-api-key",
  "workflowId": "1987728214757978114",
  "addMetadata": true,
  "nodeInfoList": [
    {
      "nodeId": "107",
      "fieldName": "image",
      "fieldValue": "https://..."  // ✅ 正确：使用 fieldValue
    }
  ],
  "instanceType": "default",
  "usePersonalQueue": "false"
}

重要提示： 向节点传入输入值时，请始终使用 fieldValue，而非 value！

重要注意事项

1. 务必使用 fieldValue，而非 value：通过 API 传递节点输入值时，必须使用 fieldValue：

   {"nodeId": "107", "fieldName": "image", "fieldValue": "..."}  // ✅ 正确
   {"nodeId": "107", "fieldName": "image", "value": "..."}       // ❌ 错误
   

2. 速率限制：基础会员存在并发数限制（通常仅支持同时运行 1 个任务）

3. 错误码 421：“API 队列已达上限”——请等待先前任务完成后再重试

4. 身份认证方式：使用 Authorization: Bearer 请求头

5. API 接口地址列表：

   • 提交任务：POST /openapi/v2/run/workflow/{workflow_id}
   • 查询状态：POST /openapi/v2/query
   • 上传文件：POST /openapi/v2/media/upload/binary

故障排查

“Invalid node info”（错误码 803）

• 确认是否使用了 fieldValue 而非 value
• 确认 nodeId 和 fieldName 与工作流配置完全一致
• 调用工作流的 getJsonApiFormat 接口，检查可用节点信息

“API queue limit reached”（错误码 421）

• 等待 2–3 分钟后重试
• 在 RunningHub Web 控制台中查看当前运行中的任务
• 如需，可在 Web 控制台中取消任务

“TOKEN_INVALID”（错误码 412）

• 确认您的 API KEY 正确无误（长度应为 32 位字符）
• 检查您的会员资格是否处于有效状态
• 尝试在控制台中重新生成 API KEY

任务长时间处于 “RUNNING” 状态

• 大型工作流可能需要数分钟才能完成
• 请在 RunningHub Web 控制台中查看实际执行进度
• 若任务运行时间异常过长，请联系技术支持