RunningHub ComfyUI Workflow Runner

This skill provides tools to execute ComfyUI workflows on the RunningHub cloud platform via API.

Prerequisites

1. RunningHub Account - Register at https://www.runninghub.ai/?inviteCode=kol01-rh124
2. API Access - Basic membership or above (free users cannot use API)
3. API Key - Get your 32-character API KEY from the API Console
4. Workflow ID - The workflow must have been successfully run manually at least once

Getting API Key

1. Login to RunningHub
2. Click your avatar in the top-right corner
3. Go to "API Console"
4. Copy your API KEY (keep it secure!)

Getting Workflow ID

1. Open the target workflow page
2. Get the ID from the URL: https://www.runninghub.ai/#/workflow/WORKFLOW_ID
3. Example: ID is 1987728214757978114

Setup API Key

Option 1: Save to Config File (Recommended)

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

The API key will be saved to config.json and automatically loaded for future runs.

Option 2: Environment Variable

export RUNNINGHUB_API_KEY=YOUR_API_KEY

Option 3: Command Line (Each Time)

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

Usage

Submit Workflow Task (Default Configuration)

For workflows using default configuration:

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

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

Run Workflow with Custom Image (NEW!)

Upload an image and run the workflow with it:

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

Parameters:

• --image: Path to the local image file
• --node-id: The node ID for image input (default: 107)
• --field-name: The field name for image input (default: image)

Query Task Status

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

Wait for Completion

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

Python API Usage

from runninghub_client import RunningHubClient, load_config, get_api_key

# Get API key from config
api_key = get_api_key()

# Initialize client
client = RunningHubClient(api_key)

# Upload image and get URL
image_url = client.upload_image("/path/to/image.png")
print(f"Image URL: {image_url}")

# Submit workflow with custom image
result = client.submit_workflow_with_image(
    workflow_id="1987728214757978114",
    node_id="107",
    field_name="image",
    image_url=image_url
)

task_id = result["taskId"]

# Wait for completion
final_result = client.wait_for_completion(task_id)

# Get output URLs
if final_result.get("status") == "SUCCESS":
    for item in final_result.get("results", []):
        print(f"Output: {item.get('url')}")

API Reference

RunningHubClient Class

__init__(api_key: str)

Initialize the client with your API KEY.

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

Upload an image file to RunningHub and get the URL.

Returns:

• Image URL on success
• None on failure

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

Submit a workflow task for execution.

Parameters:

• workflow_id: The workflow ID from RunningHub
• node_info_list: Node configuration list (optional)

Important: Use fieldValue (not value) in node_info_list:

node_info_list = [
    {
        "nodeId": "107",
        "fieldName": "image",
        "fieldValue": "https://..."  # ✅ Use fieldValue, not value
    }
]

Returns:

{
  "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

Submit a workflow with an image input (convenience method).

Example:

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

query_task(task_id: str) -> Dict

Query the status of a submitted task.

Returns:

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

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

Wait for a task to complete by polling status.

Image Upload

Endpoint: POST /openapi/v2/media/upload/binary

Headers:

• Authorization: Bearer \x3Capi_key>

Body:

• Multipart form-data with file field

Response:

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

Submit Workflow with Custom Input

Endpoint: POST /openapi/v2/run/workflow/{workflow_id}

Headers:

• Authorization: Bearer \x3Capi_key>
• Content-Type: application/json

Request Body:

{
  "apiKey": "your-api-key",
  "workflowId": "1987728214757978114",
  "addMetadata": true,
  "nodeInfoList": [
    {
      "nodeId": "107",
      "fieldName": "image",
      "fieldValue": "https://..."  // ✅ Use fieldValue, not value
    }
  ],
  "instanceType": "default",
  "usePersonalQueue": "false"
}

Important: Use fieldValue not value for node input values!

Important Notes

1. Use fieldValue not value: When passing node input values via API, always use fieldValue:

   {"nodeId": "107", "fieldName": "image", "fieldValue": "..."}  // ✅ Correct
   {"nodeId": "107", "fieldName": "image", "value": "..."}       // ❌ Wrong
   

2. Rate Limiting: Basic members have concurrency limits (usually 1 task at a time)

3. Error 421: "API queue limit reached" - Wait for previous tasks to complete

4. Authentication: Uses Authorization: Bearer \x3Capi_key> header

5. API Endpoints:

   • Submit: POST /openapi/v2/run/workflow/{workflow_id}
   • Query: POST /openapi/v2/query
   • Upload: POST /openapi/v2/media/upload/binary

Troubleshooting

"Invalid node info" (Error 803)

• Check that you're using fieldValue not value
• Verify the nodeId and fieldName match the workflow configuration
• Use the workflow's getJsonApiFormat endpoint to check available nodes

"API queue limit reached" (Error 421)

• Wait 2-3 minutes and retry
• Check RunningHub web console for running tasks
• Cancel tasks from web console if needed

"TOKEN_INVALID" (Error 412)

• Verify your API KEY is correct (32 characters)
• Check if your membership is active
• Try regenerating the API KEY from console

Task stuck in "RUNNING"

• Large workflows may take several minutes
• Check RunningHub web console for actual progress
• Contact support if task runs too long