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

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

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",
  "retainSeconds": 60,
  "nodeInfoList": [
    {
      "nodeId": "6",
      "fieldName": "text",
      "fieldValue": "1 girl in classroom"
    }
  ]
}

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 JSON string (overrides `workflowId`)
`instanceType`	string	-	Specify the instance type (e.g., `plus`)
`usePersonalQueue`	boolean	false	Whether exclusive-type tasks should enter a queue
`retainSeconds`	Integer	-	Instance retention time (10~180s). See details below

retainSeconds Usage Instructions

Only valid for Enterprise Shared API Keys. When set, the instance will remain active for the specified duration after a task successfully completes. It will be prioritized for reuse by the same user with the same workflow, reducing cold start and queuing times.

Cost: Additional fees apply based on the actual duration the instance is retained.

Range: 10 to 180 seconds.

"retainSeconds": 60

Explanation of `usePersonalQueue`

This parameter only takes effect for API keys of the exclusive type. If enabled, tasks automatically enter a queue and execute when an exclusive machine assigned to the user becomes available. Limit: 1000 tasks per user.

instanceType Usage Instructions

To run a task on a "plus" instance (e.g., machines with 48GB VRAM), set the instanceType parameter:

"instanceType": "plus"

About `webhookUrl` (Advanced Use)

Set webhookUrl to receive automatic notifications. RunningHub will POST the following to your URL upon completion:

{
  "event": "TASK_END",
  "taskId": "1904163390028185602",
  "eventData": "{\"code\":0,\"msg\":\"success\",\"data\":[{\"fileUrl\":\"...\",\"fileType\":\"png\",\"nodeId\":\"9\"}]}"
}

Response

Successful Response

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "1910246754753896450",
    "taskStatus": "QUEUED",
    "clientId": "e825290b08ca2015b8f62f0bbdb5f5f6"
  }
}

Response Fields

Field	Type	Description
`code`	int	Response code, `0` means success
`msg`	string	Response message
`data`	object	Task result data

data Subfields

Field	Type	Description
`taskId`	string	Unique ID for querying status or result
`taskStatus`	string	Initial status: `QUEUED`, `RUNNING`, or `FAILED`
`promptTips`	string	ComfyUI validation messages or errors

Best Practices

✅ Always verify nodeId and fieldName against your exported workflow JSON.

✅ Use retainSeconds for high-frequency tasks to significantly improve response speed.

✅ Implement webhookUrl for efficient, asynchronous result handling.

❌ Avoid polling at extremely high frequencies; use webhooks where possible.

Check Task Status

Check Task Output

Upload Resource

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 'https://www.runninghub.ai/task/openapi/create' \
--header 'Host: www.runninghub.ai' \
--header 'Authorization: Bearer [Your API KEY]' \
--header 'Content-Type: application/json' \
--data '{
    "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

retainSeconds Usage Instructions

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#

retainSeconds Usage Instructions#

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

retainSeconds Usage Instructions

Explanation of `usePersonalQueue`

instanceType Usage Instructions

About `webhookUrl` (Advanced Use)

Response

Successful Response

Response Fields

data Subfields

Best Practices

Related APIs