Skip to main content

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:

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:

ParameterData typeRequired/OptionalDescription
tokenstringRequiredA 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.
  • 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.
  • gb-lon: London, England, 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.

    ParameterData typeRequired/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 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.
    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 or jpeg
  • webp
  • The default value is png.
    This parameter only takes effect when type is set to static.
    packbooleanOptionalWhether 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


    _13
    POST /v5/services/conversion/tasks
    _13
    Host: api.netless.link
    _13
    region: us-sv
    _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": "static",
    _13
    "preview": true,
    _13
    "scale": 1,
    _13
    "outputFormat": "jpg"
    _13
    }

    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:


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

    Description of parameters in the response:

    ParameterData typeDescription
    uuidstringThe Task UUID, which is the unique identifier of the file-conversion task.
    typestringThe conversion type:
  • dynamic: Dynamic-file conversion, converting the file to web pages.
  • static: Static-file conversion, converting the file to images.
  • statusstringThe 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:

    ParameterData typeRequired/OptionalDescription
    tokenstringRequiredA 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.
  • 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.
  • gb-lon: London, England, 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:

    ParameterData typeRequired/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.

    Query Parameters

    You need to pass in the following query parameters:

    ParameterData typeRequired/OptionalDescription
    typestringRequiredThe conversion type:
  • dynamic: Dynamic-file conversion, converting the file to web pages.
  • static: Static-file conversion, converting the file to images.
  • Request example


    _5
    GET /v5/services/conversion/tasks/2fxxxxxx367e?type=static
    _5
    Host: api.netless.link
    _5
    region: us-sv
    _5
    Content-Type: application/json
    _5
    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:


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

    Description of parameters in the response:

    ParameterData typeDescription
    uuidstringThe Task UUID, which is the unique identifier of the file-conversion task.
    typestringThe conversion type:
  • dynamic: Dynamic-file conversion, converting the file to web pages.
  • static: Static-file conversion, converting the file to images.
  • statusstringThe status of the conversion task:
  • Waiting: Conversion is waiting to start.
  • Converting: Conversion is in progress.
  • Finished: Conversion has finished.
  • Fail: Conversion failed.
  • failedReasonstringThe reason the conversion task failed. This field is returned only when status is Fail.
    progressobjectThe 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.

    Page Content