本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护

文档中心





全部产品

Console 官网社区技术支持





文档转换

更新时间 2023/07/12 09:43:54

声网互动白板提供文档转换服务，支持将 PPT、PPTX、DOC、DOCX、PDF 格式的文件转换成静态图片，将 PPT 和 PPTX 的文件转换为动态 HTML 网页，转换后的图片或网页可作为演示资料在互动白板中展示。详见文档转换服务。

本文仅适用于新版文档转换服务。新版本和旧版本的差异详见新旧版本对比。如果使用旧版文档转换服务，请查看旧版文档转换服务 API 参考。

调用文档转换 API 前，请确保：

已在声网控制台开启文档转图片或文档转网页服务并添加存储配置。详见开启互动白板配套服务。
已为待转换的文档生成一个公网可访问的 URL 地址。

发起文档转换

发起一个文档转换任务。

接口原型

方法：POST
接入点：https://api.netless.link/v5/projector/tasks

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数	类型	是否必需	描述
`token`	string	必需	拥有 `writer` 或 `admin` 权限的 SDK Token，可通过以下方式获取：在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。调用服务端 RESTful API，详见生成 SDK Token。在 app 服务端用代码生成，详见在 app 服务端生成 Token。
`region`	string	必需	指定处理该请求的数据中心，取值如下： `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。 `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。 `in-mum`：印度孟买，服务区覆盖印度。 `eu`：欧洲（法兰克福），服务区覆盖欧洲。

请求包体

该 API 需要在请求包体中传入以下参数：

参数	类型	是否必需	描述
`resource`	string	必需	待转换的源文件 URL。
`type`	string	可选	转换任务类型，取值如下： `dynamic`：（默认）动态文档转换，即文档转网页。 `static`：静态文档转换，即文档转图片。
`preview`	boolean	可选	是否需要生成预览图： `true`：是。 `false`：否。该参数仅在 `type` 设为 `dynamic` 时生效。
`scale`	number	可选	图片缩放比例，取值范围 [0.1,3.0]，默认值为 `1.2`。数值越大，图片越清晰。该参数仅在 `type` 设为 `static` 时生效。
`outputFormat`	string	可选	输出图片格式，取值如下：（默认）`png` `jpg` `jpeg` 该参数仅在 `type` 设为 `static` 时生效。
`webhookEndpoint`	string	可选	Webhook 回调地址，一般为 app 服务端地址，用于接收服务端发送的转换任务进度等信息。详见 Webhook 回调。
`webhookRetry`	number	可选	Webhook 回调失败时的重试次数。默认值为 `3` ，最大值为 `10` 。
`imageCompressionLevel`	number	可选	动态转换输出图片的压缩等级，仅能传入以下值： `0`：（默认）输出原图。 `1`：输出图片使用的最大颜色数量限制为 256。 `2`：输出图片使用的最大颜色数量限制为 192。 `3`：输出图片使用的最大颜色数量限制为 128。 `4`：输出图片使用的最大颜色数量限制为 64。该参数仅在 `type` 设为 `dynamic` 时生效。通常，在保证画质不受明显影响的前提下，输出图片的体积最高可以压缩至原图的 10%。压缩图片体积可在弱网环境下改善转换后 PPT 的首次加载时间。

请求示例

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

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

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 201，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

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

响应包体参数：

参数	类型	描述
`uuid`	string	转换任务的 UUID，即转换任务的唯一标识符。
`status`	string	转换任务的状态： `Waiting`：等待转换。 `Converting`：转换中。 `Finished`：已完成。 `Fail`：失败。

如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

查询转换任务进度

查询七天内创建的文档转换任务的进度。

接口原型

方法：GET
接入点：https://api.netless.link/v5/projector/tasks/{uuid}

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数	类型	是否必需	描述
`token`	string	必需	Task Token，可通过以下方式获取：调用服务端 RESTful API，详见生成 Task Token。在 app 服务端用代码生成，详见在 app 服务端生成 Token。
`region`	string	必需	指定处理该请求的数据中心，取值如下： `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。 `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。 `in-mum`：印度孟买，服务区覆盖印度。 `eu`：欧洲（法兰克福），服务区覆盖欧洲。

请求路径

该 API 需要在 URL 中传入以下参数：

参数	类型	是否必需	描述
`uuid`	string	必需	转换任务的 UUID，即转换任务的唯一标识符，可通过调用发起转换任务 API 获取。

请求示例

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

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

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

响应包体参数：

参数	类型	描述
`uuid`	string	转换任务的 UUID，转换任务的唯一标识符。
`status`	string	转换任务的状态： `Waiting`：等待中。 `Converting`：转换中。 `Finished`：已完成。 `Fail`：失败。
`type`	string	转换任务类型，取值如下： `dynamic`：动态文档转换，即文档转网页。 `static`：静态文档转换，即文档转图片。
`convertedPercentage`	number	转换进度百分比。
`prefix`	string	转换结果文件地址前缀路径。
`pageCount`	number	文档页数，转换任务失败时没有该字段。
`previews`	object	转换后的文档预览图地址，每页对应一个预览图地址。该参数仅在发起文档转换时，请求包体中的 `preview` 设为 `true`，且 `type` 设为 `dynamic` 时才生效。
`note`	string	从文档中提取出的备注内容，只包含有备注的页面。
`images`	object	文档转图片结果的地址，每页对应一张图片。该参数仅在发起文档转换时，请求包体中的 `type` 设为 `static` 时才生效。
`errorCode`	string	错误码。仅在转换任务失败时，才会返回该字段。所有可能的错误码详见错误码汇总表。
`errorMessage`	string	错误码对应的错误消息，描述出错的原因。仅在转换任务失败时，才会返回该字段。

查询转换任务进度接口仅支持查询七天内创建的转换任务。
为了避免转换状态信息或结果丢失，声网推荐你在转换完毕或者失败后，及时自行存储任务信息，或通过 Webhook 回调获取任务状态更变的通知。

查询待转换任务

列出未完成转换的所有任务。

接口原型

方法：GET
接入点：https://api.netless.link/v5/projector/tasks

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数	类型	是否必需	描述
`token`	string	必需	拥有 `writer` 或 `admin` 权限的 SDK Token，可通过以下方式获取：在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。调用服务端 RESTful API，详见生成 SDK Token。在 app 服务端用代码生成，详见在 app 服务端生成 Token。
`region`	string	必需	指定处理该请求的数据中心，取值如下： `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。 `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。 `in-mum`：印度孟买，服务区覆盖印度。 `eu`：欧洲（法兰克福），服务区覆盖欧洲。

请求示例

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

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

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

响应包体参数：

参数	类型	描述
`taskId`	string	转换任务的 UUID，即转换任务的唯一标识符。
`status`	number	转换任务的状态： `1`：任务进行中。 `0`：任务正在排队。

如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

取消指定的文档转换任务

取消指定的文档转换任务。

接口原型

方法：DELETE
接入点：https://api.netless.link/v5/projector/tasks/{uuid}

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数	类型	是否必需	描述
`token`	string	必需	SDK Token，可通过以下方式获取：调用服务端 RESTful API，详见生成 SDK Token。在 app 服务端用代码生成，详见在 app 服务端生成 Token。
`region`	string	必需	指定处理该请求的数据中心，取值如下： `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。 `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。 `in-mum`：印度孟买，服务区覆盖印度。 `eu`：欧洲（法兰克福），服务区覆盖欧洲。

请求路径

该 API 需要在 URL 中传入以下参数：

参数	类型	是否必需	描述
`uuid`	string	必需	转换任务的 UUID, 即转换任务的唯一标识符，可通过调用发起转换任务 API 获取。

请求示例

DELETE /v5/projector/tasks/2fxxxxxx367e
Host: api.netless.link
region: cn-hz
Content-Type: application/json
token: NETLESSSDK_YWsxxxxxM2MjRi

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

{
  taskId: 'xxx',
  success: true
}

响应包体参数：

参数	类型	描述
`taskId`	string	转换任务的 UUID，即转换任务的唯一标识符。
`success`	boolean	是否成功取消转换任务： `true`：取消成功。 `false`：取消失败。

如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

设置任务优先级

将待进行的指定任务移动至任务队列最前面或最后面。

接口原型

方法：PUT
接入点：https://api.netless.link/v5/projector/tasks/{uuid}/priority

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数	类型	是否必需	描述
`token`	string	必需	拥有 `writer` 或 `admin` 权限的 SDK Token，可通过以下方式获取：在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。调用服务端 RESTful API，详见生成 SDK Token。在 app 服务端用代码生成，详见在 app 服务端生成 Token。
`region`	string	必需	指定处理该请求的数据中心，取值如下： `cn-hz`：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。 `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。 `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。 `in-mum`：印度孟买，服务区覆盖印度。 `eu`：欧洲（法兰克福），服务区覆盖欧洲。

请求包体

该 API 需要在请求包体中传入以下参数：

参数	类型	是否必需	描述
`priority`	string	必需	设定优先级，取值如下： `highest`：最高，即移动至任务队列最前。 `lowest`：最低，即移动至任务队列末尾。

请求路径

该 API 需要在 URL 中传入以下参数：

参数	类型	是否必需	描述
`uuid`	string	必需	转换任务的 UUID, 即转换任务的唯一标识符，可通过调用发起转换任务 API 获取。

请求示例

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

{
    "priority": highest
}

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

{
  uuid: 'xxx',
  success: true 
}

响应包体参数：

参数	类型	描述
`uuid`	string	转换任务的 UUID，即转换任务的唯一标识符。
`success`	boolean	是否成功设置优先级： `true`：设置成功。 `false`：设置失败。

如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

Webhook 回调

接收来自服务端的文档转换进度和运行状态信息。发起文档转换时，在请求包体填入相应参数以调用。

Webhook 回调有一定概率重复回调，为保证 app 服务端在接到相同响应时的处理方式保持一致，需要做好幂等处理。

HTTP 响应

所有可能的响应状态码详见状态码汇总表。

如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

请求成功响应示例：

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

      "note": "https://xxx.xx.xx/note.json"，
      "images": {
        "1": {
          "width": 720,
          "height": 1080,
          "url": "https://xxxx.xx.xx/1.xxx",
        },
        "2": {
          "width": 720,
          "height": 1080,
          "url": "https://xxxx.xx.xx/2.xxx",
        }
      },
      "noticeTimestamp": 1231369699739
  }

}

响应包体参数：

参数	类型	描述
`code`	number	错误码，成功时为 `0`。所有可能的错误码详见错误码汇总表。
`message`	string	错误码对应的错误消息，描述出错的原因。
`taskId`	string	转换任务的 UUID，即转换任务的唯一标识符。
`taskType`	string	任务类型，可能的值如下： `dynamic`：动态文档转换，即文档转网页。 `static`：静态文档转换，即文档转图片。
`prefixUrl`	string	转换后文件地址的前缀路径。
`pageCount`	number	文档页数，转换任务失败时没有该字段。
`previews`	object	转换后的文档预览图地址，每页对应一个预览图地址。仅在发起文档转换时，请求包体中的 `preview` 设为 `true`，且 `type` 设为 `dynamic` 时才生效。转换任务失败时没有该字段。
`note`	string	文档提取出的备注内容，只包含有备注的页面。
`images`	object	文档转图片结果的地址，每页对应一张图片。该参数仅在发起文档转换时，请求包体中的 `type` 设为 `static` 时才生效。
`noticeTimestamp`	number	通知时间戳。

错误码

调用文档转换服务时可能出现的错误码和相关说明。

错误码	错误消息	描述	处理方法
2010201	unsupported file format	用户上传了不支持的文件格式（如 PGN, JPG, JEPG, MP3, MP4 等)。	上传支持的文件。
2010202	dynamic conversion only support pptx	用户上传的文件格式不支持动态转换。	上传 PPTX 格式的文件。
2010203	the number of tasks exceeds limit	转换队列中的任务过多。	调用取消指定的文档转换任务以减少队列中的任务数量，或等待已有转换任务完成后再发起转换。
2010605	task not found	未找到要查询的任务。	查询任务参数是否正确。
2011201	task timeout	任务超时。	检查网络连接或压缩文件体积。
2010606	team not found	找不到用户信息。	查询 token 是否正确。在控制台中确认数据中心和文档转网页服务是否正确配置。
2010607	modify priority for running task is not allowed	无法修改正在运行的任务优先级。	确保所修改的任务正在排队中。
2011301	task not found	传入的 taskid 查询不到任务。	查询任务参数是否正确。
2030100	download from OSS file failed	源文件下载失败。	检查文件是否已经上传。
2030101	unzip file failed, unsupported file in PPT	不支持的 PPT 格式。	检查是否能使用 PowerPoint 打开此文件。
2030102	can't find media file from unzip PPT	解压后找不到媒体文件。	检查 PPT 媒体文件位置是否正确，是否使用了外链。在用户电脑上测试，移动 PPT 其它文件夹后，打开 PPT 能否播放媒体文件。
2030200	read xml file failed	解压后的 XML 文件异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2030201	formula resolve failed, please check animation of PPT	XML 中的公式解析错误。	检查或删除 PPT 内的动画并重试。
2030202	unsupported formula type, please check animation of PPT	XML 中的公式类型错误。	检查或删除 PPT 内的动画并重试。
2030801	Invalid parsing of display object (Type: slide; Page: 45; Object Name: Img 3)	解析某个元素时出错。	联系技术支持或者将错误元素删除后重新发起转换, 可根据错误消息中的 `Page` 和 `Object Name` 定位到错误元素的具体页码和名称。
2030802	Invalid parsing of slide (Page: 11;)	解析某个页面时出错。	联系技术支持或者将错误页面删除后重新发起转换, 可根据错误消息中的 `Page` 定位到错误页面的具体页码。
2040005	task timeout	图片转换任务超时。	文档内的图片可能异常或者体积过大，联系技术支持定位。
2050099	unknown error	未知的文档转图片异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2050100	unsupported file type	不支持的文件格式。	上传 PPT 或 PPTX 文件。
2050101	file download failed	源文件下载失败。	检查网络连接。
2050102	file is empty	文件内容为空。	本地打开检查文件是否有内容。
2050107	file url encode failed	文件 URL 编码失败。	检查文件路径是否正常。
2050201	init presentation parser failed	初始化 PPT 解析异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2050299	unknown parsing error	未知的文档解析异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2050401	generate preview failed	预览图生成失败。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2060402	fonts in the rules that are not provided	找不到指定字体。	联系技术支持。
2090304	upload file to custom storage failed	上传文件到用户存储失败。	检查存储配置是否正确。
2090305	not supported storage provider	不支持的云存储服务商。	检查服务商链接是否正确或更换服务商。
2110099	unknown error	未知的文档转图片异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2110100	unsupported file type	用户传入了无法支持的文件格式。	上传静态转换支持的文件（ ppt/pptx/doc/docx/pdf）。
2110101	download file failed	文件下载失败。	检查文件地址是否有效。
2110102	file is empty	文件内容为空。	本地打开文件，检查是否有内容。
2110107	file url encode failed	文件 URL 编码失败。	检查文件路径是否正常。
2110108	get file extension failed	获取文件格式失败	检查上传的文件是否直接修改过扩展名，但文件本身是不支持的格式。
2110201	init presentation parser failed	未知的 PPT 文档解析异常。	检查上传的文件是否为非 PowerPoint 软件编辑（例如 WPS）。
2110202	init word parser failed	未知的 DOC 文档解析异常。	检查上传的文件是否为非 Word 软件编辑（例如 WPS）。
2120201	file is empty	PDF 文件内容为空。	本地打开文件，检查是否有内容。
2120301	download file failed	PDF 文件下载失败。	检查文件地址是否有效。

这篇文章对你有帮助吗？

是

否