File conversion

Interactive Whiteboard supports file conversion from PPT, PPTX, DOC, DOCX, and PDF files into static images, as well as from PPT/PPTX files into dynamic HTML web pages. The generated images and web pages can be presented on the whiteboard. See File Conversion Overview.

Prerequisites

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

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

Start file conversion

Call this API to start a file-conversion task.

Prototype

• Method: POST
• Access point: https://api.netless.link/v5/projector/tasks

Request header

Pass in the following parameters in the request header:

Request Body

You can specify the following parameters:

Request example

curl --request POST \
  --url https://api.netless.link/v5/projector/tasks \
  --header 'region: <string>' \
  --header 'token: <string>' \
  --data '
{
  "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
  "type": "dynamic",
  "preview": true,
  "webhookEndpoint": "https://example.com/agoracallback",
  "webhookRetry": 3,
  "imageCompressionLevel": 0
}'

HTTP response

For the details of all the 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.

Response example

{
  "uuid": "2fd2dxxxxx367e",
  "type": "dynamic",
  "status": "Waiting"
}

Response parameters

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 the progress of a file-conversion task

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

Prototype

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

Request header

Pass in the following parameters in the request header:

Request Path

The following parameters are required in the URL:

Request example

curl --request GET \
  --url https://api.netless.link/v5/projector/tasks/:uuid \
  --header 'region: <string>' \
  --header 'token: <string>'

HTTP response

For the details of all the 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.

Response examples:

• Dynamic conversion completed

  {
    "uuid": "dc11fe9e1xxxxxx7cd7ca3670a",
    "type": "dynamic",
    "status": "Finished",
    "convertedPercentage": 100,
    "pageCount": 2,
    "previews": {
      "1": "https://xxx/flat/dynamicConvert/xxx/1.png",
      "2": "https://xxx/flat/dynamicConvertxxx/2.png"
    },
    "note": "https://xxx/jsonOutput/note.json",
    "prefix": "https://xxx/flat/dynamicConvert",
    "zip": "https://xxx.com/flat/dynamicConvert/xxx.zip",
    "resources": [
      "https://xxx/jsonOutput/note.json",
      "https://xxx/flat/dynamicConvert/xxx/1.png",
      "https://xxx/flat/dynamicConvert/xxx/2.png"
    ]
  }

• Static conversion completed

  {
    "uuid": "b5ec7c26ebxxxx217b8e2fb4dc5",
    "type": "static",
    "status": "Finished",
    "convertedPercentage": 100,
    "pageCount": 2,
    "images": {
      "1": {
        "width": 1440,
        "height": 810,
        "url": "https:/xxx/flat/staticConvert/xxxx/1.png"
      },
      "2": {
        "width": 1440,
        "height": 810,
        "url": "https://xxx/flat/staticConvert/xxxx/2.png"
      }
    },
    "prefix": "https://xxx/flat/"
  }

• Task in progress

  {
    "uuid": "b5ec7c26exxxxb8e2fb4dc5",
    "type": "static",
    "status": "Converting",
    "convertedPercentage": 0,
    "prefix": "https://xxx/flat/"
  }

Response parameters:

Query to-be-converted tasks

Call this API to list all tasks that are waiting to be converted.

Prototype

• Method: GET
• Access point: https://api.netless.link/v5/projector/tasks

Request header

Pass in the following parameters in the request header:

Request example

curl --request GET \
  --url https://api.netless.link/v5/projector/tasks \
  --header 'region: <string>' \
  --header 'token: <string>'

HTTP response

For the details of all the 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.

Response example

[
  {
    "taskId": "xxx",
    "status": 1
  },
  {
    "taskId": "xxx",
    "status": 0
  }
]

Response parameters

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

Cancel conversion task

Call this API to cancel a specified conversion task.

Prototype

• Method: DELETE
• Access point: https://api.netless.link/v5/projector/tasks/{uuid}

Request header

Pass in the following parameters in the request header:

Request Path

The following parameters are required in the URL:

Request example

DELETE /v5/projector/tasks/2fxxxxxx367e
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWsxxxxxM2MjRi

HTTP response

For the details of all the 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.

Response example

{
  "taskId": "xxx",
  "success": true
}

Response parameters

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

Set task priority

Call this API to move the specified conversion task in the waiting list to the front or the back of the task queue.

Prototype

• Method: PUT
• Access point: https://api.netless.link/v5/projector/tasks/{uuid}/priority

Request header

Pass in the following parameters in the request header:

Request Body

You can specify the following parameters:

Request Path

The following parameters are required in the URL:

Request example

PUT /v5/projector/tasks/2fxxxxxx367e
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWs9QxxxxxxMjRi

{
  "priority": "highest"
}

HTTP response

For the details of all the 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.

Response example

{
  "taskId": "xxx",
  "success": true
}

Response parameters

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

Webhook callback

Call this callback to receive reports on the progress and operating status of file-conversion tasks from the server. You can call this callback by passing in the relevant parameters in the request body when launching a file-conversion task.

HTTP response

For the details of all the 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.

Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "da4c1b9ae************92af4ef22b8",
    "taskType": "dynamic_conversion",
    "prefixUrl": "https://xxxx.com/dynamicConvert",
    "pageCount": 10,
    "previews": {
      "1": "https://xxxx.xx.xx/1.png",
      "2": "https://xxxx.xx.xx/2.png"
    },
    "note": "https://xxx.xx.xx/note.json",
    "images": {
      "1": "https://xxxx.xx.xx/1.xxx",
      "2": "https://xxxx.xx.xx/2.xxx"
    },
    "noticeTimestamp": 1231369699739
  }
}

Response parameters

Error code

The following are details and solutions for all the possible error codes that could occur when calling the file conversion RESTful API.