# Legacy file conversion API (/en/api-reference/api-ref/whiteboard/file-conversion-deprecated)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
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](file-conversion.md).
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](../file-conversion-overview-deprecated.mdx).
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](https://console.agora.io/v2). See [Enable whiteboard server-side features](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#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) [#start-file-conversion-post]
Call this API to start a file-conversion task.
### Prototype [#prototype]
* Method: `POST`
* Access point: `https://api.netless.link/v5/services/conversion/tasks`
### Request header [#request-header]
Pass in the following parameters in the request header:
| Parameter | Data type | Required/Optional | Description |
| :-------- | :-------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Required | An SDK token with the `writer` or `admin` role.
To get an SDK Token, you can:- Get a test-purpose SDK token from Agora Console. See [Get security credentials for your whiteboard project](/en/realtime-media/whiteboard/build/set-up-and-build-your-first-app/enable-whiteboard.md#get-security-credentials-for-your-whiteboard-project).
- Call the RESTful API. See [Generate an SDK Token](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md#generate-an-sdk-token-post).
|
| `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 [#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 [#request-example]
```bash
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 [#http-response]
For details about all possible response status codes, see the [status code table](overview#status-codes).
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:**
```json
"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) [#query-file-conversion-progress-get]
Call this API to query the progress of a file-conversion task.
### Prototype [#prototype-1]
* Method: `GET`
* Access point: `https://api.netless.link/v5/services/conversion/tasks/{uuid}`
### Request header [#request-header-1]
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](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-rest.md#generate-a-task-token-post).
- Use code samples. See [Generate a token from your app server](/en/realtime-media/whiteboard/build/authenticate-users/generate-token-app-server.mdx).
|
| `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 [#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 [#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 [#request-example-1]
```bash
GET /v5/services/conversion/tasks/2fxxxxxx367e?type=static
Host: api.netless.link
region: us-sv
Content-Type: application/json
token: NETLESSSDK_YWsxxxxxM2MjRi
```
### HTTP response [#http-response-1]
For details about all possible response status codes, see the [status code table](overview#status-codes).
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:**
```json
"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.