Async Task APIs

❖ Feature Description

Create, query, download, and cancel asynchronous file processing tasks.

Create an async task

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

❖ Request Parameters

x-api-key*

Authentication credential sent in the header: x-api-key. Sign in to the Dashboard API management page to view the API Access Key for the current deployment.

Path Parameters

sourcestring*

Source file type.

targetstring*

Target file type or operation.

Body Parameters multipart/form-data

fileFile

Choose FileNo file selected

Primary source file for single-file operations.

filesFile[]

Choose Files

No file selected

Source files for PDF merge.

insertFileFile

Choose FileNo file selected

PDF file to insert.

imageFileFile

Choose FileNo file selected

Image watermark file.

iccFileFile

Choose FileNo file selected

ICC profile for PDF standards conversion.

htmlFileFile

Choose FileNo file selected

HTML file for PDF generation.

templateFileFile

Choose FileNo file selected

HTML template for PDF generation.

dataFileFile

Choose FileNo file selected

JSON data file for template rendering.

requeststring

PDF request JSON string. See Async PDF Task request parameters for details.

optionsstring

Conversion options JSON string. See Conversion Options for details.

passwordstring

Source file password.

❖ Response Properties

Field	Type	Description
code	Integer	Business status code.
msg	String	Response message.
data	Object	Response data.
data.taskId	String	Task ID. Returned after task creation and used to query, download, or cancel the task.
data.status	String	Task status. Common values are pending, processing, completed, failed, and canceled.
data.failureCode	String	Error code when the task fails or is canceled; usually empty while processing or after success.
data.failureReason	String	Reason when the task fails or is canceled; usually empty while processing or after success.

🔗Request Example

curl --request POST \
  --url http://localhost:8080/api/v1/task/pdf/docx \
  --header 'x-api-key: YOUR API-KEY' \
  --form [email protected]

✓Response Example

200 OK

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

Query a task

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

❖ Request Parameters

x-api-key*

Authentication credential sent in the header: x-api-key. Sign in to the Dashboard API management page to view the API Access Key for the current deployment.

Path Parameters

idstring*

Task ID.

❖ Response Properties

Field	Type	Description
code	Integer	Business status code.
msg	String	Response message.
data	Object	Response data.
data.taskId	String	Task ID. Returned after task creation and used to query, download, or cancel the task.
data.status	String	Task status. Common values are pending, processing, completed, failed, and canceled.
data.failureCode	String	Error code when the task fails or is canceled; usually empty while processing or after success.
data.failureReason	String	Reason when the task fails or is canceled; usually empty while processing or after success.

🔗Request Example

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

✓Response Example

200 OK

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

Download task result

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

❖ Request Parameters

x-api-key*

Authentication credential sent in the header: x-api-key. Sign in to the Dashboard API management page to view the API Access Key for the current deployment.

Path Parameters

idstring*

Task ID.

🔗Request Example

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

✓Response Example

200 OK

Processed successfully. Returns the result file stream.

Cancel a task

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

❖ Request Parameters

x-api-key*

Authentication credential sent in the header: x-api-key. Sign in to the Dashboard API management page to view the API Access Key for the current deployment.

Path Parameters

idstring*

Task ID.

❖ Response Properties

Field	Type	Description
code	Integer	Business status code.
msg	String	Response message.
data	Object	Response data.
data.taskId	String	Task ID. Returned after task creation and used to query, download, or cancel the task.
data.status	String	Task status. Common values are pending, processing, completed, failed, and canceled.
data.failureCode	String	Error code when the task fails or is canceled; usually empty while processing or after success.
data.failureReason	String	Reason when the task fails or is canceled; usually empty while processing or after success.

🔗Request Example

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

✓Response Example

200 OK

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<string>",
    "status": "canceled",
    "failureCode": "TASK_CANCELED",
    "failureReason": "task canceled by client"
  }
}

Need to stop an async task?

When an asynchronous task has been submitted, but you no longer wish to continue processing it, you can initiate a "Close Task" request to actively terminate the task.

Go to Close Task