Deprecated file conversion

Interactive Whiteboard released a new version of file conversion service on July 27, 2022, that greatly improves conversion speed, content parsing, and stability. The new version also adds the ability to integrate with third-party whiteboard SDKs. Agora strongly recommends you use the new version of file conversion. See File conversion RESTful API reference.

The file-conversion feature provided by Interactive Whiteboard can convert PPT, PPTX, DOC, DOCX, and PDF files into static images or dynamic HTML web pages. The generated images and web pages can be presented on the whiteboard. See Old File Conversion Overview.

Before calling the RESTful API for file conversion, ensure that:

You have enabled Docs to Picture or Docs to Web and configured storage settings in Agora Console. See Enable whiteboard server-side features.
You have generated a URL address for the file you want to convert, and the address is publicly accessible.

Start file conversion (POST)

Call this API to start a file-conversion task.

Prototype

Method: POST
Access point: https://api.netless.link/v5/services/conversion/tasks

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	A SDK token with the `writer` or `admin` role. To get a SDK Token, you can: Get a test-purpose SDK token from Agora Console. See Get security credentials for your whiteboard project. Call the RESTful API. See Generate an SDK Token.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request Body

The following parameters are required in the URL.

Parameter	Data type	Required/Optional	Description
`resource`	string	Required	The URL of the file you want to convert.
`type`	string	Required	The conversion type: `dynamic`: Dynamic-file conversion, converting the file to web pages. `static`: Static-file conversion, converting the file to images.
`preview`	boolean	Optional	Whether to generate a preview of the generated web pages: `true`: Generate a preview. `false`: Do not generate a preview. This parameter only takes effect when `type` is set to `dynamic`. Note that generating a preview can take a long time.
`scale`	number	Optional	The scale factor of an image. The range is [0.1,3.0], and the default value is `1.2`. The higher the value, the clearer the generated image. This parameter only takes effect when `type` is set to `static`.
`outputFormat`	string	Optional	The format of the generated image: `png` `jpg` or `jpeg` `webp` The default value is `png.` This parameter only takes effect when `type` is set to `static`.
`pack`	boolean	Optional	Whether to generate a resource package when performing a static document conversion task: `true`: Generate a resource package. When this parameter is set as `true`, the Agora server packages all converted images into a `{uuid}.zip` file and uploads it to your specified storage path. `false`: (Default) Do not generate a resource package. This parameter only takes effect when `type` is set to `static`.

Request example

POST /v5/services/conversion/tasks
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9QxxxxxxMjRi
 
{
    "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
    "type": "static",
    "preview": true,
    "scale": 1,
    "outputFormat": "jpg"
}

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 201, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 201,
"body":
{
    "uuid": "2fd2dxxxxx367e",
    "type": "static",
    "status": "Waiting"
}

Description of parameters in the response:

Parameter	Data type	Description
`uuid`	string	The Task UUID, which is the unique identifier of the file-conversion task.
`type`	string	The conversion type: `dynamic`: Dynamic-file conversion, converting the file to web pages. `static`: Static-file conversion, converting the file to images.
`status`	string	The status of the conversion task: `Waiting`: Conversion is waiting to start. `Converting`: Conversion is in progress. `Finished`: Conversion has finished. `Fail`: Conversion failed.

If the status code is not 201, the request fails. The response body includes a message field that describes the reason for the failure.

Query file conversion progress (GET)

Call this API to query the progress of a file-conversion task.

Prototype

Method: GET
Access point: https://api.netless.link/v5/services/conversion/tasks/{uuid}

Request header

Pass in the following parameters in the request header:

Parameter	Data type	Required/Optional	Description
`token`	string	Required	A Task Token. To get one, you can: Call the RESTful API. See Generate a Task Token. Use code samples. See Generate a token from your app server.
`region`	string	Required	Specifies a data center to process the request: `us-sv`: Silicon Valley, US, which provides services to North America and South America. `sg`: Singapore, which provides services to Singapore, East Asia, and Southeast Asia. `in-mum`: Mumbai, India, which provides services to India. `eu`: Frankfurt, Europe, which provides services to Europe. `cn-hz`: Hangzhou, China, which provides services to the areas not covered by other data centers.

Request Path

The following parameters are required in the URL:

Parameter	Data type	Required/Optional	Description
`uuid`	string	Required	The Task UUID, which is the unique identifier of the file-conversion task. You can get it by calling the RESTful API to start a file conversion.

Query Parameters

You need to pass in the following query parameters:

Parameter	Data type	Required/Optional	Description
`type`	string	Required	The conversion type: `dynamic`: Dynamic-file conversion, converting the file to web pages. `static`: Static-file conversion, converting the file to images.

Request example

GET /v5/services/conversion/tasks/2fxxxxxx367e?type=static
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWsxxxxxM2MjRi

HTTP response

For details about all possible response status codes, see the status code table.

If the status code is 200, the request is successful. The response returns the status code and corresponding parameters.

The following is a response example for a successful request:

"status": 200,
"body":
{
    "uuid": "2fdxxxx7e",
    "type": "static",
    "status": "Finished",
    "progress": {
        "totalPageSize": 2,
        "convertedPageSize": 2,
        "convertedPercentage": 100,
        "convertedFileList": [
            {
                "width": 1333,
                "height": 750,
                "conversionFileUrl": "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticConvert/2fdxxxxx67e/1.jpeg"
            },
            {
                "width": 1333,
                "height": 750,
                "conversionFileUrl": "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticConvert/2fdxxxxx67e/2.jpeg"
            }
        ]
    }
}

Description of parameters in the response:

Parameter	Data type	Description
`uuid`	string	The Task UUID, which is the unique identifier of the file-conversion task.
`type`	string	The conversion type: `dynamic`: Dynamic-file conversion, converting the file to web pages. `static`: Static-file conversion, converting the file to images.
`status`	string	The status of the conversion task: `Waiting`: Conversion is waiting to start. `Converting`: Conversion is in progress. `Finished`: Conversion has finished. `Fail`: Conversion failed.
`failedReason`	string	The reason the conversion task failed. This field is returned only when `status` is `Fail`.
`progress`	object	The progress of the conversion task, which includes the following fields: `totalPageSize`: Number. Indicates the number of pages of the source file. `convertedPageSize`: Number. Indicates the number of pages that have been converted. `convertedPercentage`: Number. Indicates the conversion progress in percentage form. `convertedFileList`: Array. Contains a list of generated files, each containing the following parameters: `width`: Number. Indicates the width of the image or PPT slide in pixels. `height`: Number. Indicates the height of the image or PPT slide in pixels. `conversionFileUrl`: String. Indicates the URL of the generated file. `preview`: String. Indicates the address of the preview. This field is returned only when `preview` is set to `true` and `type` is set to `dynamic` in the request body when starting file conversion. `currentStep`: String. Indicates the current step of a dynamic-file conversion task: `Extracting`: The server is extracting resources. `Packaging`: The server is packaging resources. `GeneratingPreview`: The server is generating the preview. `MediaTranscode`: The server is transcoding. `currentStep` is returned only when `type` is set to `dynamic` in the request body when starting file conversion.

If the status code is not 200, the request fails. The response body includes a message field that describes the reason for the failure.