# 发起文档转换 (/zh-CN/api-reference/api-ref/whiteboard/restful/start-file-conversion)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

发起一个文档转换任务。

- OpenAPI: /openapi/whiteboard/restful-wb.zh-CN.yaml
- Operation ID: post-v5-projector-tasks
- Method: POST
- Path: /v5/projector/tasks
- Endpoint: https://api.netless.link/v5/projector/tasks

## Servers

- https://api.netless.link

:::warning[注意]
调用文档转换 API 前，请确保：

- 已在[声网控制台](https://console.shengwang.cn/)开启**文档转图片**或**文档转网页**服务并添加存储配置。详见[开启互动白板配套服务](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#开启互动白板配套服务)。

- 已为待转换的文档生成一个公网可访问的 URL 地址。
:::

## Parameters

- `region` (header, required, string) - 指定处理该请求的数据中心，取值如下：

- `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。

- `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。

- `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。

- `in-mum`：印度孟买，服务区覆盖印度。

- `eu`：欧洲（法兰克福），服务区覆盖欧洲。
  - Allowed: `cn-hz` | `us-sv` | `sg` | `in-mum` | `eu`
- `token` (header, required, string) - SDK Token，可以通过以下方式获取：

- 在声网控制台生成用于测试的 SDK Token，详见[获取互动白板项目的安全密钥](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。

- 调用服务端 RESTful API， 详见[生成 SDK Token](generate-sdk-token)。

- 在 App 服务端用代码生成，详见[在 App 服务端生成 Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/generate-token#在-app-服务端生成-token)。

## Request body

- `resource` (string, required) - 待转换的源文件 URL。
- `type` (string) - 转换任务类型，取值如下：

- `dynamic`：动态文档转换，即文档转网页。

- `static`：静态文档转换，即文档转图片。
  - Default: `dynamic`
- `preview` (boolean) - 是否需要生成预览图：

- `true`：是。

- `false`：否。
该参数仅在 `type` 设为 `dynamic` 时生效。
- `scale` (number) - 图片缩放比例。数值越大，图片越清晰。该参数仅在 `type` 设为 `static` 时生效。
  - Default: `1.2`
  - Range: `[0.1, 3]`
- `outputFormat` (string) - 输出图片格式，取值如下：

- `png`：PNG 格式。

- `jpg`：JPG 格式。

-  `jpeg`：JPEG 格式。

-  `qpdf`：QPDF 格式。仅 PDF 文件（以 `%PDF` 开头的文件）支持转换为 QPDF 格式。你可以使用 [@netless-app-pdfjs](https://github.com/netless-io/netless-app-pdfjs) 插件展示到基于 Fastboard SDK 的互动白板 App 中。
 该参数仅在 `type` 设为 `static` 时生效。
  - Default: `png`
- `webhookEndpoint` (string) - Webhook 回调地址，一般为 app 服务端地址，用于接收服务端发送的转换任务进度等信息。传入该参数即可激活 Webhook 回调，接收来自服务端的文档转换进度和运行状态信息。Webhook 配置方式和签名验证详见[接收文档转换 Webhook 事件](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/extend-whiteboard/conversion-webhook)。

> [!CAUTION]
> Webhook 回调有一定概率重复回调，为保证 app 服务端在接到相同响应时的处理方式保持一致，需要做好幂等处理。
- `webhookRetry` (number) - Webhook 回调失败时的重试次数。
  - Default: `3`
  - Maximum: `10`
- `imageCompressionLevel` (number) - 动态转换输出图片的压缩等级，仅能传入以下值：

- `0`：（默认）输出原图。

- `1`：输出图片使用的最大颜色数量限制为 256。

- `2`：输出图片使用的最大颜色数量限制为 192。

- `3`：输出图片使用的最大颜色数量限制为 128。

- `4`：输出图片使用的最大颜色数量限制为 64。
该参数仅在 `type` 设为 `dynamic` 时生效。

> [!NOTE]
> 通常，在保证画质不受明显影响的前提下，输出图片的体积最高可以压缩至原图的 10%。压缩图片体积可在弱网环境下改善转换后 PPT 的首次加载时间。
  - Default: `0`
- `buildSpa` (boolean) - 是否在转换完成后构建一个可独立渲染的单页应用程序 (SPA, Single-page Application)：

- `true`：（默认）构建 SPA 文件。文件为 HTML 格式，其中包含渲染 PPT 的所有资源，可用于单页预览，但服务器需要耗时（约 3 至 300 秒）下载所需资源和编译文件。

- `false`：不构建 SPA 文件。
  - Default: `true`

### Request body example

```json
{
  "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
  "type": "dynamic",
  "preview": true,
  "webhookEndpoint": "https://example.com/agoracallback",
  "webhookRetry": 3,
  "imageCompressionLevel": 0
}
```

## Responses

### 201

若返回的状态码为 `201` 则表示请求成功。响应 Body 中包含本次请求的结果。

若返回的状态码不为 `201` 则表示请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/whiteboard/fastboard-sdk/reference/response-code)了解可能的原因。

- `uuid` (string) - 转换任务的 UUID，即转换任务的唯一标识符。
- `type` (string) - 转换任务类型，取值如下：

- `dynamic`：动态文档转换，即文档转网页。

- `static`：静态文档转换，即文档转图片。
- `status` (string) - 转换任务的状态：

- `Waiting`：等待转换。

- `Converting`：转换中。

- `Finished`：已完成。

- `Fail`：失败。

## Response examples

### 201

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