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查询转码任务列表。
retry callback调用retry/task/callback查询转码任务列表。

请求结构

本文为您介绍了媒体处理服务 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 settings

postman settings

postman 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 entitysession_id 重复
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: text/plain; charset=utf-8


{
    "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

说明:

  • 缩略图文件存放在文件夹 {output_name}_thumbnail下, {output_name}_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: text/plain; charset=utf-8


{
  "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: text/plain; charset=utf-8


{
    "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。
pipeline否string管道 id，一般不需要设置。
extra_options否object任务扩展配置。
session_id否string用于去重的识别码，如果24小时内曾有过相同的识别码的请求，则本次的请求会返回之前重复的taskid，错误码为1006。最长 50 个字符，不传该参数或者参数为空字符串则本次请求不做去重操作。
custom_info否string自定义信息，可通过任务回调和任务查询获取，长度限制为2048个字符。

请求示例

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",
    "pipeline": "5f2631056b3d4b91acaef61bfb50e0c4",
    "extra_options": {
        "session_id": "d6d4xxxx0f1",
        "custom_info": "test for ios"
    }
}

返回参数

名称类型描述
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_frameratefloat源视频帧率。
output_sizebigint输出视频大小。
output_resolutionstring输出视频分辨率。
output_frameratefloat输出视频帧率。
code（data.list.code）int转码任务错误码。
messagestring转码任务错误码描述。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8


{
    "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_frameratefloat源视频帧率。
output_sizebigint输出视频大小。
output_resolutionstring输出视频分辨率。
output_frameratefloat输出视频帧率。
code（data.list.code）int转码任务错误码。
messagestring转码任务错误码描述。
totalint指定查询时间段且在指定转码状态下的查询记录总数。
numint本次查询返回的实际转码任务记录数。
msgstringAPI 错误码描述。
request_idstring请求 ID。

返回示例

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8




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

retry_callback

重新触发任务回调接口，若任务通知失败，可调用此接口重新触发任务回调。

URI
/vodencoding/v1/retry/task/callback

HTTP 请求方式
POST

请求参数

名称是否必填类型描述
task_id是string转码任务 ID

请求示例

POST /vodencoding/v1/retry/task/callback HTTP/1.1
User-Agent: curl/7.29.0
Host: 192.*.*.*:8080
Accept: */*
Content-Type: application/json


{
  "task_id": "202510311539d426ffv9bua6xxxxxxx"
}

返回参数

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

返回示例

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


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

回调接口说明

回调请求：

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"
}
3/17/2026 02:37:07