visionular

本手册介绍媒体处理服务相关的 API。

API 概览

本文为您提供了媒体处理服务所有 API 的列表。

视频存储相关接口

接口名称接口功能描述
add_storage调用add_storage创建转码后视频输出的存储空间。
list_storage调用list_storage查询存储空间信息。
del_storage调用del_storage删除存储空间。

转码模板相关接口

接口名称接口功能描述
add_template调用add_template创建转码模板。
query_template调用query_template查询转码模板信息。
update_template调用update_template更新转码模板信息。
list_template调用list_template查询转码模板列表。
add_adaptive_template调用add_adaptive_template新增多码率转码模板。
update_adaptive_template调用update_adaptive_template更新多码率转码模板。
del_template调用del_template删除转码模板。

转码任务相关接口

接口名称接口功能描述
create_task调用create_task创建转码任务。
query_task调用query_task查询转码任务。
list_task调用list_task查询转码任务列表。

请求结构

本文为您介绍了媒体处理服务 API 的请求结构。

服务地址

接入地域域名
中国大陆api.visionular.cn

通信协议

只支持通过HTTPS 进行通信。

请求方法

方法描述
GET适用于查询一条或多条记录的接口，请求参数从请求的 URL 中获取。
POST适用于增加一条记录的接口，请求参数从请求的 JSON Body 中获取。
PUT适用于修改一条记录的接口，请求参数从请求的 JSON Body 中获取。
DELETE适用于删除一条记录的接口，请求参数从请求的 URL 中获取。

HTTP 请求头

请求头描述
Content-Type需要从 JSON Body 中传入参数的 API 必须设置Content-Type:application/json。

字符编码

请求及返回结果都使用 UTF-8 字符集进行编码。

签名机制

本文介绍如何对HTTPS协议的请求进行加密验证。 目前有2个版本的签名方法, 签名方法V2简单易用。

签名版本V2

简介

具体采用AK（AccessKeyId）/SK（SecretAccessKey）/SIGN（Signature）的形式做访问限制。

云直播服务通过使用AccessKeyId和SecretAccessKey进行使用BasicAuth方法来验证请求的发送者身份。

  • 您可以在公有云服务控制台申请AK/SK密钥对。

    说明：您可以同时申请多组AK/SK密钥对，也可以设置某个AK/SK密钥对失效。

  • 在您获取AK/SK密钥对后，可根据特定的签名算法或签名SDK生成带签名的请求。

签名示例(Golang)
func BuildRequest(username, password string) (requestInfo *http.Request, err error)
{
    requestInfo, _ = http.NewRequest(method, url.String(), body)
    requestInfo.Header.Add("auth-type", "use-basic")
    requestInfo.SetBasicAuth(c.cfg.username, c.cfg.password)
    return requestInfo, nil
}
鉴权使用的是BasicAuth鉴权, 使用ak/sk作为 userName 和 password
注意: 请求的时候使用https协议请求, 并且在header中增加参数: "auth-type":"use-basic"

postman请求方式

postman settingspostman settingspostman settings

签名版本V1

简介

对于每一次 HTTP 或者 HTTPS 协议请求，我们会根据访问中的签名信息验证访问请求者身份。具体采用 AK（AccessKeyId）/SK（SecretAccessKey）/SIGN（Signature）的形式做访问限制。媒体处理服务通过使用 AccessKeyId 和 SecretAccessKey 进行对称加密的方法来验证请求的发送者身份。

  • 您可以在公有云服务控制台申请 AK/SK 密钥对。

    说明：您可以同时申请多组 AK/SK 密钥对，也可以设置某个 AK/SK 密钥对失效。

  • 在您获取 AK/SK 密钥对后，可根据特定的签名算法或签名 SDK 生成带签名的请求。

签名方法

为了通过 API 请求的安全验证，您需要在客户端对其 API 请求进行签名（即生成正确的数字签名），并且使用 HTTP 头 Authorization 在网络上传输该请求的数字签名。Authorization 头的具体格式如下：

Authorization:Visionular AccessKeyId={AK}, Signature={SIGN}

如上格式所示，Authorization 头的值包含访问密钥对中的 AccessKeyId，且与之对应的 SecretAccessKey 将用于 Signature 值的构造。下面将详细解释如何构造 Signature 值。

  1. 准备访问密钥对

    为 API 请求生成签名，需使用一对 AK/SK 访问密钥对。

    您可以在媒体处理服务控制台新建访问密钥对，也可以使用已经存在的访问密钥对。但是需要保证使用的密钥对处于启用状态。

  2. 生成请求的签名字符串

    API 的签名字符串由 HTTP 请求中的 Method、Header 和 Body 信息生成，具体方式如下：

    StringToSign = VERB + "\n"
              + Content-Md5 + "\n"
              + Content-Type + "\n"
              + Date + "\n"
              + CanonicalizedHeaders + "\n"
              + CanonicalizedResource

    说明：上述公式中的\n 表示换行转义字符，+（加号）表示字符串连接操作，其他各个参数的定义如下表所示。

    参数名称是否必选参数说明   示例
    VERB是HTTP 请求的方法名称，全部由大写字母组成，主要有 PUT、GET、POST、HEAD、DELETE 等。GET
    Content-Md5否HTTP 请求中 Body 部分的 MD5 值（必须为大写字符串），若 Body 为空则设置为空字符串。0DAC79A8541E0CD9E3AAD913E1119821
    Content-Type否HTTP 请求中 Body 部分的类型，非 GET 请求且有 Body 参数时请设置为application/json，否则设置为空字符串。application/json
    Date是HTTP 请求中的标准时间戳，遵循 RFC 1123 格式，使用 GMT 标准时间。Thu, 14 May 2020 16:17:40 GMT
    CanonicalizedHeaders否由 HTTP 请求中以 X-Wz- 为前缀的自定义构造的字符串。目前仅支持X-Wz-Nonce（签名随机字符串）。
    关于 CanonicalizedHeaders 的具体构建方法请参见CanonicalizedHeaders 的构造方式。    		60d0bd7e-95bb-11ea-b1d2-005056400001
    CanonicalizedResource是由 HTTP 请求资源构造的字符串。
    关于 CanonicalizedResource 的具体构建方法请参见CanonicalizedResource 的构造方式。    		/vodencoding/v1/create_task

    对于部分无 Body 的 HTTP 请求，其 Content-Md5 和 Content-Type 两个域为空字符串，这时整个签名字符串的生成方式如下：

    StringToSign = VERB + "\n"
                 + "\n"
                 + "\n"
                 + Date + "\n"
                 + CanonicalizedHeaders + "\n"
                 + CanonicalizedResource

    • CanonicalizedHeaders 的构造方式

      所有以 x-wz-为前缀的 HTTP Header 被称为 CanonicalizedHeaders，构建方法如下：

      1. 将所有以X-Wz-为前缀的 HTTP 请求头的名称转换为小写的形式。

        例如：将X-Wz-Nonce: WEIZHEN转换成x-wz-nonce: WEIZHEN。

      2. 将上一步得到的所有自定义请求头按照字典顺序进行升序排序。

      3. 删除请求头和内容之间分隔符两端出现的任何空格，并用:连接。

        例如：将X-Wz-Nonce: WEIZHEN转换成x-wz-nonce:WEIZHEN。

      4. 将所有的头和内容用\n 分隔符组合成最后的 CanonicalizedHeader。

      说明：若 CanonicalizedHeaders 规定的 HTTP 请求头不存在，则整个 CanonicalizedHeader 设置为空字符串

    • CanonicalizedResource 的构造方式

      请求中想访问的目标资源被称为 CanonicalizedResource，构建方法如下：

      1. 将 CanonicalizedResource 设置为空字符串""。

      2. 放入要访问的 API 资源，如 /vodencoding/v1/create_task 。

      3. 如果请求包含查询字符串QUERY_STRING，则在 CanonicalizedResource 字符串尾部添加 ? 和查询字符串。

        说明：QUERY_STRING 是 URL 中请求参数按字典顺序排序后的字符串，其中参数名和值之间用=相隔组成字符串，并对参数名-值对按照字典顺序升序排序，然后以&符号连接构成字符串。其公式化描述如下：

        QUERY_STRING = "KEY1=VALUE1" + "&" + "KEY2=VALUE2"

        此时， CanonicalizedResource 为/vodencoding/v1/create_task?KEY1=VALUE1&KEY2=VALUE2。

  1. 生成请求的数字签名

    目前， API 只支持一种数字签名算法，即默认签名算法 hmac-sha1。其完整签名公式如下：

    Signature = Base64( HMAC-SHA1( SecretAccessKey, UTF-8-Encoding-Of(StringToSign) ) )

    说明：签名的方法用 RFC 2104 中定义的 HMAC-SHA1 方法。如上公式用的 SecretAccessKey 必须和最终的 Authorization 头中使用的 AccessKeyId 相对应。否则，请求将无法通过服务端验证。

签名示例

假设 AccessKey ID 为uOzZM******PJGuP，AccessKeySecret 为CVa7na1HIUL******y1QfNwQW37vP3。

  1. 想要发送的 HTTP 请求为:

    POST /vodencoding/v1/create_task HTTP/1.1
     Host: 0.0.0.0:8888
     User-Agent: python-requests/2.18.4
     Accept-Encoding: gzip, deflate
     Accept: */*
     Connection: keep-alive
     Content-Type: application/json
     Date: Wed, 08 Dec 2021 06:30:03 GMT
     X-Wz-Nonce: 46d10994-57f0-11ec-a857-005056400001
     Content-Md5: 6FBAED2F3D81D2EC725A53CE9A95FCAE
     Authorization: Visionular AccessKeyId=uOzZM******PJGuP, Signature=D039jOXvu******cYpDeb3wNY=
     Content-Length: 153
    

     {"template_name": "my_test_template", "storage_id": "6756ac47950eb89c", "input": "https://wz-test-s3.s3.amazonaws.com/input.mp4", "output": "output.mp4"}
    `

  2. 生成 MD5 值：

    Content-Md5 = "6FBAED2F3D81D2EC725A53CE9A95FCAE"

  3. 生成随机字符串:

    X-Wz-Nonce = "46d10994-57f0-11ec-a857-005056400001"

  4. 组装待签名字符串:

    StringToSign = "POST" + "\n"
                + "6FBAED2F3D81D2EC725A53CE9A95FCAE" + "\n"
                + "application/json" + "\n"
                + "Wed, 08 Dec 2021 06:30:03 GMT" + "\n"
                + "x-wz-nonce:46d10994-57f0-11ec-a857-005056400001" + "\n"
                + "/vodencoding/v1/create_task" + "\n"

  5. 根据签名公式Signature = Base64( HMAC-SHA1( SecretAccessKey, UTF-8-Encoding-Of(StringToSign) ) )生成请求的数字签名:

    Signature = "D039jOXvu******cYpDeb3wNY="

  6. 得到签名后的 HTTP 请求为:

    POST /vodencoding/v1/create_task HTTP/1.1
    Host: 0.0.0.0:8888
    User-Agent: python-requests/2.18.4
    Accept-Encoding: gzip, deflate
    Accept: */*
    Connection: keep-alive
    Content-Type: application/json
    Date: Wed, 08 Dec 2021 06:30:03 GMT
    X-Wz-Nonce: 46d10994-57f0-11ec-a857-005056400001
    Content-Md5: 6FBAED2F3D81D2EC725A53CE9A95FCAE
    Authorization: Visionular AccessKeyId=uOzZM******PJGuP, Signature=D039jOXvu******cYpDeb3wNY=
    Content-Length: 153
    

    {"template_name": "my_test_template", "storage_id": "6756ac47950eb89c", "input": "https://wz-test-s3.s3.amazonaws.com/input.mp4", "output": "output.mp4"}

API 错误码

本文列出了 API 错误码，您在 API 调用的过程中可以查看 API 错误码表来定位错误原因。

HTTP 请求返回数据采用统一格式，返回的 HTTP 状态码为 2xx，表示请求成功；返回 4xx 或 5xx，表示请求失败。

调用 API 服务后返回数据采用统一格式，返回的 API 错误码为 0 时，表示调用成功；返回 100x 或 200x，表示调用失败。返回的数据目前仅支持 JOSN 格式。

API 错误码描述说明
0success请求成功
1000internal error系统错误
1001lack param缺少参数
1002bad param请求参数无法解析
1003auth fail鉴权失败
1004empty result查询结果为空
1005operation fail操作失败
1006      duplicated entity重复请求(如果1天内曾有过创建转码任务请求参数完全相同的请求，则本次的请求会返回该错误)
1007bad source资源错误
2001upload fail文件上传失败
2002download fail文件下载失败
2003transcode fail转码失败
2004encryption error加密失败
2005drag errordrag 处理失败
2006md5 sign errormd5 命名失败

视频存储相关接口

add_storage

调用add_storage接口创建用于存储输出媒体文件的存储空间。

URI
/vodencoding/v1/add_storage

HTTP 方法
POST

请求参数

名称是否必填类型描述
region是string存储空间所在的地域，如 cn-zhangjiakou 、cn-hangzhou。
type是string存储空间所属云厂商类型，如 s3、oss、obs。
bucket是string存储空间名称。
prefix否string存储空间路径前缀。
storage_ak否string可访问存储空间的 AccessKey，若存储空间为私有访问则必须设置。
storage_sk否string可访问存储空间的 AccessSecretKey，若存储空间为私有访问则必须设置。
notify否string转码任务完成后通知回调的 URL。

请求示例

POST /vodencoding/v1/storage HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*
Content-Type: application/json
Content-Length: 419


{
  "type": "oss",
  "region": "cn-zhangjiakou",
  "bucket": "cloudhub-new",
  "storage_ak": "LTAI5t5******EWduEV3Pja",
  "storage_sk": "xqTJfWzDA******DFm9WOsBChCRF",
  "prefix": "wangxinyan-test/output/1646987895",
  "notify": ""
}

返回参数

名称类型描述
codeintAPI 错误码。
storage_idstring新建存储空间的 ID。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code": 0,
    "msg": "success",
    "data": {
        "storage_id": "a970c1****9cabd"
    }
    "request_id": "521****8-37f2-4fcf-b231-e3****915c9"
}

list_storage

调用list_storage接口查询存储空间列表。

URI
/vodencoding/v1/list_storage

HTTP 请求方式
GET

请求参数
None

请求示例

GET /vodencoding/v1/list_storage HTTP/1.1

返回参数

名称类型描述
codeintAPI 错误码。
listjson array存储空间列表。
bucketstring存储空间名称。
created_timeint存储空间创建的时间。
prefixstring输出文件目录或前缀。
regionstring存储空间所在的地域，如 cn-zhangjiakou 、cn-hangzhou。
storage_idstring存储空间 ID。
typestring存储空间所属云厂商类型，如 s3、oss、obs。
notifystring转码任务完成后通知回调的 URL。
numint列表中存储空间数量。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code": 0,
    "data": {
        "list": [
            {
                "bucket":"cloudhub-new",
                "created_time":1646987896,
                "prefix":"wangxinyan-test/output/1646987895",
                "region":"cn-zhangjiakou",
                "storage_id":"df522*****3461b0",
                "notify": "http://test.****.com/notify",
                "type":"oss"
            }
        ],
        "num": 1
    },
    "msg": "success"
    "request_id":"84****31-7bf8-4697-80e5-db77****5bfc
}

del_storage

调用del_storage接口删除存储空间。

URI
/vodencoding/v1/del_storage

HTTP 请求方法
DELETE

请求参数

名称是否必填类型描述
storage_id是string存储空间 ID。

请求示例

DELETE /vodencoding/v1/del_storage?storage_id=8c94****8c395d HTTP/1.1

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code": 0,
    "msg": "success"
    “request_id": "62****64-f9de-4915-8ea9-b3ab*****442"
}

转码模板相关接口

add_template

调用add_template接口创建转码参数模板。

URI
/vodencoding/v1/add_template

HTTP 请求方法
POST

请求参数

名称是否必填类型描述
template_name是string模板名称，在同一账号下需确保唯一。
format否string封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
vcodec否string视频编码格式。取值：
  • h264（默认值）
  • h265
acodec否string音频编码格式，取值：aac。
resolution否string分辨率，默认保持源分辨率。
framerate否int输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
quality否float输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_size否int一个 gop 的帧数。
audio_bitrate否int音频码率，单位 bps。
video_bitrate否int视频码率，单位 bps。
说明：该参数设置优先级高于参数quality，即设置该参数后，参数quality不生效。
audio_sample_rate否string音频目标采样率，单位 Hz，取值： 48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channels否int音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_time否int分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_type否string分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
encryption否json视频加密参数组，参考 add_template 接口中的 encryption 参数表。
description否string模板说明。
thumbnail否json缩略图参数组，参考 add_template 接口中的 thumbnail 参数表。
watermark_image否json array图片水印参数组，参考 add_template 接口中的 watermark_image 参数表。
watermark_text否json array文字水印参数组，参考 add_template 接口中的 watermark_text 参数表。
concat_fragment否json拼接片头片尾参数组，参考 add_template 接口中的 concat_fragment 参数表。
encryption
参数是否必填类型说明
provider是stringkey server 协议类型，取值：Normal, ExpressPlay, 默认为Normal.
mode是string加密方法：支持 AES-128、Sample AES，默认 AES-128
drm_systems是json array支持的 DRM system 列表：Widevine, FairPlay, 默认 ClearKey
key_url是string获取加密秘钥的 url，长度不超过 512
http_method否string访问加密秘钥 url 的 http 方法，可选 GET、POST、HEAD、PUT，默认为 GET
headers否json访问加密秘钥 url 的 http 头，key/value 参数对，最多不超过 10 对，每个 key 介于 1-64 个字符，每个 value 不多于 256 个字符

说明:

目标分辨率 Resolution 支持以下几种设置方式：

设置方式描述是否识别横竖屏是否允许小分辨率转大分辨率
${w}x${h}表示按照指定的宽${w}和高${h}转码。否是
${w}x-2表示宽按设置的值转码，高等比缩放。否是
-2x${h}表示高按设置的值转码，宽等比缩放。否是
0x0表示按源视频的分辨率转码。否否
${s}p公式中p为小写字母，表示设置目标视频短边为${s}，且长边等比缩放。若${s}比原视频短边大，则不改变视频分辨率。是否
${l}w公式中w为小写字母，表示设置目标视频长边为${l}，且短边等比缩放。若${l}比原视频长边大，则不改变视频分辨率。是否
${s}P公式中P为大写字母，表示设置目标视频短边为${s}，且长边等比缩放。是是
${l}W公式中W为大写字母，表示设置目标视频长边为${l}，且短边等比缩放。是是
${l}x${s}wp表示转码输出的视频短边和长边均不超过设置值，且保持等比缩放。${l} ≥ ${s} > 0
例如：设置1280x720wp，则转出的视频短边 ≤720 且长边 ≤1280。
  • 若原视频分辨率为 1280x960，则转码后分辨率为 960x720。
  • 若原视频分辨率为 720x1440，则转码后分辨率为 640x1280。
是否
${w}x${h}b表示补黑模式，目标视频按模板分辨率转码，若计算出转码后某一单边小于模板分辨率，则该边会填充黑边背景。否是
thumbnail
参数是否必填类型说明
start_point否int视频截图起始点秒数 >= 0 ,最大值10000,默认为0
interval是int缩略图之间的大概秒数。指定一个整数值。缩略图之间的实际间隔可以相差数秒， 0 < interval < = 10000
number是int截取图像的数量， 0 < 截图数量 <= 1000，系统最大截取数量 1000 张
width否int设置单帧截图或多帧截图输出的图片宽，单位：像素, 最大值2000
height否int设置单帧截图或多帧截图输出的图片高，单位：像素, 最大值2000

说明:

  • 缩略图文件存放在文件夹 thumbnail下, thumbnail文件夹和输出的视频文件在同一级目录.
  • 缩略图命名按照 00001.jpg、00002.jpg、00003.jpg 的规则来命名
  • 如果宽和高都不设置时，则缩略图的尺寸和源视频相同。
  • 如果只设置宽（或高）时，另一边会按照视频的分辨率保持比例不变，避免图像变形。
  • 建议您不要同时任意设置宽和高的值，以免引起图像比例失真。
watermark_image
参数是否必填类型说明
image_url是string图片水印url地址
image_size是string图片水印宽高，如指定分辨率100x100、单边自适应-2x100
image_offset是string图片水印坐标及透明度，格式为x=100:y=100:alpha=1，水印坐标指以视频屏幕左上角为原点，向x轴做水平位移和向y轴做垂直位移，支持使用表达式，如(W-w)/2:(H-h)/2表示视频中央位置，其中 W,H 表示视频的宽高，w,h 表示水印的宽高；水印透明度alpha传0代表透明，传1代表不透明
time_interval否string图片水印插入时间点，若不设置，则视频全程都有水印，若设置时间点如"1,15"，则水印在视频的第1秒出现，第15秒后消失
watermark_text
参数是否必填类型说明
content是string文字水印内容，支持中文、英文、数字、标点符号(仅支持!@,&*#~_)
font_size是string文字水印字号，传数字
font_color是string文字水印颜色，如红色可用英文red或颜色代码#FF0000
offset是string文字水印坐标及透明度，参考图片水印的描述
time_interval否string文字水印插入时间点，参考图片水印的描述
font_type否string文字水印字体，支持source_han_sans_sc(思源黑体)、source_han_serif_sc(思源宋体)
concat_fragment
参数是否必填类型说明
enable是bool是否开启拼接片头片尾
start是string片头视频地址
end是string片尾视频地址
mode否int转码模式，传0表示自适应转码，当片头片尾的编码、分辨率与模板一致则直接和正片拼接，若不一致则按模板转码后拼接(忽略水印参数)；传1表示强制转码，使用模板配置对片头片尾进行转码，然后和正片拼接。

说明:

  • 启用视频拼接的模板，分辨率必须为{w}x{h}b这种形式, 否则转码失败。
  • 启用视频拼接的多码率模板，必须设置强制转码，否则转码失败。

请求示例

POST /vodencoding/v1/add_template HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.101:8080
Accept: */*
Content-Type: application/json
Content-Length: 419


{
    "template_name": "H264_540P_mp4",
    "description": "测试模板--H264_540P_mp4",
    "format": "mp4",
    "vcodec": "h264",
    "framerate": 25,
    "gop_size": 50,
    "quality": 5,
    "resolution": "1280x720b",  
    "seg_time": 0,
    "seg_type": "",
    "video_bitrate": 700,
    "acodec": "aac",
    "audio_bitrate": 64000,
    "audio_channels": 2,
    "audio_sample_rate": "48k",
    "thumbnail": {
        "format": "jpg",
        "start_point": 1,
        "interval": 60,
        "number": 30,
        "width": 1280,
        "height": 720
    },
    "watermark": {
        "image": [
            {
                "image_url": "http://www.aaa.com/1.jpg", 
                "image_size": "100x-2", 
                "image_offset": "W-w-10:10:alpha=1", 
                "time_interval": "2,10"
            }
        ],
        "text": [
            {
              "content": "My Text Test", 
              "time_interval": "2,10", 
              "font_color": "red",
              "font_size": "12",
              "offset": "x=1:y=10:alpha=1",
              "font_type": "source_han_sans_sc" 
            }
        ]
    },
    "concat_fragment": {
        "enable": true, 
        "start": "http://bucket-1250000000.cos.ap-beijing.myqcloud.com/start.mp4", 
        "end": "http://bucket-1250000000.cos.ap-beijing.myqcloud.com/end.mp4", 
        "transcode": false 
    }
}

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code":0,
    "msg":"success"
    “request_id": "cb7****c-23bc-4a33-b44d-a18f****565"
}

query_template

调用query_template接口查询转码参数模板信息。

URI
/vodencoding/v1/query_template

HTTP 请求方式
GET

请求参数

名称是否必填类型描述
template_name是string模板名称，必须是账户下可用的模板。

请求示例

GET /vodencoding/v1/query_template?template_name=Template1646987898 HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*

返回参数

名称类型描述
codeintAPI 错误码。
template_namestring模板名称，在同一账号下需确保唯一。
trans_modestring转码方式，取值：
  • normal：常规转码
  • adaptive：多码率转码
formatstring封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
vcodecstring视频编码格式。取值：
  • h264（默认值）
  • h265
acodecstring音频编码格式，取值：aac。
resolutionstring分辨率，默认保持源分辨率。
framerateint输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
qualityfloat输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_sizeint一个 gop 的帧数。
audio_bitrateint音频码率，单位 bps。
video_bitrateint视频码率，单位 bps。
audio_sample_ratestring音频目标采样率，单位 Hz，取值：48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channelsint音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_timeint分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_typestring分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
descriptionstring模板说明。
encryptionjson视频加密参数组说明，参考add_template接口该参数的描述。
adaptive_streamsjson array多码率流配置说明，参考add_adaptive_template接口该参数的描述。
thumbnailjson缩略图说明，参考add_template接口该参数的描述。
watermark_imagejson array图片水印说明，参考add_template接口该参数的描述。
watermark_textjson array文本水印说明，参考add_template接口该参数的描述。
concat_fragmentjson拼接片头片尾说明，参考add_template接口该参数的描述。
created_atint模板创建时间。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
  "code":0,
  "msg":"success",
  "data":{
    "template_name":"Template1646987898",
    "trans_mode":"adaptive",
    "format":"hls",
    "vcodec":"h264",
    "acodec":"aac",
    "resolution":"0x0",
    "framerate":25,
    "quality":5,
    "gop_size":50,
    "audio_bitrate":2000,
    "video_bitrate":3000,
    "audio_sample_rate":"48k",
    "audio_channels":3,
    "seg_time":10,
    "seg_type":"fmp4",
    "description":"接口测试模板",
    "encryption":{
      "provider":"ExpressPlay",
      "mode":"AES-128",
      "drm_systems":["Widevine","FairPlay"],
      "key_url":"https://wz.shike.press/tools/drm.php",
      "http_method":"POST"
    },
    "adaptive_streams":[
      {
        "vcodec":"h264",
        "resolution":"720p"
      },
      {
        "vcodec":"h264",
        "resolution":"360p"
      }
    ],
    "thumbnail":{
      "start_point":1,
      "interval":2,
      "number":5,
      "height":480
    },
    "watermark_image":[{
      "image_url":"https://xxx.com/test.jpg",
      "image_size":"320x-2",
      "image_offset":"(W-w)/2:(H-h)/2:alpha=0.5",
      "time_interval":"0,16"
    }],
    "watermark_text":[{
      "content":"test text",
      "font_color":"green",
      "font_size":"40",
      "offset":"x=150:y=300:alpha=1",
      "time_interval":"0,13",
      "font_type":"source_han_serif_sc"
    }],
    "concat_fragment":{
      "enable":true,
      "start":"https://xxx.com/start.mp4",
      "end":"https://xxx.com/end.mp4",
      "mode":0
    },
    "created_at":1646987901
  },
  "request_id":"c6f****b-96cf-4858-a54a-84f*****0426"
}

update_template

调用update_template接口编辑转码参数模板。

URI
/vodencoding/v1/update_template

HTTP 请求方式
PUT

请求参数

名称是否必填类型描述
template_name是string模板名称，必须是账户下可用的模板。
format否string封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
vcodec否string视频编码格式。取值：
  • h264（默认值）
  • h265
acodec否string音频编码格式，取值：aac。
resolution否string分辨率，默认保持源分辨率。参考 add_template 接口中的该参数说明
framerate否int输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
quality否float输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_size否int一个 gop 的帧数。
audio_bitrate否int音频码率，单位 bps。
video_bitrate否int视频码率，单位 bps。
说明：该参数设置优先级高于参数quality，即设置该参数后，参数quality不生效。
audio_sample_rate否string音频目标采样率，单位 Hz，取值：48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channels否int音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_time否int分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_type否string分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
encryption否json视频加密参数组，参考 add_template 接口中的 encryption 参数表。
description否string模板说明。
thumbnail否json缩略图说明，参考 add_template 接口中的 thumbnail 参数表
watermark_image否json array图片水印参数组，参考 add_template 接口中的 watermark_image 参数表。
watermark_text否json array文字水印参数组，参考 add_template 接口中的 watermark_text 参数表。
concat_fragment否json拼接片头片尾参数组，参考 add_template 接口中的 concat_fragment 参数表。

请求示例

POST /vodencoding/v1/update_template HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.101:8080
Accept: */*
Content-Type: application/json
Content-Length: 419


{
  "acodec":"aac",
  "audio_bitrate":0,
  "audio_channels":0,
  "audio_sample_rate":"48k",
  "description":"接口测试模板",
  "format":"mp4",
  "framerate":25,
  "gop_size":50,
  "quality":5,
  "resolution":"0x0",
  "seg_time":10,
  "seg_type":"fmp4",
  "template_name":"Template1646987898",
  "vcodec":"h264",
  "video_bitrate":3000,
  "thumbnail":{
    "format": "jpg",
    "start_point": 1,
    "interval": 60,
    "number": 30,
    "width": 1280,
    "height": 720
  },
  "watermark_image":[{
    "image_url": "https://xxx.com/test.png", 
    "image_size": "100x-2",
    "image_offset": "W-w-10:10:alpha=1",
    "time_interval": "2,10"
  }],
  "watermark_text":[{
    "content": "My Text Test",
    "time_interval": "2,10",
    "font_color": "red",
    "font_size": "12",
    "offset": "x=1:y=10:alpha=1",
    "font_type": "source_han_sans_sc"
  }],
  "concat_fragment":{
    "enable": true,
    "start": "http://xxx.com/start.mp4",
    "end": "http://xxx.com/end.mp4",
    "mode": 0,
  }
}

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code":0,
    "msg":"success"
    “request_id": "c6f****b-96cf-4858-a54a-84f*****0426"
}

list_template

调用list_template接口查询转码参数模板列表。

URI
/vodencoding/v1/list_template

HTTP 请求方式
GET

请求参数
None

请求示例

GET /vodencoding/v1/list_template HTTP/1.1

返回参数

名称类型描述
codeintAPI 错误码。
listjson array模板列表内容。
template_namestring模板名称，在同一账号下需确保唯一。
trans_modestring转码方式，取值：
  • normal：常规转码
  • adaptive：多码率转码
formatstring封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
vcodecstring视频编码格式。取值：
  • h264（默认值）
  • h265
acodecstring音频编码格式，取值：aac。
resolutionstring分辨率，默认保持源分辨率。
framerateint输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
qualityfloat输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_sizeint一个 gop 的帧数。
audio_bitrateint音频码率，单位 bps。
video_bitrateint视频码率，单位 bps。
audio_sample_ratestring音频目标采样率，单位 Hz，取值：48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channelsint音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_timeint分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_typestring分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
descriptionstring模板说明。
thumbnailjson缩略图说明。
watermark_imagejson array图片水印参数组，参考 add_template 接口中的 watermark_image 参数表。
watermark_textjson array文字水印参数组，参考 add_template 接口中的 watermark_text 参数表。
concat_fragmentjson拼接片头片尾参数组，参考 add_template 接口中的 concat_fragment 参数表。
created_atint模板创建时间。
numint列表中转码参数模板数量。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code": 0,
    "data": {
      "num": 2,
      "list": [
        {
          "template_name":"Template1646987898",
          "trans_mode":"adaptive",
          "format":"hls",
          "vcodec":"h264",
          "acodec":"aac",
          "resolution":"0x0",
          "framerate":25,
          "quality":5,
          "gop_size":50,
          "audio_bitrate":2000,
          "video_bitrate":3000,
          "audio_sample_rate":"48k",
          "audio_channels":3,
          "seg_time":10,
          "seg_type":"fmp4",
          "description":"接口测试模板",
          "encryption":{
            "provider":"ExpressPlay",
            "mode":"AES-128",
            "drm_systems":["Widevine","FairPlay"],
            "key_url":"https://wz.shike.press/tools/drm.php",
            "http_method":"POST"
          },
          "adaptive_streams":[
            {
              "vcodec":"h264",
              "resolution":"720p"
            },
            {
              "vcodec":"h264",
              "resolution":"360p"
            }
          ],
          "thumbnail":{
            "start_point":1,
            "interval":2,
            "number":5,
            "height":480
          },
          "watermark_image":[{
            "image_url":"https://xxx.com/test.jpg",
            "image_size":"320x-2",
            "image_offset":"(W-w)/2:(H-h)/2:alpha=0.5",
            "time_interval":"0,16"
          }],
          "watermark_text":[{
            "content":"test text",
            "font_color":"green",
            "font_size":"40",
            "offset":"x=150:y=300:alpha=1",
            "time_interval":"0,13",
            "font_type":"source_han_serif_sc"
          }],
          "concat_fragment":{
            "enable":true,
            "start":"https://xxx.com/start.mp4",
            "end":"https://xxx.com/end.mp4",
            "mode":0
          },
          "created_at":1646987901
        },
        {
          "template_name":"wztest_liveq1234",
          "trans_mode":"normal",
          "format":"mp4",
          "vcodec":"h264",
          "acodec":"aac",
          "resolution":"720P",
          "framerate":25,
          "quality":5,
          "video_bitrate":32000,
          "gop_size":250,
          "seg_type":"10",
          "seg_time":1234567,
          "audio_bitrate":32000,
          "audio_sample_rate":"96k",
          "audio_channels":2,
          "description":"wx doc",
          "created_at":1646722741
        }
    	]
	},
	"msg": "success"
	"request_id":"c54****7-5ab0-4a79-b9be-e3f*****6b7f"
}

add_adaptive_template

调用add_adaptive_template接口新增多码率转码模板。

URI
/vodencoding/v1/add_adaptive_template

HTTP 请求方法
POST

请求参数
名称是否必填类型描述
template_name是string模板名称，在同一账号下需确保唯一。
adaptive_streams是json array多路码率参数设置，具体参数解释请参见[adaptive_streams](# adaptive_streams)。
format否string封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
acodec否string音频编码格式，取值：aac。
resolution否string分辨率，默认保持源分辨率。
framerate否int输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
quality否float输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_size否int一个 gop 的帧数。
audio_bitrate否int音频码率，单位 bps。
video_bitrate否int视频码率，单位 bps。
说明：该参数设置优先级高于参数quality，即设置该参数后，参数quality不生效。
audio_sample_rate否string音频目标采样率，单位 Hz，取值：48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channels否int音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_time否int分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_type否string分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
encryption否json视频加密参数组，参考 add_template 接口中的 encryption 参数表。
description否string模板说明。
thumbnail否json缩略图说明。
watermark_image否json array图片水印参数组，参考 add_template 接口中的 watermark_image 参数表。
watermark_text否json array文字水印参数组，参考 add_template 接口中的 watermark_text 参数表。
concat_fragment否json拼接片头片尾参数组，参考 add_template 接口中的 concat_fragment 参数表。
adaptive_streams
参数是否必填类型说明
vcodec是string当前视频流的视频编码格式，取值：h264、h265。
resolution否string当前视频流的分辨率。
默认当前视频流分辨率与源保持一致。
quality否float当前视频流输出的视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
audio_bitrate否int当前视频流的音频码率，单位 bps。
video_bitrate否int当前视频流的视频码率，单位 bps。
说明：该参数设置优先级高于参数quality，即设置该参数后，参数quality不生效。
请求示例
GET /vodencoding/v1/add_adaptive_template HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*


{
   "acodec":"aac",
   "adaptive_streams":[
     {
       "vcodec": "h264",
       "quality": 5,
       "resolution": "720P",
       "video_bitrate": 32000,
       "audio_bitrate":32000
     },
     {
       "vcodec": "h265",
       "quality": 56
     }
   ],
   "audio_bitrate":0,
   "audio_channels":0,
   "audio_sample_rate":"48k",
   "description":"接口测试多码率模板",
   "format":"hls",
   "framerate":25,
   "gop_size":50,
   "quality":5,
   "resolution":"0x0",
   "seg_time":10,
   "seg_type":"mpegts",
   "template_name":"HLS_Template16****7899",
   "vcodec":"h264",
   "video_bitrate":3000,
   "thumbnail":"",
   "watermark_image":"",
   "watermark_text":"",
   "concat_fragment":""
}

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code":0,
    "msg":"success"
    “request_id": "19e****9-dcde-40f7-bd81-acf*****096a"
}

update_adaptive_template

调用update_adaptive_template接口更新多码率转码模板。

URI
/vodencoding/v1/update_adaptive_template

HTTP 请求方法
PUT

请求参数

名称是否必填类型描述
template_name是string模板名称，必须是账户下可用的模板。
adaptive_streams否json array多路码率参数设置，参考add_adaptive_template接口该参数的说明。
format否string封装格式。取值：
  • mp4（默认值）
  • hls
  • flv
  • dash
acodec否string音频编码格式，取值：aac。
resolution否string分辨率，默认保持源分辨率。
framerate否int输出视频帧率，取值：0~120，默认值 0（即保持源帧率）。
quality否float输出视频质量等级，取值：1-10，默认值 5。等级越高质量越高。
gop_size否int一个 gop 的帧数。
audio_bitrate否int音频码率，单位 bps。
video_bitrate否int视频码率，单位 bps。
说明：该参数设置优先级高于参数quality，即设置该参数后，参数quality不生效。
audio_sample_rate否string音频目标采样率，单位 Hz，取值：48k、44.1k、32k。
说明：若该参数设置为空或者不传入该参数，则表示音频目标采样率与源保持一致。
audio_channels否int音频目标通道数，取值：
  • 1
  • 2
  • 6
说明：若该参数设置为 0 或者不传入该参数，则表示音频目标通道数与源保持一致。
seg_time否int分片时长。当封装格式format设置为hls或dash时，需要设置该参数，单位为秒。
默认为视频关键帧之间的间隔秒数，建议设置为关键帧之间的间隔秒数的整数倍。
seg_type否string分片格式。当封装格式format设置为hls或dash时，需要设置该参数。
取值：
  • 当format设置为hls时
    • mpegts
    • fmp4
  • 当format设置为dash时
    • mp4
    • webm
encryption否json视频加密参数组，参考 add_template 接口中的 encryption 参数表。
description否string模板说明。
thumbnail否json缩略图说明。
watermark_image否json array图片水印参数组，参考 add_template 接口中的 watermark_image 参数表。
watermark_text否json array文字水印参数组，参考 add_template 接口中的 watermark_text 参数表。
concat_fragment否json拼接片头片尾参数组，参考 add_template 接口中的 concat_fragment 参数表。

请求示例

PUT /vodencoding/v1/update_adaptive_template HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*
Content-Type: application/json
Content-Length: 419


{
   "acodec":"aac",
   "adaptive_streams":[
     {
       "vcodec": "h264",
       "quality": 5,
       "resolution": "720P",
       "video_bitrate": 32000,
       "audio_bitrate":32000
     },
     {
       "vcodec": "h265",
       "quality": 56
     }
   ],
   "audio_bitrate":0,
   "audio_channels":0,
   "audio_sample_rate":"48k",
   "description":"接口测试多码率模板",
   "format":"hls",
   "framerate":25,
   "gop_size":50,
   "quality":5,
   "resolution":"0x0",
   "seg_time":10,
   "seg_type":"mpegts",
   "template_name":"HLS_Template16****7899",
   "vcodec":"h264",
   "video_bitrate":3000,
   "thumbnail":"",
   "watermark_image":"",
   "watermark_text":"",
   "concat_fragment":""
}

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
   "code":0,
   "msg":"success",
   "request_id":"65****4c-bcbe-4605-a2af-5b*****4df24"
}

del_template

调用del_template接口删除转码参数模板。

URI
/vodencoding/v1/del_template

HTTP 请求方法
DELETE

请求参数

名称是否必填类型描述
template_name是string模板名称，必须是账户下可用的模板。

请求示例

DELETE /vodencoding/v1/del_template?template_name=3cba1d67&template_name=wz_live HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*

返回参数

名称类型描述
codeintAPI 错误码。
msgstringAPI 错误码描述。
resquest_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 11 Aug 2020 07:49:56 GMT
Content-Length: 23


{
    "code": 0,
    "msg": "success"
    "request_id": "d7aa****-c9d1-43d0-9030-aba****703bc"
}

转码任务相关接口

create_task

调用create_task接口创建转码任务。

说明：多模版转码时，需要多次调用接口，一个转码任务只能使用一个模板。

URI
/vodencoding/v1/create_task

HTTP 请求方式
POST

请求参数

名称是否必填类型描述
template_name是string转码模板名称。
input是string目标视频所在的地址。
output是string目标视频转码后输出路径。
storage_id是string用于存储输出媒体文件的存储空间 ID。

请求示例

POST /vodencoding/v1/create_task HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*
Content-Type: application/json
Content-Length: 207


{
   "input":"https://cloudhub-new.oss-cn-zhangjiakou.aliyuncs.com/wangxinyan-test/test.mp4",
   "output":"test01.mp4",
   "storage_id":"df5*****3461b0",
   "template_name":"Template16***7898"
}

返回参数

名称类型描述
codeintAPI 错误码。
task_idstring转码任务 ID。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code": 0,
    "data": {
        "task_id": "202203110******71150f38b9cc9a"
     },
    "msg": "success"
    "request_id": "d7aa****-c9d1-43d0-9030-aba****703bc"
}

query_task

调用query_task接口查询转码任务详情。

URI
/vodencoding/v1/query_task

HTTP 请求方式
GET

请求参数

名称是否必填类型描述
task_id是string转码任务 ID，ID 可以包含数字、字母、下划线、横杠。

请求示例

GET /vodencoding/v1/query_task?task_id=202008111******371038e8555b HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*

返回参数

名称类型描述
codeintAPI 错误码。
source_bitratefloat输入视频的码率，单位 kbps。
output_bitratefloat输出视频的码率，单位 kbps。
created_timeint转码任务创建的时间。
started_timeint转码任务开始的时间
finished_timeint转码任务结束的时间。
inputstring目标视频所在路径。
outputstring目标视频转码后输出路径。
statusstring目标转码任务状态，取值：
  • pending：表示等待
  • running：表示正在转码
  • downloading：正在下载目标视频
  • uploading：正在上传目标视频
  • succeeded：转码成功
  • failed：转码失败
template_namestring转码参数模板名称。
task_idstring转码任务 ID。
storage_idstring用于存储输出媒体文件的存储空间 ID。
regionstring地域。
durationfloat片源视频时长。
source_sizebigint源视频大小。
source_resolutionstring源视频分辨率。
source_framerateint源视频帧率。
output_sizebigint输出视频大小。
output_resolutionstring输出视频分辨率。
output_framerateint输出视频帧率。
code（data.list.code）int转码任务错误码。
messagestring转码任务错误码描述。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json


{
    "code":0,
    "msg":"success",
    "data":{
        "task_id":"20220311083823657571150f38b9cc9a",
        "input":"https://cloudhub-new.oss-cn-zhangjiakou.aliyuncs.com/wangxinyan-test/test.mp4",
        "output":"oss://cloudhub-new/wangxinyan-test/output/1646987895/test01.mp4",
        "template_name":"Template1646987898",
        "storage_id":"df522bdccb3461b0",
        "region":"cn-hangzhou",
        "created_time":1646987903,
        "started_time":1646987903,
        "finished_time":0,
        "status":"running",
        "duration":0,
        "source_bitrate":0,
        "source_size":0,
        "source_resolution":"",
        "source_framerate":0,
        "output_size":0,
        "output_resolution":"",
        "output_framerate":0,
        "output_bitrate":0,
        "code":0,
        "message":"running"
        },
    "request_id":"43****1-5e05-4899-bbd2-29d5*****358"
}

list_task

调用list_task接口查询转码任务列表。

说明：支持按时间查询，转码任务的状态查询。

URI
/vodencoding/v1/list_task

HTTP 请求方式
GET

请求参数

名称是否必填类型描述
start_time否int按时间查询时，指定查询转码记录的起始时间，unix 时间戳，10 位。
end_time否int按时间查询时，指定查询转码记录的终止时间，unix 时间戳，10 位。
status否string指定目标转码任务的状态，取值：
  • 空：表示查询所有转码状态的任务（默认值）
  • pending：表示等待
  • running：表示正在转码
  • downloading：正在下载目标视频
  • uploading：正在上传目标视频
  • succeeded：转码成功
  • failed：转码失败
start_num否int从第 N 条记录开始搜索，默认值为 0。
count否int返回的最大记录数，默认值为 50, 最大值200。

请求示例

GET /vodencoding/v1/list_task?count=10&end_time=1649246173&start_time=1649159773 HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.168.1.101:8080
Accept: */*

返回参数

名称类型描述
codeintAPI 错误码。
listjosn array转码任务列表。
source_bitratefloat输入视频的码率，单位 kbps。
output_bitratefloat输出视频的码率，单位 kbps。
created_timeint转码任务创建的时间。
started_timeint转码任务开始的时间。
finished_timeint转码任务结束的时间。
inputstring目标视频所在路径。
outputstring目标视频转码后输出路径。
statusstring目标转码任务状态，取值：
  • pending：表示等待
  • running：表示正在转码
  • downloading：正在下载目标视频
  • uploading：正在上传目标视频
  • succeeded：转码成功
  • failed：转码失败
template_namestring转码参数模板名称。
task_idstring转码任务 ID。
storage_idstring用于存储输出媒体文件的存储空间 ID。
regionstring地域。
durationfloat片源视频时长。
source_sizebigint源视频大小。
source_resolutionstring源视频分辨率。
source_framerateint源视频帧率。
output_sizebigint输出视频大小。
output_resolutionstring输出视频分辨率。
output_framerateint输出视频帧率。
code（data.list.code）int转码任务错误码。
messagestring转码任务错误码描述。
totalint指定查询时间段且在指定转码状态下的查询记录总数。
numint本次查询返回的实际转码任务记录数。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 11 Aug 2020 09:38:46 GMT
Content-Length: 105


{
  "code":0,
  "msg":"success",
  "data":{
  "list":[
  {
    "task_id":"20220311083823657571150f38b9cc9a",
    "input":"https://cloudhub-new.oss-cn-zhangjiakou.aliyuncs.com/wangxinyan-test/test.mp4"
    "output":"oss://cloudhub-new/wangxinyan-test/output/1646987895/test01.mp4",
    "template_name":"Template1646987898",
    "storage_id":"df522bdccb3461b0",
    "region":"cn-hangzhou",
    "created_time":1646987903,
    "started_time":1646987903,
    "finished_time":1646987906,
    "status":"succeeded",
    "duration":30,
    "source_bitrate":193.95,
    "source_size":727324,
    "source_resolution":"960x540",
    "source_framerate":25,
    "output_size":906197,
    "output_resolution":"960x540",
    "output_framerate":25,
    "output_bitrate":241.65,
    "code":0,
    "message":"succeeded"
    },
  {
    "task_id":"20211230000252019045617d685fd291",
    "input":"http://x.com/t.mp4",
    "output":"oss://c/t/i.mp4",
    "template_name":"Template1640944948",
    "storage_id":"b63ab68fef7e4288",
    "region":"cn-hangzhou",
    "region":"cn-hangzhou",
    "created_time":0,
    "started_time":0,
    "finished_time":0,
    "status":"failed",
    "duration":5,
    "source_bitrate":2,
    "source_resolution":"10p",
    "source_framerate":2.1,
    "output_size":0,
    "output_resolution":"",
    "output_framerate":0,
    "output_bitrate":0,
    "code":0,
    "message":"test"
    }
    ],
  "num":2,
  "total":2
  },
  "request_id":"9e****4-ebd0-47ed-9722-73c*****58f6"
}

回调接口说明

回调请求：

HTTP POST 请求，包体内容为 JSON, JSON 格式如下:

{


    "code": 0,
    "msg": "Succeeded",
    "callback_url": "http://xxx.com/notify",
    "data": [
        {
            "task_id": "20220420111542664667cccc3d179880",
            "input": "https://xxxx.xxx.com/xxx/test.mp4",
            "output": "oss://hztst/vangzinyan_test/output/test159.mp4",
            "format": "mp4",
            "status": "succeeded",
            "duration": 30,
            "spend_time": 2
        },
        {
            "task_id": "20220420111542664667cccc3d179780",
            "input": "https://xxxx.xxx.com/xxx/test.mp4",
            "output": "oss://hztst/vangzinyan_test/output/test159.mp4",
            "format": "mp4",
            "status": "failed",
            "duration": 30,
            "spend_time": 2
        }
    ]
}

回调参数说明:

名称类型描述
codeint回调状态码,固定值: 0。
msgstring回调任务状态描述, 本次回调的任务全部转码成功,取值succeeded;有一条失败,取值failed。
datajosn array回调转码任务信息。
task_idstring转码任务ID。
inputstring输入视频地址。
outputstring视频转码后输出地址。
formatstring视频格式: mp4/hls/dash/flv
statusstring转码任务状态，取值：
  • succeeded：转码成功
  • failed：转码失败
durationfloat转码后视频的时长, 单位: 秒
spend_timefloat转码耗时, 单位: 秒

回调接口响应：

HTTP STATUS CODE = 200，服务端忽略应答包具体内容，如果状态码异常，会重试 3 次，每次间隔 5 秒。

第三方接口

加密秘钥获取接口

转码模板参数 encryption.key_url 对应的接口，执行带视频加密的转码任务时访问该接口获取加密秘钥。

URI
自定义

HTTP 请求方法
转码模板参数 encryption.http_method 指定的方法，支持 GET、POST、HEAD、PUT，默认为 GET

请求参数

名称是否必填类型描述

请求示例

GET /customer/secret HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*

返回参数

名称类型描述
statusstring返回状态码，成功：SUCCESS，失败：FAILURE。必选项。
reasonstring错误描述。
trace_idstring追溯 ID。
datajson秘钥信息参数。
data.secret_keystring加密秘钥明文，必须使用 Hex 编码格式。必选项。
data.auth_urlstring解密认证获取秘钥的 url 地址。必选项。
data.ciphertextstring被加密的加密秘钥，用于追加为 auth_url 的参数，为空时忽略。

返回示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 11 Aug 2020 07:49:56 GMT
Content-Length: 266


{
  "status": "SUCCESS",
  "reason": "",
  "data": {
    "secret_key": "56177471A553431F2E43724AE3E3B89A",
    "ciphertext": "d8sZTBA/MYfwEpt15r8/+5sSK5h7wW2xF5y7d5ejfU4",
    "auth_url": "https://xxx/hls/key"
  },
  "trace_id": "9716b39f8e566dccf279662290258fe6"
}
7/16/2024 09:19:41