调用CreateGrabFrameTask创建一个视频截帧任务_智能媒体管理(IMM)-阿里云帮助中心

调用CreateGrabFrameTask接口创建一个视频截帧任务，执行完成后返回TaskId。

接口说明

此接口已不再维护，建议使用新版（2020-09-30 版本）接口 CreateMediaConvertTask 。关于新版与旧版 API 的对比，请参见新旧版本使用指引中的新版与旧版 API 对应关系说明章节。
执行完成后，使用 GetVideoTask 接口查询返回的 TaskId，可以查看任务执行结果。您也可以使用通知机制，传入 NotifyTopicName 和 NotifyEndpoint，及时通知任务执行信息。
使用视频截帧时，输出的图片按照一张一秒计费。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
imm:CreateGrabFrameTask		全部资源 *	无	无

请求参数

名称	类型	必填	描述	示例值
Project	string	是	项目名称。	immvideotest
VideoUri	string	是	视频的 OSS URI。 OSS 地址规则为`oss://bucket/object`，其中 bucket 为和当前项目处于同一区域的 OSS Bucket 名称，object 为文件路径。	oss://imm-test/testcases/video.mp4
NotifyTopicName	string	否	异步反向通知的 TopicName。	topic1
NotifyEndpoint	string	否	异步反向通知的 Endpoint，任务执行状态可以通过该 Endpoint 异步通知给调用者。使用此功能需要先开通轻量消息队列（原 MNS）服务，新建 topic 和 queue，并配置订阅关系。具体操作，请参见轻量消息队列（原 MNS）快速入门。说明轻量消息队列（原 MNS）服务和智能媒体管理必须处于同一地域。	http://1111111111.mns.cn-hangzhou.aliyuncs.com
TargetList	string	是	输出截帧列表。支持对同一视频同时输出多种结果。截帧列表包括如下选项： TargetUri（必选）：输出文件的 OSS URI，类型为 String。支持自定义文件名例如 pre{002}suf.jpg，则输出图片文件的名称为 pre002suf.jpg、pre003suf.jpg 等。如果 TotalNumber 为 1，则直接使用该名称。 OSS 地址规则为`oss://bucket/object`，其中 bucket 为和当前项目处于同一区域的 OSS Bucket 名称，object 为文件路径。 GrabType（必选）：截帧类型，类型为 String。目前支持 sprite（雪碧图）和 interval（间隔截帧）。 Interval（可选）：截帧间隔，支持按时长的百分比设置，如果该值小于 0.01 则按 0.01 处理，类型为 String。当截取视频中的多个帧时，必须设置此参数；如果截取视频中单个帧时，可以不设置此参数。 TotalNumber（可选）：截帧数量，类型为 Integer。如果视频的有效时长不足，则按照有效时长截帧。 SkipBegin（可选）：跳过开始时间，支持按时长的百分比设置，类型为 String。 SkipEnd（可选）：跳过结束时间，支持按时长的百分比设置，类型为 String。 Width（可选）：截帧宽度，支持按百分比设置，类型为 String。 Height（可选）：截帧高度，支持按百分比设置，类型为 String。 SpriteRow（可选）：雪碧图中小图的行数，取值范围为 1~20，类型为 Integer。当截取雪碧图时，必须设置此参数。截取雪碧图时会优先填写满行，行数不足时为黑色背景。 SpriteColumn（可选）：雪碧图中小图的列数，取值范围为 1~20，类型为 Integer。当截取雪碧图时，必须设置此参数。截取雪碧图时会优先填写满行，行数不足时为黑色背景。 SpritePad（可选）：雪碧图中小图间的间隔，默认值为 2，取值范围为 1~50，类型为 Integer。 SpriteMargin（可选）：雪碧图边缘间隔，默认值为 2，取值范围为 1~100，类型为 Integer。 ScaleType（可选）：缩放方式，默认值为 STRETCH，类型为 String。可选值如下： CROP：缩放并裁剪。 STRETCH：拉伸以填满。 FILL：缩放并保留黑边。 FIT：缩放并不保留黑边。	[{"GrabType":"interval","GrabNumber":"1","TargetUri":"oss://imm-test/testcases/grabframeimage.jpg"}]
CustomMessage	string	否	用户自定义的信息。在轻量消息队列（原 MNS）通知任务执行状态时，内容会原样返回。	GrabFrameTest

#轻量消息队列（原 MNS）通知

请求参数中如果设置了 NotifyTopicName 和 NotifyEndpoint 支持轻量消息队列（原 MNS）事件通知，则智能媒体管理会为您返回异步通知。通知的消息格式为：

{
  "events": [
    {
      "eventName": "GrabFrameTask",
      "eventSource": "acs:imm",
      "eventTime": "2019-09-30T14:14:51.901Z",
      "eventVersion": "1.0",
      "imm": {
        "CustomMessage": "hello",
        "ErrorCode": "",
        "GrabDuration": "1",
        "JobId": "GrabFrameTask-2c21f159-dfe1-4cb3-ba5d-5db0c422ac2a",
        "Results": "[{\"Success\":\"true\",\"GrabType\":\"interval\",\"GrabNumber\":\"1\",\"FinalNumber\":\"1\",\"TargetPrefix\":\"oss://imm-test/testcases/",\"TargetList\":[\"grabframeimage.jpg\"],\"Reason\":\"\"}]",
        "SourceCodec": "h264",
        "SourceDuration": "182.58",
        "SourceResolution": "1280x720",
        "TaskId": "GrabFrameTask-2c21f159-dfe1-4cb3-ba5d-5db0c422ac2a",
        "VideoUri": "oss://imm-test/testcases/video.mp4"
      }
    }
  ]
}

轻量消息队列（原 MNS）通知返回参数说明请参见下表。

参数	类型	描述
eventName	String	任务类型，返回值固定为 GrabFrameTask。
imm.TaskId	String	任务唯一 ID。
imm.Duration	String	视频总时长。
imm.GrabDuration	String	截帧处理时长。
imm.CustomMessage	String	用户自定义信息，返回内容和创建任务时设置的内容一致。
imm.Results	String	视频转码结果 Result 数组，以 JSON 格式表示。

Result 包括的选项请参见下表。

参数	类型	描述
Success	String	任务执行是否成功。
GrabType	String	截帧模式。
GrabNumber	String	截帧数量，一张按一秒计费。
FinalNumber	String	最终输出的数量，例如雪碧图的张数。
TargetPrefix	String	输出图片的前缀。
TargetList	[]String	输出图片的数组，如果图片较多时，直接输出设置的值。

返回参数

名称	类型	描述	示例值
	object
TaskId	string	任务 ID。	GrabFrameTask-ffcdec0c-73ba-451a-bec4-a9fe3f4cd765
RequestId	string	当次请求的 Request ID。	10AFFE69-73BA-47C2-8A85-029AA9DA72A3
TaskType	string	任务的类型，返回值固定为 GrabFrameTask。	GrabFrameTask

示例

正常返回示例

JSON格式

{
  "TaskId": "GrabFrameTask-ffcdec0c-73ba-451a-bec4-a9fe3f4cd765",
  "RequestId": "10AFFE69-73BA-47C2-8A85-029AA9DA72A3",
  "TaskType": "GrabFrameTask"
}

错误码

访问错误中心查看更多错误码。