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.
This page applies to the new version of file conversion. For the main differences between the old and new versions, see Version comparison. If you use the old file conversion, see Old File Conversion RESTful API Reference.
Before calling the RESTful API for file conversion, ensure that you have done the following:
- 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:
| Parameter | Category | Required/Optional | Description |
|---|---|---|---|
token | string | Required | A writer or admin SDK token. You can obtain a token using one of the following methods: |
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.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 | Category | 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 files:true: Generate a preview.false: Do not generate a preview. |
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:pngjpgjpegpng. This parameter only takes effect when type is set to static. |
webhookEndpoint | string | Optional | The address of the Webhook callback, generally the app server address, is used to receive information sent by the server, such as the progress of tasks. See webhook callback. |
webhookRetry | number | Optional | The number of retries the system attempts when the Webhook callback fails. The default value is 3, and the maximum is 10. |
imageCompressionLevel | number | Optional | The compression level of the output image. You can only pass in the following values: 0: (Default) Output the original image.1: The maximum number of colors used in the output image is limited to 256.2: The maximum number of colors used in the output image is limited to 192.3: The maximum number of colors used in the output image is limited to 128.4: The maximum number of colors used in the output image is limited to 64.type is set to dynamic.Usually, the size of the output image can be compressed to up to 10% of its original without significantly reducing the image quality. Compressing the size of images can improve the first loading time of PPT files after conversion in poor network environment. |
Request example
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
uuid | string | The task UUID, which is the unique identifier of the file-conversion task. |
status | string | The status of the file-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 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:
| Parameter | Category | Required/Optional | Description |
|---|---|---|---|
token | string | Required | The Task token. You can obtain a token using one of the following methods: |
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.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 | Category | 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. |
Request example
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
uuid | string | The task UUID, which is the unique identifier of the file-conversion task. |
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. |
type | string | The conversion type:dynamic: Dynamic-file conversion, converting the file to web pages.static: Static-file conversion, converting the file to images. |
convertedPercentage | number | The progress of the conversion expressed as a percentage. |
prefix | string | The prefix of the address of the generated file. |
pageCount | number | The number of file pages. This value is not available when the conversion task fails. |
previews | object | The address of the preview. Each page corresponds to a preview address. This parameter is only returned when preview is set to true and type is set to dynamic in the request body when starting the file conversion. This value is not available when the conversion task fails. |
note | string | Notes and comments extracted from the file. This parameter contains only the pages that have notes or comments. |
images | object | The address of the static conversion results. Each page corresponds to an image. This parameter is only returned when type is set to static in the request body when starting the file conversion. This value is not available when the conversion task fails. |
errorCode | string | The error code. This parameter is only returned when the conversion task fails. For the details of all the possible error codes, see error code. |
errorMessage | string | The error message corresponding to the error code, describing the cause of the error. This parameter is only returned when the conversion task fails. |
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:
| Parameter | Category | Required/Optional | Description |
|---|---|---|---|
token | string | Required | A writer or admin SDK token. You can obtain a token using one of the following methods: |
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.cn-hz: Hangzhou, China, which provides services to the areas not covered by other data centers. |
Request example
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
taskId | string | The task UUID, which is the unique identifier of the file-conversion task. |
status | number | The status of the conversion task:1: In progress. 0: Waiting to be converted. |
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:
| Parameter | Category | Required/Optional | Description |
|---|---|---|---|
token | string | Required | An SDK token. You can obtain a token using one of the following methods: |
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.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 | Category | 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. |
Request example
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
taskId | string | The task UUID, which is the unique identifier of the file-conversion task. |
success | boolean | Whether canceling the conversion task is successful: true: Task cancellation is successful.false: Task cancellation is unsuccessful. |
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:
| Parameter | Category | Required/Optional | Description |
|---|---|---|---|
token | string | Required | A writer or admin SDK token. You can obtain a token using one of the following methods:: |
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.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 | Category | Required/Optional | Description |
|---|---|---|---|
priority | string | Required | Set task priority: highest: Move to the front of the task queue. lowest: Move to the back of the task queue. |
Request Path
The following parameters are required in the URL:
| Parameter | Category | 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. |
Request example
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
uuid | string | The task UUID, which is the unique identifier of the file-conversion task. |
success | boolean | Whether setting the priority is successful: true: Setting the priority succeeded. false: Setting the priority failed. |
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.
The Webhook callback could be repeated multiple times. To ensure that the app server processes identical responses in the same manner, you need to apply idempotent processing.
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.
The following is a response example for a successful request:
Description of parameters in the response:
| Parameter | Category | Description |
|---|---|---|
code | number | The error code. When the task succeeds, the value is 0. For the details of all the possible error codes, see error code. |
message | string | The error message corresponding to the error code, describing the cause of the error. |
taskId | string | The task UUID, which is the unique identifier of the file-conversion task. |
taskType | string | The type of the conversion task. Currently, only dynamic_conversion is available. |
prefixUrl | string | The prefix of the address of the generated file. |
pageCount | number | The number of file pages. This parameter is not available when the conversion task fails. |
previews | object | The address of the preview. Each page corresponds to a preview address. This parameter is only returned when preview is set to true in the request body when starting the file conversion. This parameter is not available when the conversion task fails. |
note | string | Notes and comments extracted from the file. This parameter contains only the pages that have notes or comments. |
images | object | The address of the static conversion results. Each page corresponds to a picture. This parameter is only returned when type is set to static in the request body when starting the file conversion. This value is not available when the conversion task fails. |
noticeTimestamp | number | The time when you receive the Webhook callback. |
Error code
The following are details and solutions for all the possible error codes that could occur when calling the file conversion RESTful API.
| Error code | Error message | Solution |
|---|---|---|
| 2010201 | unsupported file format | Upload the PPT or PPTX files. |
| 2010202 | dynamic conversion only support pptx | Upload the PPTX files. |
| 2010203 | the number of tasks exceeds limit | Call Cancel conversion task to reduce the number of tasks in the queue, or wait for existing conversion tasks to complete before starting a conversion task. |
| 2010605 | task not found | Check whether the task UUID is correct. |
| 2011201 | task timeout | Check the network connection or compress the file size. |
| 2010606 | team not found | Check whether the token is correct. In Agora Console, check whether the data center is correctly configured and docs-to-web is enabled. |
| 2010607 | modify priority for running task is not allowed | Ensure that the target task is in the waiting list. |
| 2011301 | task not found | Check whether the task UUID is correct. |
| 2030100 | download from OSS file failed | Check whether the target file has been uploaded. |
| 2030101 | unzip file failed, unsupported file in PPT | Check whether the file can be opened with PowerPoint. |
| 2030102 | can't find media file from unzip PPT | Check whether the path of the media files in the PPT is correct and whether an external link is used. On the user's computer, move the PPT file to other folders and check whether the media files in the PPT file are playable. |
| 2030200 | read xml file failed | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2030201 | formula resolve failed, please check animation of PPT | Examine or delete the animation in the PPT, and retry. |
| 2030202 | unsupported formula type, please check animation of PPT | Examine or delete the animation in the PPT, and retry. |
| 2040005 | task timeout | Abnormal or oversized images are used in the uploaded file; contact support@agora.io |
| 2050099 | unknown error | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2050100 | unsupported file type | Upload the PPT or PPTX files. |
| 2050101 | file download failed | Check the network connection. |
| 2050102 | file is empty | Open the file locally, and check whether the file is empty. |
| 2050107 | file url encode failed | Check whether the URL address of the file is correct. |
| 2050201 | init presentation parser failed | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2050299 | unknown parsing error | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2050401 | generate preview failed | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2060402 | fonts in the rules that are not provided | Contact support@agora.io |
| 2090304 | upload file to custom storage failed | Check whether the storage configuration is correct. |
| 2090305 | not supported storage provider | Check whether the link to the cloud storage service provider is correct, or consider changing the service provider. |
| 2110099 | unknown error | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2110100 | unsupported file type | Upload files in a format that static conversion supports (PPT/PPTX/DOC/DOCX/PDF). |
| 2110101 | download file failed | Check whether the address of the file is valid. |
| 2110102 | file is empty | Open the file locally, and check whether the file is empty. |
| 2110107 | file url encode failed | Check whether the URL address of the file is correct. |
| 2110108 | get file extension failed | Check whether the extension of the uploaded file has been modified intentionally, but the content of the file remains in an unsupported format. |
| 2110201 | init presentation parser failed | Check whether the uploaded file is edited with software other than MS PowerPoint. |
| 2110202 | init word parser failed | Check whether the uploaded file is edited with software other than MS Word. |
| 2120201 | file is empty | Open the file locally, and check whether the file is empty. |
| 2120301 | download file failed | Check whether the address of the file is valid. |