异步任务接口

创建异步任务使用与同步处理一致的路径格式。任务查询、下载和取消接口保持基于任务 ID 的生命周期路径。

创建任务

项目	值
请求地址	POST http://localhost:8080/api/v1/task/{source}/{target}
认证	x-api-key: your_api_key_here
请求类型	multipart/form-data

Multipart 字段

参数名	类型	说明	是否必填
file	File	单文件操作的主文件。	合并和内联数据生成场景除外
files	File[]	PDF 合并使用的多个文件。	合并时必填
insertFile	File	task/pdf/insert-from-pdf 的待插入 PDF 文件。	按需
imageFile	File	task/pdf/watermark/add 的水印图片。	否
iccFile	File	task/pdf/pdfa 的 ICC profile 文件。	PDF 规范转换时必填
htmlFile	File	task/pdf/generation/html-to-pdf 的 HTML 文件。	使用 request.html 或 request.htmlUrl 时可不传
templateFile	File	task/pdf/generation/template-to-pdf 的 HTML 模板文件。	使用 request.template 时可不传
dataFile	File	模板渲染使用的 JSON 数据文件。	否
request	String	PDF 工具或生成 PDF 参数 JSON 字符串。	否
options	String	转档参数 JSON 字符串。	否
password	String	源文件密码。	否

curl 示例

curl -X POST "http://localhost:8080/api/v1/task/pdf/docx" \
  -H "x-api-key: your_api_key_here" \
  -F "[email protected]" \
  -F 'options={"pageRanges":"1-3"}'

返回示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7fdc1fb6-1f4d-4b5c-88d6-4b4c4c1e8f44",
    "status": "pending"
  }
}

查询任务

curl -X GET "http://localhost:8080/api/v1/task/7fdc1fb6-1f4d-4b5c-88d6-4b4c4c1e8f44" \
  -H "x-api-key: your_api_key_here"

下载结果

curl -L "http://localhost:8080/api/v1/task/7fdc1fb6-1f4d-4b5c-88d6-4b4c4c1e8f44/download" \
  -H "x-api-key: your_api_key_here" \
  -o result.bin

任务成功后下载接口返回结果文件流。若任务存在但尚未完成，返回 409 和 TASK_NOT_READY。

取消任务

curl -X POST "http://localhost:8080/api/v1/task/7fdc1fb6-1f4d-4b5c-88d6-4b4c4c1e8f44/cancel" \
  -H "x-api-key: your_api_key_here"