工作流 API 文档说明

智算云扉支持通过 API 调用平台中的工作流。

所有工作流统一使用任务创建接口，通过 appId 指定需要运行的工作流。

每个工作流的输入参数独立配置，具体参数统一放在 inputParams 中，请以对应工作流页面展示的 API 参数说明 为准。

调用流程

text

创建 API 令牌
      ↓
选择工作流
      ↓
获取 appId 与 API 参数
      ↓
POST 创建任务
      ↓
获取任务 ID
      ↓
GET 查询任务
      ↓
获取生成结果

1. 创建 API 令牌

前往 API 令牌管理创建工作流 API 令牌。

工作流令牌创建图

调用 API 时，需要通过 Header 携带令牌：

http

Authorization: Bearer YOUR_API_TOKEN

注意

API Token 属于敏感凭证，请妥善保管。

请勿将 Token 提交到公开代码仓库、公开日志或直接暴露在前端代码中。

2. 选择工作流

前往工作流页面选择需要通过 API 调用的工作流。

每个工作流都会提供对应的：

appId
API 输入参数
参数类型
是否必填
参数限制
积分消耗

不同工作流的输入参数相互独立，请以对应工作流页面显示的 API 参数要求为准。

调用时，工作流自身参数统一放在：

json

{
  "inputParams": {}
}

中。

3. 创建工作流任务

请求地址

POST

text

https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/create

参数	类型	必填	说明
Authorization	string	是	API 访问令牌，格式：`Bearer <Token>`
Content-Type	string	是	固定为 `application/json`

Body 参数

参数	类型	必填	说明
appId	string	是	工作流唯一标识
inputParams	object	是	当前工作流所需的输入参数

TIP

创建后排队中的任务暂不支持取消。

所有工作流统一使用同一个任务创建接口。

调用不同工作流时，只需要更换对应的 appId，并按照该工作流要求填写 inputParams。

请求结构

json

{
  "appId": "APP_ID",
  "inputParams": {
    "参数名": "参数值"
  }
}

请求示例

假设当前工作流需要：

ratio
pixel
prompt
time

则请求示例如下：

http

POST https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/create
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "appId": "APP_ID",
  "inputParams": {
    "ratio": "9:16",
    "pixel": "768P",
    "prompt": "A cinematic city scene at dusk.",
    "time": 5
  }
}

cURL 示例

bash

curl --location \
--request POST 'https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/create' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appId": "APP_ID",
  "inputParams": {
    "ratio": "9:16",
    "pixel": "768P",
    "prompt": "A cinematic city scene at dusk.",
    "time": 5
  }
}'

其中：

YOUR_API_TOKEN：替换为你的 API 令牌
APP_ID：替换为当前工作流对应的 appId
inputParams：按照当前工作流页面显示的 API 参数填写

注意

示例中的 ratio、pixel、prompt、time 仅用于演示请求结构。

不同工作流的 inputParams 参数不同，请以对应工作流页面显示的 API 参数为准。

4. 查询工作流任务

创建任务成功后，接口会返回本次任务对应的任务 ID。

通过任务 ID 可以查询工作流当前执行状态、运行时间以及最终生成结果。

请求地址

GET

text

https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/getTask

调用查询接口时，需要携带 API Token，并传入创建任务后返回的任务 ID。

http

Authorization: Bearer YOUR_API_TOKEN

任务通常会经历：

text

排队中
  ↓
生成中
  ↓
成功 / 取消 / 失败 / 超时

当任务仍处于排队中或生成中时，可以间隔一段时间后再次调用查询接口。

任务成功后，即可从返回结果中的 files 字段获取生成文件。

查询返回示例

例如，当任务当前仍处于排队状态时，可能返回：

json

{
  "code": 0,
  "msg": null,
  "errCode": null,
  "data": {
    "taskId": "1154715881075376128",
    "status": 0,
    "startTime": null,
    "endTime": null,
    "executionDuration": null,
    "files": null
  },
  "ok": true
}

返回字段说明

字段	类型	说明
code	number	接口返回码，`0` 表示本次接口请求正常
msg	string / null	接口返回消息
errCode	string / null	错误码，无错误时通常为 `null`
data	object	当前工作流任务信息
data.taskId	string	工作流任务 ID
data.status	number	当前任务执行状态
data.startTime	string / null	任务开始执行时间，尚未开始时为 `null`
data.endTime	string / null	任务结束时间，尚未结束时为 `null`
data.executionDuration	number / null	任务执行耗时，尚未执行完成时可能为 `null`
data.files	array / null	工作流生成的文件结果，任务尚未成功时可能为 `null`
ok	boolean	本次查询接口请求是否正常

status 状态码说明

任务实际执行状态以：

text

data.status

字段为准。

status	状态	说明
`0`	排队中	任务已经创建，正在等待可用算力执行
`1`	生成中	工作流已经开始执行
`2`	成功	工作流执行成功，可以获取生成结果
`3`	取消	任务已被取消
`4`	失败	工作流执行失败
`5`	超时	工作流执行时间超过限制，任务已结束
`6`	上传中	文件正在上传

任务状态可以简单分为：

text

运行中
├── 0 排队中
├── 1 生成中
└── 6 上传中

已结束
├── 2 成功
├── 3 取消
├── 4 失败
└── 5 超时

注意

ok: true 仅表示本次 查询接口请求正常，并不代表工作流任务已经执行成功。

判断工作流是否执行成功，应以 data.status 为准。

例如：

json

{
  "ok": true,
  "data": {
    "status": 0
  }
}

表示查询接口调用正常，但当前工作流任务仍处于 排队中。

只有：

text

data.status = 2

时，才表示工作流任务执行成功。

状态判断

调用查询接口后，可以根据 data.status 判断下一步操作：

status	是否继续查询	下一步
`0`	是	等待后再次查询
`1`	是	等待后再次查询
`2`	否	获取 `files`
`3`	否	任务已取消
`4`	否	处理失败结果
`5`	否	处理超时结果

TIP

建议根据实际业务设置合理的查询间隔，避免无间隔、高频调用查询接口。

当 status 为 0 或 1 时，可以间隔一段时间再次查询。

当 status 为 2、3、4 或 5 时，任务已经结束，无需继续轮询。

5. 获取生成结果

当工作流执行成功，即：

text

data.status = 2

时，任务查询接口会通过：

text

data.files

返回对应的生成结果。

根据不同工作流，结果可能包括：

图片
视频
音频
其他文件

具体返回内容以实际工作流输出为准。

如果查询结果中：

text

data.files = null

说明当前没有可获取的生成文件，应结合 data.status 判断当前任务状态。

例如：

json

{
  "data": {
    "status": 0,
    "files": null
  }
}

表示任务仍处于排队中，因此暂时没有生成文件。

而当：

json

{
  "data": {
    "status": 2,
    "files": []
  }
}

时，表示任务已经执行完成，应根据实际返回的 files 内容读取工作流生成结果。

6. 支持的文件格式

平台目前支持以下文件格式。

图片

类型	扩展名
PNG	`.png`
JPEG	`.jpg` `.jpeg`
JFIF	`.jfif`
GIF	`.gif`
WebP	`.webp`
BMP	`.bmp`
SVG	`.svg`
TIFF	`.tif` `.tiff`
AVIF	`.avif`
HEIC	`.heic`
ICO	`.ico`

text

png, jpg, jpeg, jfif, gif, webp, bmp, svg, tif, tiff, avif, heic, ico

视频

类型	扩展名
MP4	`.mp4`
WebM	`.webm`
MKV	`.mkv`
MOV	`.mov`
AVI	`.avi`

text

mp4, webm, mkv, mov, avi

音频

类型	扩展名
MP3	`.mp3`
WAV	`.wav`
OGG	`.ogg`
FLAC	`.flac`
M4A	`.m4a`

text

mp3, wav, ogg, flac, m4a

注意

以上为平台支持识别的文件格式。

具体工作流是否支持图片、视频或音频，以及文件数量、大小、分辨率、时长等限制，请以对应工作流的 API 参数说明为准。

7. 积分与计费

智算云扉中的工作流运行需要消耗积分。

平台积分通过 算力点兑换 获得。

text

算力点
  ↓
兑换积分
  ↓
调用工作流
  ↓
消耗积分

不同工作流的积分消耗可能不同，具体以工作流页面显示的信息为准。

调用 API 前，请确保账户积分余额充足。

8. 调用日志

所有工作流 API 调用记录可以在调用日志中查看。

调用日志可用于查看：

调用时间
工作流信息
任务状态
运行结果
积分消耗
成功或失败记录

如果 API 调用出现异常，建议优先进入调用日志查看对应任务记录。

API 地址汇总

功能	请求方式	地址
创建工作流任务	POST	`https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/create`
查询工作流任务	GET	`https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/getTask`

快速开始

Step 1：创建 API Token

前往 API 令牌管理创建工作流 API Token。

Step 2：选择工作流

前往工作流页面选择需要调用的工作流。

Step 3：获取 API 信息

查看当前工作流对应的：

text

appId
inputParams 参数
参数限制
积分消耗

Step 4：创建任务

调用：

http

POST https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/create

请求结构：

json

{
  "appId": "APP_ID",
  "inputParams": {
    "参数名": "参数值"
  }
}

创建任务成功后，保存接口返回的任务 ID。

Step 5：查询任务

使用创建任务后获得的任务 ID 调用：

http

GET https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/getTask

查询任务当前执行状态。

重点读取：

text

data.status

状态：

text

0 = 排队中
1 = 生成中
2 = 成功
3 = 取消
4 = 失败
5 = 超时

如果：

text

status = 0 或 1

则等待一段时间后继续查询。

如果：

text

status = 2

则任务执行成功，可以读取生成结果。

如果：

text

status = 3、4 或 5

则任务已经结束，无需继续查询。

Step 6：获取结果

当：

text

data.status = 2

时，从：

text

data.files

中获取工作流生成结果。

如需查看调用记录，可前往调用日志。

完整调用逻辑

text

创建 API Token
        ↓
选择工作流
        ↓
获取 appId
        ↓
按照工作流要求准备 inputParams
        ↓
POST /create
        ↓
获得 taskId
        ↓
GET /getTask
        ↓
读取 data.status
        ↓
┌───────────────┬───────────────┐
│               │               │
0 排队中        1 生成中        2 成功
│               │               │
└───────┬───────┘               ↓
        │                    获取 files
        ↓
等待后继续查询

3 取消 / 4 失败 / 5 超时
        ↓
     停止查询

常见问题

不同工作流需要使用不同的创建接口吗？

不需要。

所有工作流统一使用同一个任务创建接口，通过 appId 确定需要执行的工作流。

appId 是什么？

appId 是每个工作流对应的唯一标识。

调用不同工作流时，只需要更换对应的 appId。

inputParams 是什么？

inputParams 用于传递当前工作流所需要的输入参数。

例如：

json

{
  "appId": "APP_ID",
  "inputParams": {
    "prompt": "YOUR_PROMPT",
    "time": 5
  }
}

不同工作流的 inputParams 参数不同，请以对应工作流页面显示的 API 参数为准。

为什么创建任务后没有直接返回图片或视频？

ComfyUI 工作流采用异步任务方式执行。

创建任务后会先返回任务 ID，需要再通过任务查询接口查询任务状态。

任务状态一般会经历：

text

排队中
  ↓
生成中
  ↓
成功

当：

text

data.status = 2

时，表示任务执行成功，此时可以从 data.files 获取最终生成结果。

`ok: true` 是否表示工作流执行成功？

不是。

ok: true 表示本次 API 查询请求正常。

例如：

json

{
  "ok": true,
  "data": {
    "status": 0
  }
}

表示查询接口调用成功，但工作流任务当前仍处于排队状态。

工作流是否真正执行成功，需要判断：

text

data.status

只有：

text

data.status = 2

才表示任务执行成功。

为什么 `startTime` 是 null？

当任务仍处于排队中、尚未真正开始执行时：

json

"startTime": null

属于正常情况。

任务开始执行后，该字段才会返回对应的开始时间。

为什么 `endTime` 是 null？

任务尚未结束时：

json

"endTime": null

属于正常情况。

任务成功、失败、取消或超时结束后，该字段才可能返回对应的结束时间。

为什么 `executionDuration` 是 null？

任务尚未开始或者尚未完成时，执行耗时可能暂时无法计算，因此：

json

"executionDuration": null

属于正常情况。

为什么 `files` 是 null？

如果任务仍处于：

text

0 = 排队中

或：

text

1 = 生成中

通常还没有最终生成结果，因此：

json

"files": null

属于正常情况。

当：

text

data.status = 2

后，再读取 data.files 获取生成结果。

查询接口需要一直调用吗？

不需要无限查询。

只需要在：

text

status = 0

或：

text

status = 1

时继续查询。

当状态变为：

text

2 = 成功
3 = 取消
4 = 失败
5 = 超时

后，任务已经结束，应停止轮询。

查询任务应该多久调用一次？

建议设置合理的查询间隔，不要无间隔连续请求。

具体轮询间隔可根据工作流平均运行时间以及业务需求自行设置。

如何获取积分？

智算云扉平台积分通过 算力点兑换 获得。

页面	地址
API 令牌	创建 / 管理 API 令牌
工作流	查看工作流
调用日志	查看调用日志

文件上传接口

用于上传工作流 API 所需的图片、视频或音频文件。

请求地址

POST

text

https://studio.aigate.cc/api/comfyui/open/v1/comfyui_workflow/uploadFile

参数	类型	必填	说明
Authorization	string	是	API 访问令牌，格式：`Bearer <Token>`

Query 参数

参数	类型	必填	说明
media_type	string	是	文件类型，支持 `image`、`video`、`audio`

media_type 可选值：

text

image  图片
video  视频
audio  音频

Body 参数

请求格式为 multipart/form-data。

参数	类型	必填	说明
file	file	是	需要上传的文件

文件大小限制

文件类型	最大大小
图片 `image`	5 MB
视频 `video`	20 MB
音频 `audio`	20 MB

注意

上传文件请勿超过对应大小限制，否则可能导致上传失败。

cURL 示例

bash

curl --location --request POST \
'https://studio.aigate.cc/comfyui/open/v1/comfyui_workflow/uploadFile?media_type=image' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form 'file=@"/path/to/file.png"'

其中：

YOUR_API_TOKEN：替换为你的 API 令牌
media_type：填写 image、video 或 audio
file：需要上传的本地文件

上传成功后，可将接口返回的文件信息用于工作流对应的文件输入参数。

工作流 API 文档说明 ​

调用流程 ​

1. 创建 API 令牌 ​

2. 选择工作流 ​

3. 创建工作流任务 ​

Header 参数 ​

Body 参数 ​

请求结构 ​

请求示例 ​

cURL 示例 ​

4. 查询工作流任务 ​

Header ​

查询返回示例 ​

返回字段说明 ​

status 状态码说明 ​

状态判断 ​

5. 获取生成结果 ​

6. 支持的文件格式 ​

图片 ​

视频 ​

音频 ​

7. 积分与计费 ​

8. 调用日志 ​

API 地址汇总 ​

快速开始 ​

Step 1：创建 API Token ​

Step 2：选择工作流 ​

Step 3：获取 API 信息 ​

Step 4：创建任务 ​

Step 5：查询任务 ​

Step 6：获取结果 ​

完整调用逻辑 ​

常见问题 ​

不同工作流需要使用不同的创建接口吗？ ​

appId 是什么？ ​

inputParams 是什么？ ​

为什么创建任务后没有直接返回图片或视频？ ​

ok: true 是否表示工作流执行成功？ ​

为什么 startTime 是 null？ ​

为什么 endTime 是 null？ ​

为什么 executionDuration 是 null？ ​

为什么 files 是 null？ ​

查询接口需要一直调用吗？ ​

查询任务应该多久调用一次？ ​

如何获取积分？ ​

相关页面 ​

文件上传接口 ​

请求地址 ​

Header 参数 ​

Query 参数 ​

Body 参数 ​

文件大小限制 ​

cURL 示例 ​

工作流 API 文档说明

调用流程

1. 创建 API 令牌

2. 选择工作流

3. 创建工作流任务

Header 参数

Body 参数

请求结构

请求示例

cURL 示例

4. 查询工作流任务

Header

查询返回示例

返回字段说明

status 状态码说明

状态判断

5. 获取生成结果

6. 支持的文件格式

图片

视频

音频

7. 积分与计费

8. 调用日志

API 地址汇总

快速开始

Step 1：创建 API Token

Step 2：选择工作流

Step 3：获取 API 信息

Step 4：创建任务

Step 5：查询任务

Step 6：获取结果

完整调用逻辑

常见问题

不同工作流需要使用不同的创建接口吗？

appId 是什么？

inputParams 是什么？

为什么创建任务后没有直接返回图片或视频？

`ok: true` 是否表示工作流执行成功？

为什么 `startTime` 是 null？

为什么 `endTime` 是 null？

为什么 `executionDuration` 是 null？

为什么 `files` 是 null？

查询接口需要一直调用吗？

查询任务应该多久调用一次？

如何获取积分？

相关页面

文件上传接口

请求地址

Header 参数

Query 参数

Body 参数

文件大小限制

cURL 示例