对视频文件进行处理

最近更新时间:2019-06-11 17:57:37

接口名称

ProcessFile

功能说明

该接口是点播任务流相关接口中的一个。开发者可以通过该接口对单个视频发起多种处理任务,包括:

  1. 视频转码(包括水印、加密和转封装)。
  2. 视频转动图(如 gif)。
  3. 按时间点截图。
  4. 采样截图。
  5. 使用截图设置封面。
  6. 截取雪碧图。
  7. 智能分析(智能分类和智能标签)。
  8. 内容审核(鉴黄)。

该接口为异步接口,即:调用该接口只是发起一系列视频处理任务。任务流中的任务状态变更(包括结束)可以通过 事件通知 机制感知。

任务执行完毕之后,每项异步任务的执行结果(例如转码输出文件 URL)可以通过 GetVideoInfo 接口获得。

事件通知

任务流状态变更(或者处理完成)会触发 事件通知 - 任务流状态变更通知。App 后台可据此监听任务流的执行状态。

更多参见 服务端事件通知简介

请求方式

请求域名

vod.api.qcloud.com

最高调用频率

100次/分钟

请求参数说明

参数名称 必填 类型 说明
fileId String 文件 ID。
transcode Object 参见 转码控制参数
animatedGraphics Object 参见 转动图控制参数
sampleSnapshot Object 参见 采样截图控制参数
coverBySnapshot Object 参见 使用截图设置封面控制参数
snapshotByTimeOffset Object 参见 指定时间点截图控制参数
imageSprite Object 参见 雪碧图控制参数
classificationAIAnalysis Object 参见 智能分类控制参数
tagAIAnalysis Object 参见 智能标签控制参数
pornReview Object 参见 鉴黄审核控制参数
notifyMode String 任务流状态变更通知模式。
  • Finish:只有当任务流全部执行完毕时,才发起一次事件通知。
  • Change:只要任务流中每个子任务的状态发生变化,都进行事件通知。
  • None:不接受该任务流回调。
默认为 Finish。
priority Integer 任务流优先级,取值范围为[-10, 10],默认为0。
COMMON_PARAMS 参见 公共参数

说明:

对视频进行智能分类智能标签,需要满足原始视频小于100MB,视频封装格式必须为 MP4、FLV 和 AVI 三种封装格式。

transcode(转码控制参数)

参数名称 必填 类型 描述
definition Array 转码输出模板号,参见 转码参数模板
watermark Integer 参见 水印参数模板。填1表示使用控制台默认水印,指定水印则填写水印 ID(整数), 不填则不带水印。
hlsMasterPlaylist Integer 若指定的转码输出参数包含多种 HLS 规格,并且指定了 hlsMasterPlaylist = 1,那么转码结束后将生成包含 HLS Master Playlist 的多码率 HLS 文件,该文件的 definition 固定为10000。 使用支持 HLS 标准的播放器播放该文件,将能够实现根据码率自适应选择视频流播放。
idrAlignment Integer 转码后的文件是否 IDR 对齐。0:不对齐;1:对齐。默认0。
drm Object 视频加密控制参数,参见 视频加密解决方案
drm.definition Integer 加密方式,参见 视频加密参数模板
mosaicList Array 马赛克遮标列表,元素是单个遮标的 马赛克信息

任务流执行完毕之后,转码结果可以从 GetVideoInfo 接口应答包体中的 transcodeInfo 对象获取到。

animatedGraphics(转动图控制参数)

参数名称 必填 类型 描述
definition Array 转动图模板号,参见 转动图参数模板
startTime Integer 动图在视频中的开始时间,单位为秒。
endTime Integer 动图在视频中的结束时间,单位为秒。

任务流执行完毕之后,转动图结果可以从 GetVideoInfo 接口应答包体中的 animatedGraphicsInfo 对象获取到。

sampleSnapshot(采样截图控制参数)

参数名称 必填 类型 描述
definition Integer 采样截图模板号,参见 采样截图参数模板
watermarkDefinition Array 水印模板号,参见 水印参数模板

任务流执行完毕之后,截图 URL 可以从 GetVideoInfo 接口应答包体中的 sampleSnapshotInfo.imageUrls 字段中获取到。

snapshotByTimeOffset(指定时间点截图控制参数)

参数名称 必填 类型 描述
definition Integer 指定时间点截图模板号,参见 指定时间点截图参数模板
timeOffset Array 整形数组,截图的时间偏移,单位为毫秒。
watermarkDefinition Array 水印模板号,参见 水印参数模板

任务流执行完毕之后,时间点截图信息可以从 GetVideoInfo 接口应答包体中的 snapshotByTimeOffsetInfo 字段获取。

coverBySnapshot(使用截图设置视频封面控制参数)

参数名称 必填 类型 描述
definition Integer 指定时间点截图模板号,参见 指定时间点截图参数模板
positionType String 截图方式。Time:依照时间点截图;Percent:依照百分比截图。
position Integer 截图位置。对于依照时间点截图,该值表示指定视频第几秒的截图作为封面;对于依照百分比截图,该值表示使用视频百分之多少的截图作为封面。
watermarkDefinition Array 水印模板号,参见 水印参数模板

任务流执行完毕之后,截图 URL 可以从 GetVideoInfo 接口应答包体中的 basicInfo.coverUrl 字段中获取到。

imageSprite(雪碧图控制参数)

参数名称 必填 类型 描述
definition Integer 雪碧图截图模板号,参见 雪碧图参数模板

任务流执行完毕之后,雪碧图结果可以从 GetVideoInfo 接口应答包体中的 imageSpriteInfo 字段获取。

classificationAIAnalysis(智能分类控制参数)

参数名称 必填 类型 描述
definition Integer 智能分类模板号,目前只支持填10。

任务流执行完毕之后,智能分类结果可以从 GetVideoInfo 接口应答包体中的 aiAnalysisInfo.classificationList 字段获取。

tagAIAnalysis(智能标签控制参数)

参数名称 必填 类型 描述
definition Integer 智能标签模板号,目前只支持填10。

任务流执行完毕之后,智能分类结果可以从 GetVideoInfo 接口应答包体中的 aiAnalysisInfo.tagInfo 字段获取。

pornReview(鉴黄审核控制参数)

参数名称 必填 类型 描述
definition Integer 鉴黄模板号,参见 鉴黄参数模板

mosaic(马赛克信息参数)

参数名称 必填 类型 描述
width String 马赛克的宽度。
  • 带%结尾的字符串表示 width 为视频宽度百分比的大小,如10%表示 width 为视频宽度的10%。
  • 带 px 结尾的字符串表示 width 单位为像素,100px 表示 width 为100像素。
默认为0px。
height String 马赛克的高度。
  • 带%结尾的字符串表示 height 为视频高度百分比的大小,如10%表示 height 为视频高度的10%。
  • 带 px 结尾的字符串表示 height 单位为像素,100px 表示 height 为100像素。
默认为0px。
left String 马赛克左上角距离视频图像左上角的水平位置。
  • 带%结尾的字符串表示 left 为视频宽度百分比的大小,如10%表示 left 为视频宽度的10%。
  • 带 px 结尾的字符串表示 left 单位为像素,100px 表示 left 为100像素。
默认为0px。
top String 马赛克左上角距离视频图像左上角的垂直位置。
  • 带%结尾的字符串表示 top 为视频高度百分比的大小,如10%表示 top 为视频宽度的10%。
  • 带 px 结尾的字符串表示 top 单位为像素,100px 表示 top 为100像素。
默认为0px。
startTimeOffset Float 马赛克在视频中的开始时间,单位为秒。
endTimeOffset Float 马赛克在视频中的结束时间,单位为秒。

请求示例

通用视频转码示例

以下示例的含义是:

  1. 对视频进行转码,转码输出模板为10,20,30,40。
  2. 转码过程需要设置水印,水印模板号为1,即默认模板。
  3. 对视频进行采样截图,采样截图的模板号为10。
    任务流中每个子任务的状态发生变化,都需要发起事件通知。
https://vod.api.qcloud.com/v2/index.php?Action=ProcessFile
&fileId=24961954183381008
&transcode.definition.0=210
&transcode.definition.1=220
&transcode.definition.2=230
&transcode.definition.3=240
&transcode.watermark=1
&sampleSnapshot.definition=10
&notifyMode=Change
&COMMON_PARAMS

视频加密转码示例

以下示例的含义是:

  1. 对视频文件进行转码,目标输出模板为210,220,230,240。
  2. 转码过程需要对视频文件进行加密,使用模板号为10的加密策略进行加密。
  3. 当整个任务流执行完毕之后,再发起事件通知。
https://vod.api.qcloud.com/v2/index.php?Action=ProcessFile
&fileId=24961954183381008
&transcode.definition.0=210
&transcode.definition.1=220
&transcode.definition.2=230
&transcode.definition.3=240
&transcode.drm.definition=10
&notifyMode=Finish
&COMMON_PARAMS

视频生成多码率HLS文件示例

以下示例的含义是:

  1. 对视频文件进行转码,目标输出模板为210,220,230,240。
  2. 生成包含210,220,230,240这四种码率的 HLS 文件。
  3. 当整个任务流执行完毕之后,再发起事件通知。
https://vod.api.qcloud.com/v2/index.php?Action=ProcessFile
&fileId=24961954183381008
&transcode.definition.0=210
&transcode.definition.1=220
&transcode.definition.2=230
&transcode.definition.3=240
&transcode.hlsMasterPlaylist=1
&notifyMode=Finish
&COMMON_PARAMS

智能分析示例

https://vod.api.qcloud.com/v2/index.php?Action=ProcessFile
&fileId=24961954183381008
&classificationAIAnalysis.definition=10
&tagAIAnalysis.definition=10
&notifyMode=Finish
&COMMON_PARAMS

内容审核(鉴黄)示例

https://vod.api.qcloud.com/v2/index.php?Action=ProcessFile
&fileId=24961954183381008
&pornReview.definition=10
&notifyMode=Finish
&COMMON_PARAMS

接口应答

参数说明

参数名称 类型 说明
code Integer 错误码,0:成功;其他值:失败。
message String 错误信息。
vodTaskId String 任务 ID。

错误码说明

错误码 含义说明
4000 - 7000 参见 公共错误码

应答示例

{
    "code": 0,
    "message": "",
    "vodTaskId": "125xx-Procedure-6a651e8d148c512af27f3b5f3d60f43a"
}