文档转码

文档上传与转码服务，用于将Office/PDF文档上传至云端并转码成图片或网页，通常用于会议或教学等场景。

请注意，与其他RESTful API使用PanoSign来认证不同，文档转码API使用PanoToken认证，这是因为Pano假设文档转码API都是由客户端调用。文档转码相关API并不关心Token里的userId、channelId、duration这些信息，只要是合法有效的Token就可以。如果需要在App Server端调用文档转码相关API，可以先调用 生成Token 接口生成一个token，参数userId、channelId、duration等信息可以任意指定。

上传文档并转码

使用 Form 表单方式上传 Office 文档或 PDF 文档至 Pano 服务器并转码。
文档上传完成后，Pano 服务器会开始转码，转码速度取决于资源空闲程度，开发者可以通过查询文档信息接口来查询进度，也可以等待 Webhook 消息通知。

请求

POST /docs
Host: api.pano.video
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIOFbRKVnqu56AZ6w


------WebKitFormBoundaryIOFbRKVnqu56AZ6w
Content-Disposition: form-data; name="file"; filename="xxx.pptx"
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation


------WebKitFormBoundaryIOFbRKVnqu56AZ6w
Content-Disposition: form-data; name="lifeType"

2
------WebKitFormBoundaryIOFbRKVnqu56AZ6w
Content-Disposition: form-data; name="convertType"

1
------WebKitFormBoundaryIOFbRKVnqu56AZ6w--

参数说明：

  • file - 上传需要进行转码的文档，仅支持 pdf、pptx、ppt、docx、doc、xlsx、xls 格式。
    当 convertType 参数为 3 时，文件最大支持 300 MB；否则最大支持 200 MB。
  • lifeType - int，可选，表示文档的生命周期，1-long term (长期)，2-temp (7天)，默认为1。

    [注意] 参数为 2 的文档 7 天后会被自动清除。

  • convertType - int，可选，表示转码类型：1-jpg，2-png，3-html，4-pdf，默认为1。
    • 参数为 1 和 2 时将文档转码为图片(也称静态转码)。
    • 参数为 3 时将文档(仅支持pptx和ppt格式)转码为网页，保留文档内的动画和音视频(也称动态转码)。
    • 参数为 4 时将文档转码为 PDF 格式(也称高清转码)。
  • needThumb - bool，可选，是否需要缩略图，默认为false
  • needZip - bool，可选，是否需要压缩包，默认为false
  • meta - string，可选，元信息(开发者自定义信息，将随文档信息原样返回)

响应

状态码说明
200请求成功处理
400请求格式错误
401认证错误
413文件过大
500服务器内部错误

响应示例

200 OK

{
  "docId": "12345678901234567"
}

分片上传文档并转码

分片上传文档主要是为了提高文档上传速度，原理是将一个大文件切分成多个小文件同时上传。
使用分片上传功能需要经过三个步骤：

  1. 初始化分片上传
  2. 上传分片
  3. 完成上传并转码

初始化分片上传

请求

POST /docs/multi/init
Host: api.pano.video
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIOFbRKVnqu56AZ6w

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="fileSize"

5242880
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="fileName"

150M.pptx
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="lifeType"

1
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="convertType"

3
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="needThumb"

true
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="needZip"

true
----WebKitFormBoundary7MA4YWxkTrZu0gW

参数说明：

  • fileSize - long，必选，分片上传文件总大小(单位：字节)
  • fileName - string，必选，分片文件名称
  • 其他参数(lifeType, convertType, needThumb, needZip, meta)和 上传文档并转码 接口中一致

响应

状态码说明
200请求成功处理
400请求格式错误
401认证错误
413文件过大
500服务器内部错误
响应示例
200 OK

{
  "docId": "12345678901234567"
}

上传分片

各分片文件主要利用初始化分片上传接口中返回的 docId 进行关联。

请求

POST /docs/multi/upload
Host: api.pano.video
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIOFbRKVnqu56AZ6w

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="50MPPTX"
Content-Type: <Content-Type header here>

(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="partNumber"

9
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="docId"

296312198618161152
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="lastPart"

false
----WebKitFormBoundary7MA4YWxkTrZu0gW

参数说明：

  • file - 必选，分片文件，分片最大 100 MB，最小 5 MB(最后一片不受 5 MB限制)
  • partNumber - int，必选，分片号，表示第几个分片，最小值为 1，最大值为 500；如果传入相同的 partNumber，后一个会覆盖前一个
  • docId - string，必选，初始化分片上传接口返回的docId
  • lastPart - bool，可选，是否是最后一个分片，默认false

响应

状态码说明
200请求成功处理
400请求格式错误
401认证错误
413文件过大
500服务器内部错误
响应示例

参数说明：

  • etag: 具体分片文件对应的标识，请保存 partNumber 和 etag 的对应关系，在最终完成分片上传的时候，会校验对应值。
200 OK

{
    "etag": "e1b342db315767be0f311fae105d1283"
}

完成分片上传并转码

请求

POST /docs/multi/complete
Host: api.pano.video
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596
Content-Type: application/json

{
    "docId": "296312198618161152",
    "etags":[
        {
            "partNumber": 1,
            "etag": "219db7f448c253798015bb7540814d4c"
        },
        {
            "partNumber": 2,
            "etag": "046da90e1dfd5cb0ad491ab3b9907618"
        }
    ]
}

参数说明：

  • docId - string，必选，初始化分片上传接口返回的 docId
  • etags - 必选，分片文件信息
  • partNumber - int，必选, 每次分片上传的 partNumber
  • etag - string，必选, 每次分片上传的 partNumber 返回的 etag

注意：etags 中的 partNumber 必须是连续递增的分片号，形如 1，2，3 ...，服务器认为合法；形如 1，3，5 ...会被服务器拒绝。

响应

状态码说明
200请求成功处理
400请求格式错误
401认证错误
413文件过大
500服务器内部错误

放弃分片上传

请求

DELETE /docs/multi/abort/<docId>
Host: api.pano.video
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596

参数说明：

  • docId - string，必选，初始化分片上传接口返回的 docId

响应

状态码说明
200请求成功处理
400请求格式错误
401认证错误
413文件过大
500服务器内部错误

查询文档信息

用于查询文档转码进度，也用于生成图片地址。

请求

GET /docs/<docId>?duration=7200
Host: api.pano.video
Content-Type: application/json
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596

参数说明：

  • docId - 文档id
  • duration - int 可选, 表示生成的url的有效期，单位：秒，默认为2小时

参数示例：
GET https://api.pano.video/docs/12345678901234567?duration=7200

响应

状态码说明
200请求成功处理
401认证错误
403非法操作
404文件不存在
500服务器内部错误

响应示例

当status=3时，响应里会带上转码结果的URL。当status=0时，字段code会进一步给出错误原因。

200 OK

{
  "docId": "12345678901234567",
  "pageCount": 2,
  "progress": 100, // 暂时只有0和100两个值
  "status": 3,     // 1-QUEUED, 2-RUNNING, 3-FINISHED, 0-FAILED
  "code": 0,       // 0-NoError, 1-Unsupported, 2-TimeOut, 3-ConvertFailed
  "url": [
    "https://transcode.pano.video/temp/convert/12345678901234567/1.jpg",
    "https://transcode.pano.video/temp/convert/12345678901234567/2.jpg"
  ],
  "thumbUrl": [    // 默认为 null，needThumb 为 true 时才有返回值
    "https://transcode.pano.video/temp/convert/12345678901234567/thumb/1.jpg",
    "https://transcode.pano.video/temp/convert/12345678901234567/thumb/2.jpg"
  ],
  "zipUrl": "https://transcode.pano.video/temp/convert/12345678901234567/bundle.zip", //默认为 null，needZip 为 true 时才有返回值
  "thumbZipUrl": "https://transcode.pano.video/temp/convert/12345678901234567/thumb/bundle.zip", ///默认为 null，needZip与needThumb都为 true 时才有返回值
  "sourceUrl": "https://transcode.pano.video/temp/src/12345678901234567/test.ppt", //源文件下载地址
  "meta": "info" // 原样返回开发者传入的自定义信息
}

分页查询转码文档列表

分页查询文档列表，按转码文档创建时间倒序排列。

请求

GET /docs?beginTime=<beginTime>&endTime=<endTime>&page=<page>&pageSize=<pageSize>
HOST: api.pano.video
Content-Type: application/json
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596

参数说明：

  • beginTime - long, 可选, 查询时间区间的起始时间(UTC时间戳, 单位：秒)
  • endTime - long, 可选, 查询时间区间的结束时间(UTC时间戳, 单位：秒)
  • page - int, 可选, 当前查询的页码, 默认值为1
  • pageSize - int, 可选, 当前页显示的条数, 默认值为100, 最大值为500

参数示例：
GET https://api.pano.video/docs?beginTime=1635696000&endTime=1635782399&page=1&pageSize=10

响应

状态码说明
200请求成功处理
401认证错误
500服务器内部错误

响应示例

200 OK
{
   "page": 1,      // int, 当前页码
   "pageSize": 10, // int, 每页显示条数
   "total": 2,     // int, 总文档条数
   "docs":
    [
      {
        "docId": "12345678901234567", // string, 转码文档ID
        "ctime": "1635696000"          // string, 转码文档创建时间(UTC时间戳, 单位：秒)
      },
      {
        "docId": "12345678901234568",
        "ctime": "1635696060"
      }
    ]
}

删除文档

请求

DELETE /docs/<docId>
Host: api.pano.video
Content-Type: application/json
Authorization: PanoToken <Token>
Tracking-Id: ef9b2acc8e1f4d598090eb6d9cbe8596

参数说明：

  • docId - 文档id

参数示例：
DELETE https://api.pano.video/docs/12345678901234567

响应

状态码说明
200请求成功处理
401认证错误
403非法操作
404文件不存在
500服务器内部错误
Last updated on 1/26/2022
← CDN推流消息服务 →