文档

CreateGrabFrameTask - 创建一个视频截帧任务

更新时间:

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

接口说明

  • 此接口已不再维护,建议使用新版(2020-09-30 版本)接口 CreateMediaConvertTask 。关于新版与旧版 API 的对比,请参见新旧版本使用指引中的新版与旧版 API 对应关系说明章节。

  • 执行完成后,使用 GetVideoTask 接口查询返回的 TaskId,可以查看任务执行结果。您也可以使用通知机制,传入 NotifyTopicName 和 NotifyEndpoint,及时通知任务执行信息。

  • 使用视频截帧时,输出的图片按照一张一秒计费。

调试

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

授权信息

当前API暂无授权信息透出。

请求参数

名称类型必填描述示例值
Projectstring

项目名称。

immvideotest
VideoUristring

视频的 OSS URI。

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

oss://imm-test/testcases/video.mp4
NotifyTopicNamestring

异步反向通知的 TopicName。

topic1
NotifyEndpointstring

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

说明 MNS 服务和智能媒体管理必须处于同一地域。
http://1111111111.mns.cn-hangzhou.aliyuncs.com
TargetListstring

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

截帧列表包括如下选项:

  • 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"}]
CustomMessagestring

用户自定义的信息。在 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 通知返回参数说明请参见下表。

参数类型描述
eventNameString任务类型,返回值固定为 GrabFrameTask。
imm.TaskIdString任务唯一 ID。
imm.DurationString视频总时长。
imm.GrabDurationString截帧处理时长。
imm.CustomMessageString用户自定义信息,返回内容和创建任务时设置的内容一致。
imm.ResultsString视频转码结果 Result 数组,以 JSON 格式表示。

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

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

返回参数

名称类型描述示例值
object
TaskIdstring

任务 ID。

GrabFrameTask-ffcdec0c-73ba-451a-bec4-a9fe3f4cd765
RequestIdstring

当次请求的 Request ID。

10AFFE69-73BA-47C2-8A85-029AA9DA72A3
TaskTypestring

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

GrabFrameTask

示例

正常返回示例

JSON格式

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

错误码

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

  • 本页导读 (1)
文档反馈