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

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

Host

string

required

Example:

www.runninghub.ai

Body Params application/json

apiKey

string

required

Example:

workflowId

string

required

Example:

1904136902449209346

nodeInfoList

array[object (Node Input Information) {3}]

optional

nodeId

string

optional

Example:

fieldName

string

optional

Example:

text

fieldValue

string

optional

Example:

1 girl in classroom

workflow

string

optional

Example:

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

boolean

optional

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 samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200成功

application/json

Body

code

integer

optional

返回标记：成功标记=0，非0失败，或者是功能码

Example:

msg

string

optional

返回信息

Example:

success

data

object (TaskCreateResponse)

optional

数据

netWssUrl

string

optional

Wss服务地址

taskId

integer <int64>

optional

任务Id

clientId

string

optional

客户端ID，当客户端首次接收clientId时，需要保存到本地，以便页面刷新重连或者二次运行任务传参使用

taskStatus

string

optional

任务状态: CREATE, SUCCESS, FAILED, RUNNING, QUEUED;

promptTips

string

optional

工作流验证结果提示,当不为空是UI需要展示节点错误信息

Example

{
  "code": 0,
  "msg": "",
  "data": {
    "taskId": 0,
    "clientId": "",
    "taskStatus": "",
    "promptTips": ""
  }
}

Start ComfyUI Task 2 - Advanced

Start ComfyUI Task (Advanced)#

Endpoint#

Method#

Request Headers#

Request Parameters#

Required Parameters#

nodeInfoList Structure#

Example Request#

Optional Parameters#

instanceType Usage Instructions#

About webhookUrl (Advanced Use)#

Response#

Successful Response#

Response Fields#

data Subfields#

Best Practices#

Related APIs#

Request

Request samples

Responses

Start ComfyUI Task (Advanced)

Endpoint

Method

Request Headers

Request Parameters

Required Parameters

nodeInfoList Structure

Example Request

Optional Parameters

instanceType Usage Instructions

About `webhookUrl` (Advanced Use)

Response

Successful Response

Response Fields

data Subfields

Best Practices

Related APIs