接口详情

1. 创建任务

接口
POST /v1/openapi/tasks
请求头
Content-Type: application/json
请求体

{
  "remark": "备注信息（可选）",
  "appId": "应用ID（必填）",
  "inputs": [
    {
      "name": "参数名",
      "value": "参数值"
    }
  ]
}

成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "任务ID",
    "current": 1 //任务排队的当前位置
  },
  "requestId": "请求唯一标识"
}

💡 说明

• appId 必须有效，否则任务创建失败。

• inputs 支持多参数输入，每个参数需明确 name 和 value。

2. 取消任务

接口
DELETE /v1/openapi/tasks/:id
路径参数

• id: 任务ID（必填）
  请求体
  {}（空JSON）
  成功响应

{
  "code": 0,
  "msg": "success",
  "requestId": "请求唯一标识"
}

⚠️ 注意
仅能取消未完成的任务，已失败/成功的任务无法取消。

3. 上传资源（图片/音频/视频）

接口
POST /v1/openapi/files
请求头
Content-Type: multipart/form-data
请求体

• file: 文件二进制流（必填）

• filename: 文件名（如 comfylink.jpg）

• type: MIME类型（如 image/png）
  成功响应

{
  "code": 0,
  "msg": "file upload success",
  "data": {
    "path": "资源访问URL（如 https://api.comfylink.com/v1/files/...）"
  },
  "requestId": "请求唯一标识"
}

📌 使用场景
上传的资源可用于其他接口（如任务输入），返回的 path 需保存备用。

4. 任务状态实时通知（WebSocket）

接口
GET /v1/openapi/ws
推送的消息格式

🔄 机制说明

• 连接建立后，服务端主动给Client推送任务状态变更。

• 需保持长连接，断开后需重新建立。

🕒 4.1 排队等待阶段（pending）

{
  "type": "pending",
  "taskId": "667d3a99c8e1118ef12be2b9",
  "data": {
    "message": "等待中...",
    "current": 1,   // 当前队列位置（前方有1个任务）
    "success": false,
    "process": 0    // 初始进度为0
  }
}

触发时机：任务进入处理队列时推送

⚙️ 4.2 开始执行阶段（progress）

{
  "type": "progress",
  "taskId": "667d3a99c8e1118ef12be2b9",
  "data": {
    "message": "执行中...",
    "current": 0,   // 0表示已离开队列开始执行
    "success": false,
    "process": 0    // 进度初始化
  }
}

关键特征：current归零表示资源锁定

🔄 4.3 进度更新阶段（progress动态）

// 进度更新至30%
{
  "type": "progress",
  "taskId": "667d3a99c8e1118ef12be2b9",
  "data": {
    "message": "执行中...",
    "current": 0,
    "success": false,
    "process": 30   // 进度百分比线性递增
  }
}

推送规则：关键节点完成时触发（如：转码完成30%）

✅ 4.4 执行成功阶段（finished）

{
  "type": "finished",
  "taskId": "667d3a99c8e1118ef12be2b9",
  "data": {
    "message": "完成",
    "current": 0,
    "success": true,  // 明确标识任务成功
    "process": 100,   // 进度强制置为100%
    "costTime": 60000,// 任务运行时长为60000毫秒
  }
}

附加说明：实际业务中常携带输出结果（如图片URL）

❌ 4.5 执行失败阶段（error）

{
  "type": "error",
  "taskId": "667d3a99c8e1118ef12be2b9",
  "data": {
    "message": "ControlNet节点权重超限（需0.1-2.0，实际2.5）", // 具体错误定位
    "current": 0,
    "success": false,
    "process": 45    // 失败时进度冻结
  }
}

错误处理：需包含可溯源的故障节点信息

5. 查询任务状态

接口
GET /v1/openapi/tasks/:id
路径参数

• id: 任务ID（必填）
  请求体
  {}（空JSON）

响应结构定义

data对象结构

outputs数组元素结构

任务成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "finished",
    "outputs": [
      {
        "id": "24",
        "type": "image",
        "result": [
          "https://cdn.com/result/20250606/6842dd00d3113dfe15ce6bf5/8b08ec37a15886ad3603c21d6d855b07dd6861a530d455081fbd0a2e2a8040b9.png"
        ]
      }
    ],
    "message": "finished"
  },
  "requestId": "c98b1786-b394-45be-aeb8-abe24abd0838"
}

任务失败

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "failed",
    "outputs": [],
    "message": "ControlNet节点权重超限（需0.1-2.0，实际2.5）"
  },
  "requestId": "5f4d83e0-7c1a-48d2-b6e9-1a2b3c4d5e6f"
}

用户取消

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "canceled",
    "outputs": [],
    "message": "用户取消"
  },
  "requestId": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210"
}

调用示例汇总

# 1. 创建任务
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Client-Id: YOUR_UUID" \
     -H "Content-Type: application/json" \
     -X POST https://api.comfylink.com/v1/openapi/tasks \
     -d '{"remark":"","appId":"YOUR_APPID","inputs":[{"name":"6:text","value":"test ..."}]}'

# 2. 取消任务
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Client-Id: YOUR_UUID" \
     -H "Content-Type: application/json" \
     -X DELETE https://api.comfylink.com/v1/openapi/tasks/创建任务返回的任务ID \
     -d '{}'

# 3. 上传文件
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Client-Id: YOUR_UUID" \
     -X POST https://api.comfylink.com/v1/openapi/files \
     -F "file=@./comfylink.jpg;filename=comfylink.jpg;type=image/jpg"

# 4. 查询任务状态
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Client-Id: YOUR_UUID" \
     -H "Content-Type: application/json" \
     -X GET https://api.comfylink.com/v1/openapi/tasks/创建任务返回的任务ID \
     -d '{}'

# 5. WebSocket建立长连接
wscat -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Client-Id: YOUR_UUID" \
     -c wss://api.comfylink.com/v1/openapi/ws

错误处理

所有接口均返回 requestId，用于问题追踪。