服务端 API 文档

对视频文件进行处理

最近更新时间:2019-12-05 11:38:06

接口名称

ProcessFile

注意:

本接口已不再维护,新接口 ProcessMedia 为您提供更完备的功能,请尽快迁移。

功能说明

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

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

本接口为异步接口,即发起一系列视频处理任务。任务流中的任务状态变更(包括结束)可以通过 事件通知 机制感知。任务执行完毕后,每项异步任务的执行结果(如转码输出文件 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。
    SubAppId Integer 点播 子应用 ID。如果要访问子应用中的资源,则将该字段填写为子应用 ID;否则无需填写该字段。
    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 马赛克在视频中的结束时间,单位为秒。

    请求示例

    通用视频转码示例

    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
    

    示例含义:

    • 对视频进行转码,转码输出模板为10、20、30和40。
    • 转码过程需要设置水印,水印模板号为1,即默认模板。
    • 对视频进行采样截图,采样截图的模板号为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.drm.definition=10
    &notifyMode=Finish
    &COMMON_PARAMS
    

    示例含义:

    • 对视频文件进行转码,目标输出模板为210、220、230和240。
    • 转码过程需要对视频文件进行加密,使用模板号为10的加密策略进行加密。
    • 当整个任务流执行完毕后,再发起事件通知。

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

    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
    

    示例含义:

    • 对视频文件进行转码,目标输出模板为210、220、230和240。
    • 生成包含210、220、230和240码率的 HLS 文件。
    • 当整个任务流执行完毕后,再发起事件通知。

    智能分析示例

    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"
    }
    目录