通知
本站点除 Legacy 产品与方案外，已迁移至 声网新文档中心 ，当前页面不再维护
文档中心
全部产品
Console 官网 社区 技术支持
简体中文
search-icon

旧版文档转换 API 参考

更新时间 2023/06/29 09:42:11

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

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

发起文档转换（POST）

发起一个文档转换任务。

接口原型

  • 方法：POST
  • 接入点：https://api.netless.link/v5/services/conversion/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
  • webp
    • 默认值为 png
    该参数仅在 type 设为 static 时生效。
    pack boolean 可选 进行静态文档转换时，是否生成资源包：
  • true：生成资源包。该参数设为 true 时，声网服务端会将所有转换后的图片打包成 {uuid}.zip 文件，并上传到你指定的存储路径中。
  • false：（默认）不生成资源包。
    • 该参数仅在 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 将无法读取转换结果。
    • 该参数仅在 type 设为 dynamic 时生效。

    请求示例

    POST /v5/services/conversion/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": "static",
    "preview": true,
    "scale": 1,
    "outputFormat": "jpg"
}

    HTTP 响应

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

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

    请求成功响应示例：

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

    响应包体参数：

    参数 类型 描述
    uuid string 转换任务的 UUID，即转换任务的唯一标识符。
    type string 转换任务类型，取值如下：
  • dynamic：动态文档转换，即文档转网页。
  • static：静态文档转换，即文档转图片。
    		•
    status string 转换任务的状态：
  • Waiting：等待转换。
  • Converting：转换中。
  • Finished：已完成。
  • Fail：失败。
    		•

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

    查询转换任务的进度（GET）

    查询文档转换任务的进度。

    接口原型

    • 方法：GET
    • 接入点：https://api.netless.link/v5/services/conversion/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 获取。

    查询参数

    该 API 需要传入以下查询参数：

    参数 类型 是否必需 描述
    type string 必需 转换任务类型，取值如下：
  • dynamic：动态文档转换，即文档转网页。
  • static：静态文档转换，即文档转图片
    		•

    请求示例

    GET /v5/services/conversion/tasks/2fxxxxxx367e?type=static
Host: api.netless.link
region: cn-hz
Content-Type: application/json
token: NETLESSSDK_YWsxxxxxM2MjRi

    HTTP 响应

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

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

    请求成功响应示例：

    "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"
            }
        ]
    }
}

    响应包体参数：

    参数 类型 描述
    uuid string 转换任务的 UUID，转换任务的唯一标识符。
    type string 转换任务类型，取值如下：
  • dynamic：动态文档转换，即文档转网页。
  • static：静态文档转换，即文档转图片。
    		•
    status string 转换任务的状态：
  • Waiting：等待中。
  • Converting：转换中。
  • Finished：已完成。
  • Fail：失败。
    		•
    failedReason string 转换任务失败的原因。只有当 status 为 Fail 时，才会返回该字段。
    progress object 转换任务的进度，包括以下字段：
    • totalPageSize：Number 类型，转换文档总页数。
    • convertedPageSize：Number 类型，已经完成转换的页数。
    • convertedPercentage：Number 类型，转换进度百分比。
    • convertedFileList：Array 类型，已完成转换的文件列表，每个文件包含以下参数：
      • width：Number 类型，图片或动态 PPT 的宽度，单位为像素。
      • height：Number 类型，图片或动态 PPT 的高度，单位为像素。
      • conversionFileUrl：String 类型，转换文件的 URL。
      • preview: String 类型，预览图地址。当发起转换时请求包体中 preview 设为 true 且 type 为 dynamic 时，才会返回该字段。
    • currentStep：String 类型，动态转换任务当前的步骤，返回值包括：
      • Extracting：提取资源。
      • Packaging：打包资源。
      • GeneratingPreview：生成预览图。
      • MediaTranscode：媒体转码。
    当发起转换时请求包体中 type 为 dynamic 时，才会返回 currentStep 字段。

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