异步任务接口

❖ 功能说明

创建、查询、下载和取消异步文件处理任务。

创建异步任务

POSThttp://localhost:8080/api/v1/task/pdf/docx

❖ 请求参数 (Parameters)

x-api-key*

在 Header 中发送的 x-api-key 认证凭证，请登录 Dashboard 的 API 管理页面查看当前部署的 API Access Key。

Path Parameters

sourcestring*

源文件类型。

targetstring*

目标文件类型或处理操作。

Body Parameters multipart/form-data

fileFile

选择文件未选择文件

单文件操作的主文件。

filesFile[]

选择文件（可多选）

未选择文件

PDF 合并使用的多个文件。

insertFileFile

选择文件未选择文件

插入 PDF 使用的待插入文件。

imageFileFile

选择文件未选择文件

图片水印文件。

iccFileFile

选择文件未选择文件

PDF 规范转换使用的 ICC profile。

htmlFileFile

选择文件未选择文件

生成 PDF 使用的 HTML 文件。

templateFileFile

选择文件未选择文件

生成 PDF 使用的 HTML 模板。

dataFileFile

选择文件未选择文件

模板渲染使用的 JSON 数据文件。

requeststring

PDF 功能参数 JSON 字符串。详情请参阅 PDF 异步任务请求参数。

optionsstring

转档参数 JSON 字符串。详情请参阅转档公共参数。

passwordstring

源文件密码。

❖ 响应属性说明

字段	类型	说明
code	Integer	业务状态码。
msg	String	响应消息。
data	Object	响应数据。
data.taskId	String	任务 ID。创建任务后返回，用于查询、下载或取消任务。
data.status	String	任务状态。常见值包括 pending（等待中）、processing（处理中）、completed（已完成）、failed（失败）和 canceled（已取消）。
data.failureCode	String	任务失败或取消时的错误码；任务处理中或成功时通常为空。
data.failureReason	String	任务失败或取消时的原因；任务处理中或成功时通常为空。

🔗请求示例 (Request)

curl --request POST \
  --url http://localhost:8080/api/v1/task/pdf/docx \
  --header 'x-api-key: YOUR API-KEY' \
  --form file=@sample.pdf

✓响应示例 (Response)

200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<string>",
    "status": "pending",
    "failureCode": "<string>",
    "failureReason": "<string>"
  }
}

查询任务

GEThttp://localhost:8080/api/v1/task/{id}

❖ 请求参数 (Parameters)

x-api-key*

在 Header 中发送的 x-api-key 认证凭证，请登录 Dashboard 的 API 管理页面查看当前部署的 API Access Key。

Path Parameters

idstring*

任务 ID。

❖ 响应属性说明

字段	类型	说明
code	Integer	业务状态码。
msg	String	响应消息。
data	Object	响应数据。
data.taskId	String	任务 ID。创建任务后返回，用于查询、下载或取消任务。
data.status	String	任务状态。常见值包括 pending（等待中）、processing（处理中）、completed（已完成）、failed（失败）和 canceled（已取消）。
data.failureCode	String	任务失败或取消时的错误码；任务处理中或成功时通常为空。
data.failureReason	String	任务失败或取消时的原因；任务处理中或成功时通常为空。

🔗请求示例 (Request)

curl --request GET \
  --url "http://localhost:8080/api/v1/task/{id}" \
  --header 'x-api-key: YOUR API-KEY'

✓响应示例 (Response)

200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<string>",
    "status": "pending",
    "failureCode": "<string>",
    "failureReason": "<string>"
  }
}

下载任务结果

GEThttp://localhost:8080/api/v1/task/{id}/download

❖ 请求参数 (Parameters)

x-api-key*

在 Header 中发送的 x-api-key 认证凭证，请登录 Dashboard 的 API 管理页面查看当前部署的 API Access Key。

Path Parameters

idstring*

任务 ID。

🔗请求示例 (Request)

curl --request GET \
  --url "http://localhost:8080/api/v1/task/{id}/download" \
  --header 'x-api-key: YOUR API-KEY'

✓响应示例 (Response)

200 OK

处理成功，返回结果文件流。

取消任务

POSThttp://localhost:8080/api/v1/task/{id}/cancel

❖ 请求参数 (Parameters)

x-api-key*

在 Header 中发送的 x-api-key 认证凭证，请登录 Dashboard 的 API 管理页面查看当前部署的 API Access Key。

Path Parameters

idstring*

任务 ID。

❖ 响应属性说明

字段	类型	说明
code	Integer	业务状态码。
msg	String	响应消息。
data	Object	响应数据。
data.taskId	String	任务 ID。创建任务后返回，用于查询、下载或取消任务。
data.status	String	任务状态。常见值包括 pending（等待中）、processing（处理中）、completed（已完成）、failed（失败）和 canceled（已取消）。
data.failureCode	String	任务失败或取消时的错误码；任务处理中或成功时通常为空。
data.failureReason	String	任务失败或取消时的原因；任务处理中或成功时通常为空。

🔗请求示例 (Request)

curl --request POST \
  --url http://localhost:8080/api/v1/task/{id}/cancel \
  --header 'x-api-key: YOUR API-KEY'

✓响应示例 (Response)

200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<string>",
    "status": "canceled",
    "failureCode": "TASK_CANCELED",
    "failureReason": "任务已由客户端取消"
  }
}

需要主动终止异步任务？

当异步任务已提交，但您不希望继续处理时，可以发起"关闭任务"请求主动终止该任务。

前往【关闭任务】