# 新建截图任务 - CreateThumbnailsTask #### 功能介绍 新建截图任务，视频截图将从首帧开始，按设置的时间间隔截图，最后截取末帧。 待截图的视频文件需要存储在与媒体处理服务同区域的OBS桶中，且该OBS桶已授权。 约束： 暂只支持生成JPG格式的图片文件。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-mpc/mpc_04_0047.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-mpc/mpc_04_0002.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | mpc:thumbnailsTask:create | Write | - | - | - | - | #### URI POST /v1/{project_id}/thumbnails 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目ID。获取方法请参考[获取项目ID](https://support.huaweicloud.com/api-mpc/mpc_04_0064.html)。 | #### 请求参数 表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 | 表4ObsObjInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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，否则会导致播放失败。 | 表5ThumbnailPara | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 截图任务描述，当截图出现异常时，此字段为异常的原因 | 表7ObsObjInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 新建截图任务失败。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-mpc/ErrorCode.html)。