Skip to main content
Android
iOS
Web

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:

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:

ParameterCategoryRequired/OptionalDescription
tokenstringRequiredA writer or admin SDK token. You can obtain a token using one of the following methods:
  • Get an SDK token for testing purposes from Agora Console. See Get security credentials for your whiteboard project.
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
  • regionstringRequiredSpecifies 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.
  • eu: Frankfurt, Europe, which provides services to Europe.
  • Request Body

    The following parameters are required in the URL:

    ParameterCategoryRequired/OptionalDescription
    resourcestringRequiredThe URL of the file you want to convert.
    typestringRequiredThe conversion type:
  • dynamic: Dynamic-file conversion, converting the file to web pages.
  • static: Static-file conversion, converting the file to images.
  • previewbooleanOptionalWhether to generate a preview of the generated files:
  • true: Generate a preview.
  • false: Do not generate a preview.
  • scalenumberOptionalThe 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.
    outputFormatstringOptionalThe format of the generated image:
  • png
  • jpg
  • jpeg
  • The default value is png. This parameter only takes effect when type is set to static.
    webhookEndpointstringOptionalThe 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.
    webhookRetrynumberOptionalThe number of retries the system attempts when the Webhook callback fails. The default value is 3, and the maximum is 10.
    imageCompressionLevelnumberOptionalThe 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.
  • This parameter only takes effect when 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


    _13
    POST /v5/projector/tasks
    _13
    Host: api.netless.link
    _13
    region: cn-hz
    _13
    Content-Type: application/json
    _13
    token: NETLESSSDK_YWs9QxxxxxxMjRi
    _13
    _13
    {
    _13
    "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
    _13
    "type": dynamic
    _13
    "preview": true,
    _13
    "webhookEndpoint": "https://example.com/agoracallback",
    _13
    "webhookRetry": 1
    _13
    }

    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:


    _4
    {
    _4
    "uuid": "2fd2dxxxxx367e",
    _4
    "status": "Waiting"
    _4
    }

    Description of parameters in the response:

    ParameterCategoryDescription
    uuidstringThe task UUID, which is the unique identifier of the file-conversion task.
    statusstringThe 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:

    ParameterCategoryRequired/OptionalDescription
    tokenstringRequiredThe Task token. You can obtain a token using one of the following methods:
  • Call the RESTful API. See Generate a task token.
  • Write code on your app server. See Generate a token from your app server.
  • regionstringRequiredSpecifies 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:

    ParameterCategoryRequired/OptionalDescription
    uuidstringRequiredThe 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


    _5
    GET /v5/projector/tasks/2fxxxxxx367e
    _5
    Host: api.netless.link
    _5
    region: cn-hz
    _5
    Content-Type: application/json
    _5
    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.

    The following is a response example for a successful request:


    _20
    {
    _20
    "uuid": "2fdxxxx7e",
    _20
    "status": "Finished",
    _20
    "type": "dynamic",
    _20
    "convertedPercentage": 100,
    _20
    "prefix": "https://xxxx.com/dynamicConvert"
    _20
    "pageCount": 10,
    _20
    "previews": {
    _20
    "1": "https://xxxx.xx.xx/1.png",
    _20
    "2": "https://xxxx.xx.xx/2.png",
    _20
    ...
    _20
    }
    _20
    "note": "https://xxx.xx.xx/note.json",
    _20
    "images": {
    _20
    "1": "https://xxxx.xx.xx/1.xxx",
    _20
    "2": "https://xxxx.xx.xx/2.xxx",
    _20
    },
    _20
    "errorCode": "20xxxxx",
    _20
    "errorMessage": "xxx",
    _20
    }

    Description of parameters in the response:

    ParameterCategoryDescription
    uuidstringThe task UUID, which is the unique identifier of the file-conversion task.
    statusstringThe status of the conversion task:
  • Waiting: Conversion is waiting to start.
  • Converting: Conversion is in progress.
  • Finished: Conversion has finished.
  • Fail: Conversion failed.
  • typestringThe conversion type:
  • dynamic: Dynamic-file conversion, converting the file to web pages.
  • static: Static-file conversion, converting the file to images.
  • convertedPercentagenumberThe progress of the conversion expressed as a percentage.
    prefixstringThe prefix of the address of the generated file.
    pageCountnumberThe number of file pages. This value is not available when the conversion task fails.
    previewsobjectThe 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.
    notestringNotes and comments extracted from the file. This parameter contains only the pages that have notes or comments.
    imagesobjectThe 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.
    errorCodestringThe error code. This parameter is only returned when the conversion task fails. For the details of all the possible error codes, see error code.
    errorMessagestringThe error message corresponding to the error code, describing the cause of the error. This parameter is only returned when the conversion task fails.

    Note: The API for querying the progress of file conversion tasks only supports tasks created within the past seven days. To prevent the loss of status information or results, Agora recommends that you additionally store task information after completing or failing a conversion, or receive notifications of task status changes through webhook callbacks.

    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:

    ParameterCategoryRequired/OptionalDescription
    tokenstringRequiredA writer or admin SDK token. You can obtain a token using one of the following methods:
  • Get an SDK token for testing purposes from Agora Console. See Get security credentials for your whiteboard project.
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
  • regionstringRequiredSpecifies 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.
  • eu: Frankfurt, Europe, which provides services to Europe.
  • Request example


    _5
    GET /v5/projector/tasks
    _5
    Host: api.netless.link
    _5
    region: cn-hz
    _5
    Content-Type: application/json
    _5
    token: NETLESSSDK_YWs9QxxxxxxMjRi

    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:


    _9
    [
    _9
    {
    _9
    taskId: 'xxx',
    _9
    status: 1
    _9
    },
    _9
    {
    _9
    ....
    _9
    }
    _9
    ]

    Description of parameters in the response:

    ParameterCategoryDescription
    taskIdstringThe task UUID, which is the unique identifier of the file-conversion task.
    statusnumberThe 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:

    ParameterCategoryRequired/OptionalDescription
    tokenstringRequiredAn SDK token. You can obtain a token using one of the following methods:
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
  • regionstringRequiredSpecifies 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:

    ParameterCategoryRequired/OptionalDescription
    uuidstringRequiredThe 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


    _5
    DELETE /v5/projector/tasks/2fxxxxxx367e
    _5
    Host: api.netless.link
    _5
    region: cn-hz
    _5
    Content-Type: application/json
    _5
    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.

    The following is a response example for a successful request:


    _4
    {
    _4
    taskId: 'xxx',
    _4
    success: true
    _4
    }

    Description of parameters in the response:

    ParameterCategoryDescription
    taskIdstringThe task UUID, which is the unique identifier of the file-conversion task.
    successbooleanWhether 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:

    ParameterCategoryRequired/OptionalDescription
    tokenstringRequiredA writer or admin SDK token. You can obtain a token using one of the following methods::
  • Get an SDK token for testing purposes from Agora Console. See Get security credentials for your whiteboard project.
  • Call the RESTful API. See Generate an SDK token.
  • Write code on your app server. See Generate a token from your app server.
  • regionstringRequiredSpecifies 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.

    ParameterCategoryRequired/OptionalDescription
    prioritystringRequiredSet 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:

    ParameterCategoryRequired/OptionalDescription
    uuidstringRequiredThe 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


    _9
    PUT /v5/projector/tasks/2fxxxxxx367e
    _9
    Host: api.netless.link
    _9
    region: cn-hz
    _9
    Content-Type: application/json
    _9
    token: NETLESSSDK_YWs9QxxxxxxMjRi
    _9
    _9
    {
    _9
    "priority": highest
    _9
    }

    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:


    _4
    {
    _4
    uuid: 'xxx',
    _4
    success: true
    _4
    }

    Description of parameters in the response:

    ParameterCategoryDescription
    uuidstringThe task UUID, which is the unique identifier of the file-conversion task.
    successbooleanWhether 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:


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

    Description of parameters in the response:

    ParameterCategoryDescription
    codenumberThe error code. When the task succeeds, the value is 0. For the details of all the possible error codes, see error code.
    messagestringThe error message corresponding to the error code, describing the cause of the error.
    taskIdstringThe task UUID, which is the unique identifier of the file-conversion task.
    taskTypestringThe type of the conversion task. Currently, only dynamic_conversion is available.
    prefixUrlstringThe prefix of the address of the generated file.
    pageCountnumberThe number of file pages. This parameter is not available when the conversion task fails.
    previewsobjectThe 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.
    notestringNotes and comments extracted from the file. This parameter contains only the pages that have notes or comments.
    imagesobjectThe 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.
    noticeTimestampnumberThe 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 codeError messageSolution
    2010201unsupported file formatUpload the PPT or PPTX files.
    2010202dynamic conversion only support pptxUpload the PPTX files.
    2010203the number of tasks exceeds limitCall 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.
    2010605task not foundCheck whether the task UUID is correct.
    2011201task timeoutCheck the network connection or compress the file size.
    2010606team not foundCheck whether the token is correct. In Agora Console, check whether the data center is correctly configured and docs-to-web is enabled.
    2010607modify priority for running task is not allowedEnsure that the target task is in the waiting list.
    2011301task not foundCheck whether the task UUID is correct.
    2030100download from OSS file failedCheck whether the target file has been uploaded.
    2030101unzip file failed, unsupported file in PPTCheck whether the file can be opened with PowerPoint.
    2030102can't find media file from unzip PPTCheck 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.
    2030200read xml file failedCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2030201formula resolve failed, please check animation of PPTExamine or delete the animation in the PPT, and retry.
    2030202unsupported formula type, please check animation of PPTExamine or delete the animation in the PPT, and retry.
    2040005task timeoutAbnormal or oversized images are used in the uploaded file; contact support@agora.io
    2050099unknown errorCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2050100unsupported file typeUpload the PPT or PPTX files.
    2050101file download failedCheck the network connection.
    2050102file is emptyOpen the file locally, and check whether the file is empty.
    2050107file url encode failedCheck whether the URL address of the file is correct.
    2050201init presentation parser failedCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2050299unknown parsing errorCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2050401generate preview failedCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2060402fonts in the rules that are not providedContact support@agora.io
    2090304upload file to custom storage failedCheck whether the storage configuration is correct.
    2090305not supported storage providerCheck whether the link to the cloud storage service provider is correct, or consider changing the service provider.
    2110099unknown errorCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2110100unsupported file typeUpload files in a format that static conversion supports (PPT/PPTX/DOC/DOCX/PDF).
    2110101download file failedCheck whether the address of the file is valid.
    2110102file is emptyOpen the file locally, and check whether the file is empty.
    2110107file url encode failedCheck whether the URL address of the file is correct.
    2110108get file extension failedCheck whether the extension of the uploaded file has been modified intentionally, but the content of the file remains in an unsupported format.
    2110201init presentation parser failedCheck whether the uploaded file is edited with software other than MS PowerPoint.
    2110202init word parser failedCheck whether the uploaded file is edited with software other than MS Word.
    2120201file is emptyOpen the file locally, and check whether the file is empty.
    2120301download file failedCheck whether the address of the file is valid.
    vundefined