AI 助理
备案控制台
首页 媒体处理 开发参考 API参考指南 API目录 截图接口 SubmitSnapshotJob - 提交截图作业

SubmitSnapshotJob - 提交截图作业

更新时间: 2024-11-08 17:07:56

提交截图作业。调用本接口之后媒体处理MPS会对输入文件进行截图和拼图。

接口说明

  • 输入单个文件大小最大支持 100 GB，超过可能导致执行失败。

  • 请确认文件已成功上传至 OSS 后再提交截图作业，否则会导致执行失败。您可通过配置 OSS 回调消息确认文件上传状态。

  • 截图作业分为同步和异步模式。

    • 同步模式仅支持单张截图，会在接口返回时生成图片。
    • 异步模式不保证时效性，在提交截图作业后，任务会添加到管道中排队，被调度执行。所以在接口返回时，不保证截图已经生成。执行完成后需要调用查询截图作业结果接口轮询执行结果，或通过为管道绑定 MNS 消息接收执行结果，具体请参见接收消息通知。
    • 只要设置了 Interval 和 Num 中的任何一个参数，就表示使用异步模式。

  • 目前仅支持生成 JPG 格式图片。

  • 更多截图常见问题，请参见截图常见问题。

QPS 限制

本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。

调试

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

授权信息

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

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

请求参数

名称类型必填描述示例值
Inputstring是

作业输入。详细说明请参见 Input 详情。

说明
  • 在媒体处理 API 中，Object 必须经过URL Encoding（基于 UTF-8 编码）后使用。
    •
    • OSS 的地域需要与当前 MPS 所在地域保持一致。
    		{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
    SnapshotConfigstring是

    截图配置。详细说明，请参见 SnapshotConfig 参数详情。

    		{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
    UserDatastring否

    用户自定义数据。支持中英文、数字、短划线（-），不能以特殊字符开头，最大长度 1024 个字节。

    		testid-001
    PipelineIdstring否

    管道 ID，详细说明，请参见基本概念。

    • 可选值：可以通过 MPS 控制台 > 全局设置 > 管道查询和创建管道。
    • 如果需要异步通知，请为管道绑定 MNS 消息，具体请参见接收消息通知。
    		dd3dae411e704030b921e52698e5****

    返回参数

    名称类型描述示例值
    object

    返回参数。

    RequestIdstring

    请求 ID。

    		19B6D8C5-A5DD-467A-B435-29D393C71E2D
    SnapshotJobobject

    截图作业。

    CreationTimestring

    任务创建时间。

    		2021-05-19T03:11:48Z
    SnapshotConfigobject

    截图配置。

    Timestring

    截图开始时间。单位：毫秒。

    		5
    TileOutobject

    拼图配置。

    Paddingstring

    图片间距。

    • 默认：0。

    • 单位：px。

    		0
    Colorstring

    背景颜色。

    • 默认：black。
    • 可取值范围：颜色关键字，random。
    说明 其中颜色关键字支持三种格式，比如黑色，支持 Black，black，#000000。
    		black
    CellSelStepstring

    选取单图片步长。

    		3
    CellHeightstring

    单图片高度。默认截图输出分辨率高度。

    		100
    CellWidthstring

    单图片宽度。默认截图输出分辨率宽度。

    		100
    Marginstring

    外框宽度。

    • 默认：0。

    • 单位：px。

    		5
    Columnsstring

    图片拼合列数。默认：10。

    		10
    IsKeepCellPicstring

    是否保留单图片。可取值：

    • true：保留。

    • false：不保留。

    • 默认：true。

    		false
    Linesstring

    图片拼合行数。默认：10。

    		10
    Intervalstring

    截图间隔时间。

    • 若指定则表示序列截图，且值大于 0。
    • 单位：秒。
    • 默认值：10。
    		20
    FrameTypestring

    截图类型。默认值：normal。可取值：

    • normal：普通帧。
    • intra：I 帧（关键帧）。
    说明 如果请求参数中将 FrameType 参数设置为 I 帧（关键帧），将只截取关键帧。如果指定的时间节点为非关键帧，则就近选取关键帧。在同等截图规则下，关键帧截图比普通帧截图速度快。
    		intra
    Widthstring

    截图输出图片宽度。

    		8
    Heightstring

    截图输出图片高度。

    		8
    OutputFileobject

    截图输出 OSS 配置。

    RoleArnstring

    指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。

    		acs:ram::1:role/testrole
    Objectstring

    截图输出文件（OSS Object）。

    		test.png
    Locationstring

    截图输出 OSS Bucket 所在数据中心（OSS Location）。

    		example-location
    Bucketstring

    截图输出文件所在 OSS Bucket。

    		example
    Numstring

    截图数量。若指定则表示序列截图。

    		10
    TileOutputFileobject

    拼图任务大图的输出 OSS 配置。

    RoleArnstring

    指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。

    		acs:ram::1:role/testrole
    Objectstring

    输出文件 （OSS Object）。

    		example.png
    Locationstring

    输出 OSS Bucket 所在数据中心（OSS Location）。

    		example-location
    Bucketstring

    输出文件所在 OSS Bucket。

    		example
    TimeArrayarray

    指定时间点数组。

    TimePointListlong

    指定时间点数组。单位毫秒，浮点数，保留 2 位小数，可重复，可无序提交，由 MPS 排序。最多 100 个时间点。指定该参数时，Num、Time、Interval 均不指定。如指定则提示参数指定错误 InvalidParameter.Ambiguity。

    		[10050, 50000, 110000, 1000500, 1100500]
    Statestring

    截图状态。取值：

    • Submitted：已提交。

    • Snapshoting：截图中。

    • Success：截图成功。

    • Fail：截图失败。

    		Snapshoting
    Messagestring

    分析失败时错误信息。若成功则不返回此参数。

    		The resource operated InputFile is bad
    MNSMessageResultobject

    MNS 通知用户作业完成的结果。

    MessageIdstring

    成功时消息 ID。若失败则不返回此参数。

    		799454621135656C7F815F198A76****
    ErrorMessagestring

    失败时错误信息。若成功则不返回此参数。

    		The resource operated InputFile is bad
    ErrorCodestring

    失败时错误码。若成功则不返回此参数。

    		InvalidParameter
    Inputobject

    作业输入。

    RoleArnstring

    指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。

    		acs:ram::1:role/testrole
    Objectstring

    输入文件（OSS Object）。

    		example.flv
    Locationstring

    输入 OSS Bucket 所在数据中心（OSS Location）。

    		example-location'
    Bucketstring

    输入文件所在 OSS Bucket。

    		example
    Countstring

    截取图片的数量。

    		1
    TileCountstring

    拼图图片数量。

    		5
    UserDatastring

    用户自定义数据。

    		testid-001
    Codestring

    分析失败时错误码。若成功则不返回此参数。

    		ResourceContentBad
    PipelineIdstring

    管道 ID。

    		dd3dae411e704030b921e52698e5****
    Idstring

    截图作业 ID。

    		f4e3b9ba9f3840c39d6e288056f0****

    示例

    正常返回示例

    JSON格式

    {
  "RequestId": "19B6D8C5-A5DD-467A-B435-29D393C71E2D",
  "SnapshotJob": {
    "CreationTime": "2021-05-19T03:11:48Z",
    "SnapshotConfig": {
      "Time": "5",
      "TileOut": {
        "Padding": "0",
        "Color": "black",
        "CellSelStep": "3",
        "CellHeight": "100",
        "CellWidth": "100",
        "Margin": "5",
        "Columns": "10",
        "IsKeepCellPic": "false",
        "Lines": "10"
      },
      "Interval": "20",
      "FrameType": "intra",
      "Width": "8",
      "Height": "8",
      "OutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "test.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "Num": "10",
      "TileOutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "example.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "TimeArray": {
        "TimePointList": [
          0
        ]
      }
    },
    "State": "Snapshoting",
    "Message": "The resource operated InputFile is bad",
    "MNSMessageResult": {
      "MessageId": "799454621135656C7F815F198A76****",
      "ErrorMessage": "The resource operated InputFile is bad",
      "ErrorCode": "InvalidParameter"
    },
    "Input": {
      "RoleArn": "acs:ram::1:role/testrole",
      "Object": "example.flv",
      "Location": "example-location'",
      "Bucket": "example"
    },
    "Count": "1",
    "TileCount": "5",
    "UserData": "testid-001",
    "Code": "ResourceContentBad",
    "PipelineId": "dd3dae411e704030b921e52698e5****",
    "Id": "f4e3b9ba9f3840c39d6e288056f0****"
  }
}

    错误码

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

    变更历史

    变更时间变更内容概要操作
    2024-04-24OpenAPI 返回结构发生变更查看变更详情
    2024-04-10API 内部配置变更，不影响调用查看变更详情
    上一篇: 截图接口 下一篇: QuerySnapshotJobList - 查询截图作业结果
    文档推荐
    阿里云首页 媒体处理 相关技术圈