Start ComfyUI Task (Advanced)

This API allows you to launch a ComfyUI image generation task based on an existing workflow template, with customized node parameters.

It is suitable for advanced use cases, such as modifying samplers, steps, prompts, seeds, or any other configurable fields in the workflow.
By specifying nodeInfoList, you can dynamically override node parameters, making your task highly flexible and programmable.

Endpoint

POST https://www.runninghub.ai/task/openapi/create

Method

POST with application/json body

Request Headers

Header	Required	Example	Description
`Host`	Yes	`www.runninghub.ai`	Your API domain (must be exact)
`Content-Type`	Yes	`application/json`	Request content type

⚠️ Note: The Host header is mandatory and must match www.runninghub.ai. It may be automatically included by some HTTP clients, but be sure to double-check.

Request Parameters

Required Parameters

Name	Type	Required	Description
`apiKey`	string	Yes	Your API key used for authentication
`workflowId`	string	Yes	Workflow template ID, exportable from the UI
`nodeInfoList`	array	No	List of node parameters to override before task execution

nodeInfoList Structure

Each item represents a node parameter override:

Field	Type	Description
`nodeId`	string	Unique ID of the node, from the exported workflow JSON
`fieldName`	string	Field name to override (e.g., `text`, `seed`, `steps`)
`fieldValue`	any	New value for the field, should match the expected type

Example Request

{
  "apiKey": "your-api-key",
  "workflowId": "1904136902449209346",
  "nodeInfoList": [
    {
      "nodeId": "6",
      "fieldName": "text",
      "fieldValue": "1 girl in classroom"
    },
    {
      "nodeId": "3",
      "fieldName": "seed",
      "fieldValue": "1231231"
    }
  ]
}

Optional Parameters

Name	Type	Default	Description
`addMetadata`	boolean	true	Whether to embed prompt metadata in the image
`webhookUrl`	string	-	Optional callback URL to receive result notifications
`workflow`	string	-	Custom full workflow in JSON string format. If provided, it overrides `workflowId`
`instanceType`	string	-	Specify the instance type when starting a task
`usePersonalQueue`	boolean	false	Whether exclusive-type tasks should enter a queue

Explanation of `usePersonalQueue`

This parameter only takes effect for API keys of the exclusive type. If you do not want to manage task queuing manually, you can set this parameter to true. The task will then automatically enter a queue and be executed when an exclusive machine assigned to the user becomes available.

Note: Each user has a personal queue limit of 1000 tasks. If this limit is exceeded, an error will be returned:
(814, "PERSONAL_QUEUE_COUNT_LIMIT")

"usePersonalQueue": "true"

instanceType Usage Instructions

If you want to run a "plus" task on a machine with 48GB of VRAM, you can set the instanceType parameter. For example:

"instanceType": "plus"

About `webhookUrl` (Advanced Use)

If you want the platform to automatically notify you when a task is completed, set the webhookUrl parameter. For example:

"webhookUrl": "https://your-webhook-url"

⚠️ Recommended for backend developers only.

Upon task completion, RunningHub will send a POST request to your URL with the following payload:

{
  "event": "TASK_END",
  "taskId": "1904163390028185602",
  "eventData": "{\"code\":0,\"msg\":\"success\",\"data\":[{\"fileUrl\":\"https://rh-images.xiaoyaoyou.com/de0db6f2564c8697b07df55a77f07be9/output/ComfyUI_00033_hpgko_1742822929.png\",\"fileType\":\"png\",\"taskCostTime\":0,\"nodeId\":\"9\"}]}"
}

event: Callback event name. Currently always TASK_END

taskId: ID of the completed task

eventData: Same structure as the Check Task Output API

⚠️ Important: Your webhook handler must process the request asynchronously.
RunningHub expects a fast response — long blocking logic may trigger retries due to timeout.

Response

Successful Response

{
  "code": 0,
  "msg": "success",
  "data": {
    "netWssUrl": null,
    "taskId": "1910246754753896450",
    "clientId": "e825290b08ca2015b8f62f0bbdb5f5f6",
    "taskStatus": "QUEUED",
    "promptTips": "{\"result\": true, \"error\": null, \"outputs_to_execute\": [\"9\"], \"node_errors\": {}}"
  }
}

Response Fields

Field	Type	Description
`code`	int	Response code, `0` means success
`msg`	string	Response message, usually `"success"`
`data`	object	Task result data (see below)

data Subfields

Field	Type	Description
`taskId`	string	Task ID, used for querying status or result
`taskStatus`	string	Initial task status: `QUEUED`, `RUNNING`, or `FAILED`
`clientId`	string	Internal tracking ID for debugging (not required for users)
`netWssUrl`	string	WebSocket URL for real-time updates (not recommended currently)
`promptTips`	string	JSON-formatted string showing ComfyUI validation messages or errors

Best Practices

✅ Always check and match nodeId and fieldName before sending the request

✅ Export the workflow JSON to explore available parameters for each node

⚠️ Use promptTips to identify invalid or misconfigured nodes

✅ Set webhookUrl if you want real-time results pushed to your backend

❌ Avoid using netWssUrl as it's currently unstable; use polling endpoints instead

Request

Authorization

Header Params

Body Params application/json

Example

{
    "apiKey": "{{apiKey}}",
    "workflowId": "1904136902449209346",
    "nodeInfoList": [
        {
            "nodeId": "6",
            "fieldName": "text",
            "fieldValue": "1 girl in classroom"
        }
    ],
    "workflow": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"scheduler\":\"karras\",\"negative\":[\"7\",0],\"denoise\":1,\"latent_image\":[\"5\",0],\"seed\":669816362794144,\"cfg\":8,\"sampler_name\":\"dpmpp_2m\",\"model\":[\"4\",0],\"positive\":[\"6\",0],\"steps\":20},\"_meta\":{\"title\":\"KSampler\"}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"MR 3DQ _SDXL V0.2.safetensors\"},\"_meta\":{\"title\":\"Load Checkpoint\"}},\"37\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"vae\":[\"4\",2],\"samples\":[\"3\",0]},\"_meta\":{\"title\":\"VAE Decode\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"batch_size\":1,\"width\":512,\"height\":512},\"_meta\":{\"title\":\"Empty Latent Image\"}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"speak_and_recognation\":{\"__value__\":[false,true]},\"text\":\"DreamWork 3D Style, a cute panda holding a bamboo in hands at sunset, highly detailed, ultra-high resolutions, 32K UHD, best quality, masterpiece, \",\"clip\":[\"4\",1]},\"_meta\":{\"title\":\"CLIP Text Encode (Prompt)\"}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"speak_and_recognation\":{\"__value__\":[false,true]},\"text\":\"\",\"clip\":[\"4\",1]},\"_meta\":{\"title\":\"CLIP Text Encode (Prompt)\"}},\"9\":{\"class_type\":\"SaveImage\",\"inputs\":{\"filename_prefix\":\"ComfyUI\",\"images\":[\"37\",0]},\"_meta\":{\"title\":\"Save Image\"}}}",
    "addMetadata": true
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://www.runninghub.ai/task/openapi/create' \
--header 'Host: www.runninghub.ai' \
--header 'Authorization: Bearer [Your API KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "apiKey": "Please enter your own apiKey and keep it safe.",
    "workflowId": "1904136902449209346",
    "nodeInfoList": [
        {
            "nodeId": "6",
            "fieldName": "text",
            "fieldValue": "1 girl in classroom"
        }
    ],
    "workflow": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"scheduler\":\"karras\",\"negative\":[\"7\",0],\"denoise\":1,\"latent_image\":[\"5\",0],\"seed\":669816362794144,\"cfg\":8,\"sampler_name\":\"dpmpp_2m\",\"model\":[\"4\",0],\"positive\":[\"6\",0],\"steps\":20},\"_meta\":{\"title\":\"KSampler\"}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"MR 3DQ _SDXL V0.2.safetensors\"},\"_meta\":{\"title\":\"Load Checkpoint\"}},\"37\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"vae\":[\"4\",2],\"samples\":[\"3\",0]},\"_meta\":{\"title\":\"VAE Decode\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"batch_size\":1,\"width\":512,\"height\":512},\"_meta\":{\"title\":\"Empty Latent Image\"}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"speak_and_recognation\":{\"__value__\":[false,true]},\"text\":\"DreamWork 3D Style, a cute panda holding a bamboo in hands at sunset, highly detailed, ultra-high resolutions, 32K UHD, best quality, masterpiece, \",\"clip\":[\"4\",1]},\"_meta\":{\"title\":\"CLIP Text Encode (Prompt)\"}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"speak_and_recognation\":{\"__value__\":[false,true]},\"text\":\"\",\"clip\":[\"4\",1]},\"_meta\":{\"title\":\"CLIP Text Encode (Prompt)\"}},\"9\":{\"class_type\":\"SaveImage\",\"inputs\":{\"filename_prefix\":\"ComfyUI\",\"images\":[\"37\",0]},\"_meta\":{\"title\":\"Save Image\"}}}",
    "addMetadata": true
}'

Start ComfyUI Task 2 - Advanced

Start ComfyUI Task (Advanced)

Endpoint

Method

Request Headers

Request Parameters

Required Parameters

nodeInfoList Structure

Example Request

Optional Parameters

Explanation of `usePersonalQueue`

instanceType Usage Instructions

About `webhookUrl` (Advanced Use)

Response

Successful Response

Response Fields

data Subfields

Best Practices

Request

Request Code Samples

Responses

Start ComfyUI Task 2 - Advanced

Start ComfyUI Task (Advanced)#

Endpoint#

Method#

Request Headers#

Request Parameters#

Required Parameters#

nodeInfoList Structure#

Example Request#

Optional Parameters#

Explanation of usePersonalQueue#

instanceType Usage Instructions#

About webhookUrl (Advanced Use)#

Response#

Successful Response#

Response Fields#

data Subfields#

Best Practices#

Related APIs#

Request

Request Code Samples

Responses

Start ComfyUI Task (Advanced)

Endpoint

Method

Request Headers

Request Parameters

Required Parameters

nodeInfoList Structure

Example Request

Optional Parameters

Explanation of `usePersonalQueue`

instanceType Usage Instructions

About `webhookUrl` (Advanced Use)

Response

Successful Response

Response Fields

data Subfields

Best Practices

Related APIs