Workflow API 接口说明#
Workflow接口提供了快速生图或视频的功能，支持多种调用模式和参数类型。接口信息#
接口地址: POST /api/v1/generate/{workflow}
Content-Type: application/json
调用模式#
接口支持同步、异步两种调用模式，通过mode参数指定：1. 同步模式 (mode=sync)#
特点: 接口会一直处于阻塞状态，直到生成任务完成、终止或失败
2. 异步模式#
2.1 WebSocket模式 (mode=async_websocket)#
特点: 接口调用立即返回，任务进度通过WebSocket推送
返回: 任务提交信息，包含WebSocket连接地址
2.2 回调模式 (mode=async_callback)#
特点: 接口调用立即返回，任务进度通过HTTP回调推送
回调: 服务器会向指定URL发送POST请求，携带任务进度信息
请求参数#
URL参数#
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|
| workflow | string | 是 | 工作流标识符 | text-to-image |
| mode | string | 否 | 调用模式，默认为sync | sync/async_websocket/async_callback |
| callback | string | 条件必填 | 回调URL，mode=async_callback时必填 | https://your-domain.com/callback |
| costLookup | boolean | 否 | 默认值为false，如果指定为true，用于查询参数对应的积分消耗值，接口不实际执行生成任务 | false |
请求体参数#
请求体为JSON格式，参数根据具体工作流配置动态确定。常见参数类型包括：基础参数类型#
| 参数类型 | 说明 | 示例值 |
|---|
| string | 字符串类型 | "hello world" |
| number | 数字类型 | 42 |
| string array | 字符串数组 | "item1,item2,item3" |
| number array | 数字数组 | "1,2,3,4" |
特殊参数类型#
| 参数类型 | 说明 | 示例值 |
|---|
| image upload | 图片上传 | 支持URL和Base64两种格式 |
⚠️ 注意：
仅支持 jpg 和 png 格式的图片作为参数传递给 workflow。
响应格式#
成功响应#
{
"code": "Success",
"data": {
"websocket": "wss://crowdcomputed.com/user/20250415193856584384",
"spend": 100,
"balance": 3900,
"taskId": "582079535692914438",
"status": "finished",
"outputs": [...]
}
}
成功响应字段#
| 字段名 | 类型 | 说明 | 示例 |
|---|
| code | string | 响应状态码 | "Success" |
| data | object | 响应数据对象 | 包含任务相关信息 |
data对象字段#
| 字段名 | 类型 | 说明 | 示例 |
|---|
| websocket | string | WebSocket连接地址，mode=async_websocket时返回 | "wss://crowdcomputed.com/user/20250415193856584384" |
| spend | number | 本次任务消耗的积分/点数 | 100 |
| balance | number | 用户剩余积分/点数 | 3900 |
| taskId | string | 任务唯一标识符 | "582079535692914438" |
| status | string | 任务状态 | "waiting"/"generating"/"finished"/"failed" |
| outputs | array | 输出结果数组，任务完成时包含 | 包含多个输出对象 |
失败响应#
{
"code": "Failed",
"message": "In async callback mode, the callback parameter is not allowed to be null"
}
失败响应字段#
| 字段名 | 类型 | 说明 | 示例 |
|---|
| code | string | 响应状态码 | "Failed" |
| message | string | 错误消息 | "invalid params" |
说明：
当任务执行失败时，系统会将任务消耗的积分退还给用户。
任务进度信息格式#
无论是WebSocket推送还是HTTP回调，任务进度信息的JSON格式都是一致的：{
"taskId": "582079535692914438",
"status": "finished",
"outputs": [
{
"outputId": "582079535692914438_0001",
"status": "finished",
"reSchedule": false,
"urls": [ "dev/images/task/582079535692914438/output/20250829220046913955.jpg"
],
"estimateMs": 15000,
"queueOrder": 0,
"startTime": 1756504840,
"endTime": 1756504847
}
]
}
顶层字段#
| 字段名 | 类型 | 说明 | 可能的值 |
|---|
| taskId | string | 任务唯一标识符 | 数字字符串 |
| status | string | 任务整体状态 | waiting/generating/finished/failed |
| outputs | array | 输出结果数组 | 包含多个输出对象 |
outputs数组中的字段#
| 字段名 | 类型 | 说明 | 示例 |
|---|
| outputId | string | 输出项唯一标识符 | "582079535692914438_0001" |
| status | string | 输出项状态 | waiting/generating/finished/failed |
| reSchedule | boolean | 标识任务是否因节点故障或超时而发生重新调度。当计算节点突然失效或任务执行超时时，系统会将任务重新分配到其他可用节点继续执行。重调度可能会延长任务的总体执行时间。任务重分配只会执行一次，如再次超时，任务会失败。 | true/false |
| urls | array | 生成文件的URL数组 | ["dev/images/task/xxx/output/xxx.jpg"] |
| estimateMs | number | 预估耗时（毫秒）- 在任务开始的时候一次性预估 | 15000 |
| queueOrder | number | 队列顺序 | 0 |
| startTime | number | 开始时间戳 | 1756504840 |
| endTime | number | 结束时间戳 | 1756504847 |
状态说明#
| 状态值 | 说明 | 出现时机 |
|---|
| waiting | 任务等待中 | 任务已创建，等待执行 |
| generating | 任务生成中 | 任务正在执行生成过程 |
| finished | 任务已完成 | 任务成功完成，包含输出结果 |
| failed | 任务失败 | 任务执行过程中出现错误 |
使用示例#
1. 同步模式示例#
2. 异步回调模式示例#
3. 参数积分消耗查询示例#
4. 图片上传参数示例#
{
"prompt": "a cat sitting on a chair",
"uploadImage": {
"type": "url",
"url": "https://example.com/cat.jpg"
}
}
{
"prompt": "a cat sitting on a chair",
"uploadImage": {
"type": "base64",
"base64Content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}
}
Modified at 2025-11-28 04:27:39
