Three APIs and two tokens are required to call the conversion service. The following is a description of the usage process:
Use sdktoken to call initiate document conversion api, initiate document conversion task and get taskuuid
Use sdktoken and taskuuid to call Generate Task Token api to get tasktoken
Use tasktoken and taskuuid to call query task conversion progress api to query task progress
Due to the excessive permissions of sdktoken, we do not recommend exposing the sdktoken to the front end. It is recommended to use sdktoken to check out the tasktoken and pass the tasktoken to the front end for use. Only users with tasktoken can query the corresponding task progress.
Initiating the conversion and checking out the tasktoken suggestions are all performed on the backend
POST
initiate document conversion Before calling the following api, please make sure you have activated the
document to webpage
ordocument to image
service on the console platform
https://shunt-api.netless.link/v5/services/conversion/tasks
When the type in the request is dynamic, the document-to-webpage (dynamic document conversion) service will be called. When the type is static, the document-to-image (static document conversion) service will be called. Please make sure that the corresponding service is enabled when calling, otherwise the api will be Report an error
Key | Required or not | Type | Remarks |
---|---|---|---|
token | required |
string |
SDK Token (read-only permission above) |
Key | Required or not | Type | Remarks |
---|---|---|---|
resource | required |
string |
Conversion task source file url |
type | required |
string |
Conversion task type, enumeration: dynamic, static |
preview | optional |
boolean |
Whether to generate a preview image, the default is false |
scale | optional |
number |
Image zoom ratio, the value ranges from 0.1 to 3, the default is 1.2 |
outputFormat | optional |
string |
The output image format, the default is png, and the optional parameter is png/jpg/jpeg/webp |
Note: Only dynamic document conversion supports the preview image function, that is, when type == "dynamic", it takes a long time to generate the preview image at the same time, please choose carefully
Note: Only static document conversion supports zoom function, that is, when type == "static", the default value is not passed. This value will change the size of the generated image
Note: Only static document conversion supports custom output format, that is, when type == "static", it will not be transferred as png, and both jpg and jpeg output formats will be jpeg
{
"uuid": "2fa009xxxxxxxxxxxxxxxxxca93da2ad", // task uuid
"type": "dynamic", // task type, enumeration: dynamic, static
"status": "Waiting" // task status, enumeration: Waiting, Converting, Finished, Fail
}
GET
Query task conversion progress https://shunt-api.netless.link/v5/services/conversion/tasks/:uuid
Key | Required or not | Type | Remarks |
---|---|---|---|
token | required |
string |
Task Token |
Key | Required | Type | Remarks |
---|---|---|---|
uuid | required |
string |
Task uuid |
Key | Required or not | Type | Remarks |
---|---|---|---|
type | required |
string |
Conversion task type, enumeration: dynamic, static |
{
"uuid": "2fa009xxxxxxxxxxxxxxxxxca93da2ad", // task uuid
"type": "dynamic", // task type, enumeration: dynamic, static
"status": "Waiting", // task status, enumeration: Waiting, Converting, Finished, Fail
"failedReason": "", // the reason after the task failed
"progress": {
"totalPageSize": 10, // Total number of pages of converted document
"convertedPageSize": 3, // The number of pages that have been converted
"convertedPercentage": 30, // Conversion progress percentage
"convertedFileList": [{ // Conversion result list
"width": 1024, // current page span
"height": 960, // current page height
"conversionFileUrl": "xxxx://xxxx.xxx.xx/xxxx.xxx", // conversion result file address
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx", // Preview image address, this field will only exist when the body parameter preview is true and the type is dynamic when the conversion is initiated
},{...}],
"currentStep": "Extracting" // The current conversion task step, this field is only available when type == dynamic
}
}
Since there are many dynamic conversion steps, we have added the current step field to indicate the progress of the task. The enumerable values are "Extracting" (resource extraction) | "Packaging" (resource packaging) | "GeneratingPreview" (generating preview) | "MediaTranscode" (Media Transcode)