为了在白板互动中共享文件，你可能需要将文档转为静态图片或动态的 HTML5 页面。通过调用服务端 OpenAPI WbTranscodeCreate 发起文档转码任务。
转码的任务处理是异步的，你可以通过 WbTranscodeQuery 查询到转码任务完成后，调用 WbTranscodeGet 获取转换好的链接集合。

调用服务端接口完成文档转码后，你还需要调用客户端接口，将转码后的文档共享到白板房间。文件上传的完整流程参见 文档上传。

前提条件

发起文档转码任务

WbTranscodeCreate 发起一个文档转码任务。

  • 调用本接口前，你需要先将文件上传到 TOS。
  • 如果你需要对多个文件进行转码，请分别调用 WbTranscodeCreate 传入相应的文件和参数设置。
请求方式

使用 Post 方式发起请求。
关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

请求参数

以下是接口特有的请求参数。关于其他公共请求参数，参看请求参数。

Query
参数名类型必填示例值描述
Actionstring是WbTranscodeCreate接口名称，本接口取值：WbTranscodeCreate
Versionstring是2020-12-01接口版本，本接口取值：2020-12-01
Body
参数名类型必填示例值描述
app_idstring是600000000000000000000000应用的唯一标志。你可以通过控制台查看和复制你的 app_id。或通过调用 ListApps 接口获取。
resourcestring是https://resource.com需要转换为图片的文档链接地址。每次调用接口只能请求处理一份文档。
resource_attrResourceAttr动态转码必填，静态转码无需填写动态转码文件设置
operatorstring是your_user_id用户 ID

transcode_config

TranscodeConfig

静态转码必填，动态转码无需填写

{
  "input_format":1,
  "output_format":1,
  "output_width":1080,
  "output_height":720
}

json

转码参数设置

storage_config

StorageConfig

  • 使用第三方的对象存储服务：必填

  • 使用火山引擎的对象存储服务，并已经在控制台设置了图片存储属性，则此参数选填

{
  "type":0,
     "tos_config":{
        "account_id":"xxx",
            "region":0,
            "bucket":"xxx"
     }
}

json

对象存储属性

  • 使用火山引擎的对象存储服务，且本次传入的参数与控制台设置的属性有差异，则以传入参数为准。

transcode_mode

int

否

0

转码类型
0: 静态转码(默认)
1: 动态转码

priority

int

否

0

静态转码的转码优先级

  • 【默认值】0: 非实时转码
  • 1: 实时转码

pre_sign_duration

int

否

5000

转码成功后返回的 URL 预签名有效期。有效范围：0 ~ 604800。

  • 【默认值】0：无限期。你需要在 TOS 服务的 bucket 为公共读。
  • 1 ～ 604800：URL 预签名有效期，单位是秒。
请求示例代码
Query
https://rtc.volcengineapi.com?Action=WbTranscodeCreate&Version=2020-12-01

postscript
Body
{
    "app_id":"600000000000000000000000",
    "oprator":"your_user_id",
    "resource":"https://resource.com",
    "priority":0,
    "transcode_config":{
        "input_format":1,
        "output_format":1,
        "output_width":1080,
        "output_height":720
    },
    "storage_config":{
        "type":0,
        "tos_config":{
            "account_id":"xxx",
            "region":0,
            "bucket":"xxx"
        }
    }
}

json
返回调用结果
正常返回示例
{
    "ResponseMetadata": {
        "RequestId": "your_request_id",
        "Service": "rtc",
        "Region": "cn-north-1",
        "Action": "WbTranscodeCreate",
        "Version": "2020-12-01"
    },
    "Result": {
        "task_id": "xxx" //task_id 为查询任务进度和获取转码后链接的必填参数
    }
}

json

查询文档转码进度

发起文档转码任务，可以通过调用 WbTranscodeQuery 查询转码任务的进度。

请求方式

使用 Get 方式发起请求。
关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

请求参数

以下是接口特有的请求参数。关于其他公共请求参数，参看请求参数。

Query
参数名类型必填示例值描述
Actionstring是WbTranscodeQuery接口名称，本接口取值：WbTranscodeQuery
Versionstring是2020-12-01接口版本，本接口取值：2020-12-01

app_id

string

是

600000000000000000000000

应用的唯一标志。你可以通过控制台查看和复制你的 app_id。或通过调用 ListApps 接口获取。

task_idstring是0000000000成功调用 WbTranscodeQuery后返回的任务ID
请求示例代码
Query
https://rtc.volcengineapi.com?Action=WbTranscodeQuery&Version=2020-12-01&app_id=your_app_id&task_id=your_task_id

postscript
返回调用结果
参数名类型必须说明

status

int

是

转码任务状态

  • 0：未开始
  • 1：进行中
  • 2：已完成
  • 3：失败

progress

err_code

int

int

否

否

静态转码进度。100 表示已完成。
动态转码恒定为 0。
错误码

err_msgstring否错误信息
正常返回示例
{
    "ResponseMetadata": {
        "RequestId": "your_request_id",
        "Service": "rtc",
        "Region": "cn-north-1",
        "Action": "WbTranscodeQuery",
        "Version": "2020-12-01"
    },
    "Result": {
        "status": 2, // 0：未开始，1:进行中，2:已完成：3:失败
        "progress": 100, 
        "err_code": 0,
        "err_msg": ""
    }
}

json

获取转码输出链接

文档转码任务完成后，可以通过 WbTranscodeGet 获取文档转码后的链接。

请求方式

使用 Get 方式发起请求。
关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

请求参数

以下是接口特有的请求参数。关于其他公共请求参数，参看请求参数。

Query
参数名类型必填示例值描述
Actionstring是WbTranscodeGet接口名称，本接口取值：WbTranscodeGet
Versionstring是2020-12-01接口版本，本接口取值：2020-12-01

app_id

string

是

600000000000000000000000

应用的唯一标志。你可以通过控制台查看和复制你的 app_id。或通过调用 ListApps 接口获取。

task_idstring是0000000000成功调用 WbTranscodeQuery后返回的任务ID

请求示例代码
Query
https://rtc.volcengineapi.com?Action=WbTranscodeGet&Version=2020-12-01&app_id=your_app_id&task_id=your_task_id

json
返回调用结果
正常返回示例

以静态转码任务为例。与动态转码不同，静态转码的返回值不包含 file_id 参数。

{
    "ResponseMetadata": {
        "RequestId": "your_request_id",
        "Service": "rtc",
        "Region": "cn-north-1",
        "Action": "WbTranscodeGet",
        "Version": "2020-12-01"
    },
    "Result": {
        "file_name": "cs.pptx",
        "width": 1920,
        "height": 1080,
        "transcode_mode": 0,
        "images": [
            {
                "page_id": 1,
                "img": "https://result1.com",
                "thumbnail_url": "https://result1_thm.com"
            },
            {
                "page_id": 2,
                "img": "https://result2.com",
                "thumbnail_url": "https://result2_thm.com"
            }
        ],
        "h5_url": ""
    }

json
数据结构
ResourceAttr
参数类型必须描述
file_namestring是文件名
sizeint是文件大小，单位：byte
TranscodeConfig
参数类型必须描述

input_format

int

是

输入文件类型
1: ppt
2: pptx
3: doc
4: docx
5: pdf

output_format

int

是

输出文件类型
1: png
2: jpg/jpeg

force_use_resolution

bool

否

是否按照指定分辨率拉伸页面
默认为 false，按照文件的原始宽高比适配指定分辨率。

output_widthint是转码后的页面宽度，单位为像素
output_heightint是转码后的页面高度，单位为像素
thumbnailbool否是否生成缩略图，默认为 false
thumbnail_widthint否缩略图分辨率宽，默认为 320
thumbnail_heightint否缩略图分辨率高，默认为 180
StorageConfig
参数类型必须描述

type

int

是

存储类型
【默认值】0: Tos
1: 第三方对象存储接口，支持阿里云和亚马逊

tos_configTosConfig否火山引擎的对象存储服务参数设置
custom_configCustomConfig否第三方对象存储服务参数设置
TosConfig
参数类型必须描述

account_id

string

是

Bucket 所属的火山引擎账号 ID。在登陆火山引擎后，可在头像的悬浮菜单中找到账号 ID。

regionint是0: 北京
bucketstring是桶名称。登陆 TOS 控制台 开通和获取。
CustomConfig
参数类型必须描述

vendor

int

是

第三方存储供应商
0: Amazon 亚马逊
1: Alicloud 阿里云

region

int

是

区域

{
"Custom": {
        "AmazonS3": {
            "EndPointFormat": "",
            "RegionIDs": {
                "0": "us-east-1",
                "1": "us-east-2",
                "2": "us-west-1",
                "3": "us-west-2",
                "4": "eu-west-1",
                "5": "eu-west-2",
                "6": "eu-west-3",

                "8": "ap-southeast-1",

                "10": "ap-northeast-1",
                "11": "ap-northeast-2",
                "12": "sa-east-1",
                "13": "ca-central-1",
                "14": "ap-south-1",

                "18": "ap-east-1",
                "19": "eu-south-1",
                "20": "ap-northeast-3",
                "21": "eu-north-1",
                "22": "me-south-1",

                "24": "af-south-1"
            }
        },
        "AlicloudOSS": {
            "EndPointFormat": "%v.aliyuncs.com",
            "RegionIDs": {
                "0": "oss-cn-hangzhou",
                "1": "oss-cn-shanghai",
                "2": "oss-cn-qingdao",
                "3": "oss-cn-beijing",
                "4": "oss-cn-zhangjiakou",
                "5": "oss-cn-huhehaote",
                "6": "oss-cn-wulanchabu",
                "7": "oss-cn-shenzhen",
                "8": "oss-cn-heyuan",
                "9": "oss-cn-guangzhou",
                "10": "oss-cn-chengdu",
                "11": "oss-cn-hongkong",
                "12": "oss-us-west-1",
                "13": "oss-us-east-1",
                "14": "oss-ap-southeast-1",
                "15": "oss-ap-southeast-2",

                "17": "oss-ap-southeast-5",
                "18": "oss-ap-northeast-1",
                "19": "oss-ap-south-1",
                "20": "oss-eu-central-1",
                "21": "oss-eu-west-1",
                "22": "oss-me-east-1",
                "23": "oss-ap-southeast-6"
            }
        }
   }

json
bucketstring是桶名称
access_keystring是Access Key

secret_key

stiring

是

Secret Key
AK/SK建议只开通写权限，关闭读权限。