Async Task APIs

Async task creation uses the same path pattern as synchronous processing. Task query, download, and cancel APIs keep the task-id based lifecycle path.

Create a Task

Item	Value
Request URL	POST http://localhost:8080/api/v1/task/{source}/{target}
Authentication	x-api-key: your_api_key_here
Request Type	multipart/form-data

Multipart Fields

Field	Type	Description	Required
file	File	Primary source file for single-file operations.	Required except merge and generation-from-inline-data
files	File[]	Source files for PDF merge.	Required for merge
insertFile	File	PDF file to insert for task/pdf/insert-from-pdf.	Required for insert-from-pdf
imageFile	File	Watermark image for task/pdf/watermark/add.	Optional
iccFile	File	ICC profile for task/pdf/pdfa.	Required for PDF standards conversion
htmlFile	File	HTML file for task/pdf/generation/html-to-pdf.	Optional when request.html or request.htmlUrl is used
templateFile	File	HTML template file for task/pdf/generation/template-to-pdf.	Optional when request.template is used
dataFile	File	JSON data file for template rendering.	Optional
request	String	PDF tool or PDF generation parameter JSON string.	Optional
options	String	Conversion options JSON string.	Optional
password	String	Source file password.	Optional

curl Example

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"}'

Response

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

Query a Task

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

Download the Result

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

The result download API returns a binary file stream after the task succeeds. If the task exists but is not ready, it returns 409 with TASK_NOT_READY.

Cancel a Task

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