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

接口说明

  • 执行完成后，使用GetVideoTask接口查询返回的TaskId，可以查看任务执行结果。您也可以使用通知机制，传入NotifyTopicName和NotifyEndpoint，及时通知任务执行信息。
  • 使用视频截帧时，输出的图片按照一张一秒计费。

调试

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

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 CreateGrabFrameTask

操作接口名称，固定取值为CreateGrabFrameTask。
Project String 是 immvideotest

项目名称。
TargetList String 是 [{"GrabType":"interval","GrabNumber":"1","TargetUri":"oss://imm-test/testcases/grabframeimage.jpg"}]

输出截帧列表。支持对同一视频同时输出多种结果。

截帧列表包括如下选项：

  • 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：缩放并不保留黑边。
VideoUri String 是 oss://imm-test/testcases/video.mp4

视频的OSS URI。

OSS地址规则为oss://bucket/object，其中bucket为和当前项目处于同一区域的OSS Bucket名称，object为文件路径。

RegionId String 否 cn-hangzhou

项目所在地域的ID。

地域Endpoint格式为imm.RegionId.aliyuncs.com，例如当RegionId为cn-hangzhou时，地域Endpoint为imm.cn-hangzhou.aliyuncs.com。

NotifyTopicName String 否 topic1

异步反向通知的TopicName。
NotifyEndpoint String 否 http://1111111111.mns.cn-hangzhou.aliyuncs.com

异步反向通知的Endpoint，任务执行状态可以通过该Endpoint异步通知给调用者。使用此功能需要先开通MNS服务，新建topic和queue，并配置订阅关系。具体操作，请参见消息服务MNS快速入门。

说明 MNS服务和智能媒体管理必须处于同一地域。
CustomMessage String 否 GrabFrameTest

用户自定义的信息。在MNS通知任务执行状态时，内容会原样返回。

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

输出图片的数组，如果图片较多时，直接输出设置的值。

返回数据

名称 类型 示例值 描述
RequestId String 10AFFE69-73BA-47C2-8A85-029AA9DA72A3

当次请求的Request ID。
TaskId String GrabFrameTask-ffcdec0c-73ba-451a-bec4-a9fe3f4cd765

任务ID。
TaskType String GrabFrameTask

任务的类型，返回值固定为GrabFrameTask。

示例

请求示例

http(s)://[Endpoint]/?Action=CreateGrabFrameTask
&Project=immvideotest
&TargetList=[{"GrabType":"interval","GrabNumber":"1","TargetUri":"oss://imm-test/testcases/grabframeimage.jpg"}]
&VideoUri=oss://imm-test/testcases/video.mp4
&<公共请求参数>

正常返回示例

XML 格式 

<TaskId>GrabFrameTask-ffcdec0c-73ba-451a-bec4-a9fe3f4cd765</TaskId>
<RequestId>10AFFE69-73BA-47C2-8A85-029AA9DA72A3</RequestId>
<TaskType>GrabFrameTask</TaskType>

JSON 格式 

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