# 发起文档转换 (/zh-CN/api-reference/api-ref/whiteboard/restful/start-legacy-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-services-conversion-tasks - Method: POST - Path: /v5/services/conversion/tasks - Endpoint: https://api.netless.link/v5/services/conversion/tasks ## Servers - https://api.netless.link ## Parameters - `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)。 - `region` (header, required, string) - 指定处理该请求的数据中心,取值如下: - `cn-hz`:中国杭州,服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 - `us-sv`:美国硅谷,服务区覆盖北美洲、南美洲。 - `sg`:新加坡,服务区覆盖新加坡、东亚、东南亚。 - `in-mum`:印度孟买,服务区覆盖印度。 - `eu`:欧洲(法兰克福),服务区覆盖欧洲。 - Allowed: `cn-hz` | `us-sv` | `sg` | `in-mum` | `eu` ## Request body - `resource` (string, required) - 待转换的源文件 URL。 - `type` (string, required) - 转换任务类型,取值如下: - `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` - `pack` (boolean) - 进行静态文档转换时,是否生成资源包: - `true`:生成资源包。该参数设为 `true` 时,声网服务端会将所有转换后的图片打包成 `{uuid}.zip` 文件,并上传到你指定的存储路径中。 - `false`:(默认)不生成资源包。 > [!NOTE] > 该参数仅在 `type` 设为 `static` 时生效。当 `type` 设为 `dynamic` 时,声网服务端会自动生成 `{uuid}.zip` 资源包。 - `canvasVersion` (boolean) - 进行动态文档转换时,除将源文档转换为常规的 DOM 元素外,是否额外转换为 `canvas` 元素: - `true`:将源文档转换为常规的 DOM 元素和 `canvas` 元素。 该选项适用于源文档包含复杂动画效果的情况,例如,切页动画。转换为 `canvas` 元素后,动画的渲染效果和性能更佳,但是转换速度会降低。 设置 `canvasVersion` 为 `true` 后,你可以使用 Whiteboard SDK,也可以使用 Fastboard SDK 渲染并展示转换后的文档。使用 Whiteboard SDK 可以读取转换结果中的 DOM 元素,并将其渲染为 DOM 网页,部分动画效果可能无法被渲染;使用 Fastboard SDK 可以读取转换结果中的 `canvas` 元素,并将其渲染为 canvas 页面,并保留完整的动画效果。 - `false`:(默认)仅将源文档转换为 DOM 元素。 该选项适用于除源文档包含复杂动画效果外的几乎所有情况,且转换速度快。但是,当源文档包含复杂动画时(例如,切页动画),转换为 DOM 元素后,部分动画效果可能无法被渲染,且渲染时可能出现卡顿。 未设置 `canvasVersion` 参数或设置 `canvasVersion` 为 `false` 后,仅可以使用 Whiteboard SDK 渲染并展示转换后的文档。使用 Fastboard SDK 将无法读取转换结果。 > [!NOTE] > 该参数仅在 `type` 设为 `dynamic` 时生效。 ### Request body example ```json { "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx", "type": "static", "preview": true, "scale": 1, "outputFormat": "jpg" } ``` ## Responses ### 201 若返回的状态码为 `201` 则表示请求成功。响应 Body 中包含本次请求的结果。 若返回的状态码不为 `201` 则表示请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/whiteboard/fastboard-sdk/reference/response-code)了解可能的原因。 - `uuid` (string) - 转换任务的 UUID,即转换任务的唯一标识符。 - `type` (string) - 转换任务类型,取值如下: - `dynamic`:动态文档转换,即文档转网页。 - `static`:静态文档转换,即文档转图片。 - Default: `dynamic` - `status` (string) - 转换任务的状态: - `Waiting`:等待转换。 - `Converting`:转换中。 - `Finished`:已完成。 - `Fail`:失败。 ## Response examples ### 201 ```json { "uuid": "2fd2dxxxxx367e", "type": "static", "status": "Waiting" } ```