调用SubmitSnapshotJob接口创建截图-媒体处理-阿里云

提交截图作业。调用本接口之后媒体处理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:SubmitSnapshotJob	create	全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值
Input	string	是	作业输入。详细说明请参见 Input 详情。说明在媒体处理 API 中，Object 必须经过URL Encoding（基于 UTF-8 编码）后使用。 OSS 的地域需要与当前 MPS 所在地域保持一致。	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	是	截图配置。详细说明，请参见 SnapshotConfig 参数详情。	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	否	用户自定义数据。支持中英文、数字、短划线（-），不能以特殊字符开头，最大长度 1024 个字节。	testid-001
PipelineId	string	否	管道 ID，详细说明，请参见基本概念。可选值：可以通过 MPS 控制台 > 全局设置 > 管道查询和创建管道。如果需要异步通知，请为管道绑定 MNS 消息，具体请参见接收消息通知。	dd3dae411e704030b921e52698e5****

返回参数

名称	类型	描述	示例值
	object	返回参数。
RequestId	string	请求 ID。	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	截图作业。
CreationTime	string	任务创建时间。	2021-05-19T03:11:48Z
SnapshotConfig	object	截图配置。
Time	string	截图开始时间。单位：毫秒。	5
TileOut	object	拼图配置。
Padding	string	图片间距。默认：0。单位：px。	0
Color	string	背景颜色。默认：black。可取值范围：颜色关键字，random。说明其中颜色关键字支持三种格式，比如黑色，支持 Black，black，#000000。	black
CellSelStep	string	选取单图片步长。	3
CellHeight	string	单图片高度。默认截图输出分辨率高度。	100
CellWidth	string	单图片宽度。默认截图输出分辨率宽度。	100
Margin	string	外框宽度。默认：0。单位：px。	5
Columns	string	图片拼合列数。默认：10。	10
IsKeepCellPic	string	是否保留单图片。可取值： true：保留。 false：不保留。默认：true。	false
Lines	string	图片拼合行数。默认：10。	10
Interval	string	截图间隔时间。若指定则表示序列截图，且值大于 0。单位：秒。默认值：10。	20
FrameType	string	截图类型。默认值：normal。可取值： normal：普通帧。 intra：I 帧（关键帧）。说明如果请求参数中将 FrameType 参数设置为 I 帧（关键帧），将只截取关键帧。如果指定的时间节点为非关键帧，则就近选取关键帧。在同等截图规则下，关键帧截图比普通帧截图速度快。	intra
Width	string	截图输出图片宽度。	8
Height	string	截图输出图片高度。	8
OutputFile	object	截图输出 OSS 配置。
RoleArn	string	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	截图输出文件（OSS Object）。	test.png
Location	string	截图输出 OSS Bucket 所在数据中心（OSS Location）。	example-location
Bucket	string	截图输出文件所在 OSS Bucket。	example
Num	string	截图数量。若指定则表示序列截图。	10
TileOutputFile	object	拼图任务大图的输出 OSS 配置。
RoleArn	string	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	输出文件（OSS Object）。	example.png
Location	string	输出 OSS Bucket 所在数据中心（OSS Location）。	example-location
Bucket	string	输出文件所在 OSS Bucket。	example
TimeArray	array	指定时间点数组。
TimePointList	long	指定时间点数组。单位毫秒，浮点数，保留 2 位小数，可重复，可无序提交，由 MPS 排序。最多 100 个时间点。指定该参数时，Num、Time、Interval 均不指定。如指定则提示参数指定错误 InvalidParameter.Ambiguity。	[10050, 50000, 110000, 1000500, 1100500]
State	string	截图状态。取值： Submitted：已提交。 Snapshoting：截图中。 Success：截图成功。 Fail：截图失败。	Snapshoting
Message	string	分析失败时错误信息。若成功则不返回此参数。	The resource operated InputFile is bad
MNSMessageResult	object	MNS 通知用户作业完成的结果。
MessageId	string	成功时消息 ID。若失败则不返回此参数。	799454621135656C7F815F198A76****
ErrorMessage	string	失败时错误信息。若成功则不返回此参数。	The resource operated InputFile is bad
ErrorCode	string	失败时错误码。若成功则不返回此参数。	InvalidParameter
Input	object	作业输入。
RoleArn	string	指定角色的 ARN。格式：acs:ram::$accountID:role/$roleName。	acs:ram::1:role/testrole
Object	string	输入文件（OSS Object）。	example.flv
Location	string	输入 OSS Bucket 所在数据中心（OSS Location）。	example-location'
Bucket	string	输入文件所在 OSS Bucket。	example
Count	string	截取图片的数量。	1
TileCount	string	拼图图片数量。	5
UserData	string	用户自定义数据。	testid-001
Code	string	分析失败时错误码。若成功则不返回此参数。	ResourceContentBad
PipelineId	string	管道 ID。	dd3dae411e704030b921e52698e5****
Id	string	截图作业 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-24	OpenAPI 返回结构发生变更	查看变更详情
2024-04-10	API 内部配置变更，不影响调用	查看变更详情