新建截图任务 - CreateThumbnailsTask

功能介绍

新建截图任务，视频截图将从首帧开始，按设置的时间间隔截图，最后截取末帧。

待截图的视频文件需要存储在与媒体处理服务同区域的OBS桶中，且该OBS桶已授权。

约束：

暂只支持生成JPG格式的图片文件。

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

如果使用角色与策略授权，具体权限要求请参见权限和授权项。
如果使用身份策略授权，需具备如下身份策略权限。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

mpc:thumbnailsTask:create

Write

-

-

-

-

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
mpc:thumbnailsTask:create	Write	-	-	-	-

URI

POST /v1/{project_id}/thumbnails

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。获取方法请参考获取项目ID。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	否	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
Authorization	否	String	使用AK/SK方式认证时必选，携带的鉴权信息。
X-Project_Id	否	String	使用AK/SK方式认证时必选，携带项目ID信息, 与路径参数中的项目ID相同。
X-Sdk-Date	否	String	使用AK/SK方式认证时必选，请求的发生时间。

表3 请求Body参数
参数	是否必选	参数类型	描述
input	是	ObsObjInfo object	源文件地址。
output	是	ObsObjInfo object	输出地址。
user_data	否	String	用户自定义数据。
thumbnail_para	是	ThumbnailPara object	截图参数
tar	否	Integer	是否压缩抽帧图片生成tar包。取值如下： 0：压缩。 1：不压缩默认值：1
sync	否	Integer	是否同步处理，同步处理是指不下载全部文件，快速定位到截图位置进行截图。取值如下： 0：排队处理，异步截图。 1：同步处理，同步截图，暂只支持按时间点截单张图。默认值：0
original_dir	否	Integer	是否使用原始输出目录。取值如下： 0：不使用原始输出目录，下发的输出目录后面追加随机目录，防止截图文件outputUri相同被覆盖。 1：使用原始输出目录。默认值：0

表4 ObsObjInfo
参数	是否必选	参数类型	描述
bucket	是	String	OBS的bucket名称。
location	是	String	OBS桶所在的区域，且必须与使用的MPC区域保持一致。
object	是	String	OBS对象路径，遵守OSS Object定义。当用于指示input时，需要指定到具体对象。当用于指示output时，只需指定到转码结果期望存放的路径。在字幕场景下，字幕文件名称中禁止携带特殊符号，否则会导致转码任务失败，如：[ 正确示例: demo.srt 错误示例: [demo.srt
file_name	否	String	文件名，文件名长度不能超过180个字符。当指定了此参数时，输出的对象名为object/file_name。当不指定此参数时，输出的对象名为object/xxx，其中xxx由MPC指定。在作为输出文件名时：在转封装场景有效，需要指定输出文件名称在转码场景下，如果需要指定输出的文件名称，请使用output_filenames参数在解析场景有效，解析场景如果指定文件名，则将解析参数写入指定文件名，通过查询接口响应json数据获取文件元数据信息在截图场景无效在转动图场景无效输出文件为HLS格式时，文件名称不能命名为index，示例：index.m3u8，否则会导致播放失败。

表5 ThumbnailPara
参数	是否必选	参数类型	描述
type	否	String	采样类型。取值如下： "TIME"：根据时间间隔采样截图。 "DOTS"：指定时间点截图。选择同步截图时，需指定此类型。 "DOTS_MS": 同步截图指定时间点毫秒值。默认值："TIME"
amount	否	Integer	黑点比例大于等于此值认为是黑帧。
threshold	否	Integer	像素值小于此值认为是黑点。
time	否	Integer	采样截图的时间间隔值。取值范围[1,100]，默认值：12。单位：秒
start_time	否	Integer	采样类型为“TIME”模式的开始时间，和“time”配合使用。默认值：0。单位：秒。说明： start_time超过片源时长,不进行抽帧
duration	否	Integer	采样类型为“TIME”模式的持续时间，和“time”、“start_time”配合使用，表示从视频文件的第“start_time”开始，持续时间为“duration”，每间隔“time”生成一张截图。取值范围：[数字，ToEND]。“ToEND”表示持续到视频结束。默认值： ToEND。单位：秒。说明： “duration”必须大于等0，若设置为0，则截图持续时间从“start_time”到视频结束。
dots	否	Array of integers	指定时间截图的时间点数组例如输入[1,3,5]，分别截取视频第1秒、第3秒、第5秒位置的图像帧异步截图：最多支持10个时间点同步截图时：只支持1个时间点
dots_ms	否	Array of integers	同步截图下，指定时间截图的时间点数组，单位毫秒例如输入[1000]，截取视频第1000毫秒位置的图像帧，仅支持一个时间点
output_filename	否	String	截图输出文件名。如果只抽一张图（即：按DOTS方式，指定1个时间点）则按该指定文件名输出图片。如果抽多张图（即：按DOTS方式指定多个时间点或按TIME间隔截图）则输出图片名在该指定文件名基础上再增加时间点（示例：output_filename_10.jpg）。如果指定了压缩抽帧图片生成tar包，则tar包按该指定文件名输出。
format	否	Integer	截图文件格式。取值如下： 1：表示jpg格式 2：表示png格式仅同步截图支持png格式
width	否	Integer	图片宽度取值范围： [96,3840] 0：自适应，保持原有宽高单位：px
height	否	Integer	图片高度取值范围： [96,2160] 0：自适应，保持原有宽高单位：px
max_length	否	Integer	截图最长边的尺寸。宽边尺寸按照该尺寸与原始视频像素等比缩放计算。参考取值范围：[240,3840] 单位：像素说明：该参数和width/height选择使用，以width/height优先，若width/height都不等于0，则图片尺寸按width/height得出；反之，则图片尺寸按max_length 得出;若该参数和width/height都未选择，则按源片源宽高输出截图

响应参数

状态码：202

表6 响应Body参数
参数	参数类型	描述
task_id	String	任务ID。
status	String	任务状态。取值如下： WAITING: 等待启动 PROCESSING：截图中 SUCCEEDED：截图成功 FAILED：截图失败 CANCELED：已删除
create_time	String	任务创建时间
output	ObsObjInfo object	输出文件信息
output_file_name	String	截图文件名称
thumbnail_time	String	指定的截图时间点
description	String	截图任务描述，当截图出现异常时，此字段为异常的原因

表7 ObsObjInfo
参数	参数类型	描述
bucket	String	OBS的bucket名称。
location	String	OBS桶所在的区域，且必须与使用的MPC区域保持一致。
object	String	OBS对象路径，遵守OSS Object定义。当用于指示input时，需要指定到具体对象。当用于指示output时，只需指定到转码结果期望存放的路径。在字幕场景下，字幕文件名称中禁止携带特殊符号，否则会导致转码任务失败，如：[ 正确示例: demo.srt 错误示例: [demo.srt
file_name	String	文件名，文件名长度不能超过180个字符。当指定了此参数时，输出的对象名为object/file_name。当不指定此参数时，输出的对象名为object/xxx，其中xxx由MPC指定。在作为输出文件名时：在转封装场景有效，需要指定输出文件名称在转码场景下，如果需要指定输出的文件名称，请使用output_filenames参数在解析场景有效，解析场景如果指定文件名，则将解析参数写入指定文件名，通过查询接口响应json数据获取文件元数据信息在截图场景无效在转动图场景无效输出文件为HLS格式时，文件名称不能命名为index，示例：index.m3u8，否则会导致播放失败。

状态码：400

表8 响应Body参数
参数	参数类型	描述
error_code	String	错误码。
error_msg	String	错误描述。

请求示例

新建异步截图任务，视频截图将从首帧开始，按设置的时间间隔截图，最后截取末帧。

POST https://{endpoint}/v1/{project_id}/thumbnails

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.mp4"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output"
  },
  "tar" : 1,
  "thumbnail_para" : {
    "time" : 2,
    "format" : 1,
    "max_length" : 480
  },
  "sync" : 0
}

新建同步截图任务（将sync设置为1），视频截图将从首帧开始，按设置的时间间隔截图，最后截取末帧。

POST https://{endpoint}/v1/{project_id}/thumbnails

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.mp4"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output"
  },
  "tar" : 1,
  "thumbnail_para" : {
    "time" : 2,
    "format" : 1,
    "max_length" : 480
  },
  "sync" : 1
}

响应示例

状态码：202

新建截图任务成功。

新建异步截图任务成功。
```
{
  "task_id" : "100211"
}
```

新建同步截图任务成功。

{
  "task_id" : "100212",
  "status" : "FINISHED",
  "create_time" : "20231201020412",
  "output" : {
    "bucket" : "bucket-demo",
    "location" : "cn-north-4",
    "object" : "output/demo_object",
    "file_name" : ""
  },
  "output_file_name" : "H_270.png",
  "thumbnail_time" : "30",
  "description" : "任务处理成功。"
}

状态码：400

新建截图任务失败。

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter"
}

状态码

状态码	描述
202	新建截图任务成功。
400	新建截图任务失败。

错误码

请参见错误码。

父主题：抽帧截图接口

上一篇：抽帧截图接口

下一篇：查询截图任务 - ListThumbnailsTask

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试