SubmitSnapshotJob-阿里云帮助中心

Submit a screenshot job. Media Processing Service (MPS) will then take screenshots and generate a sprite image from the input file.

Operation description

The maximum size for a single input file is 100 GB. Exceeding this limit may cause the job to fail.
Before you submit a snapshot job, ensure the file has been successfully uploaded to OSS. Otherwise, the job may fail. You can configure OSS callbacks to confirm the file upload status.
Snapshot jobs support both synchronous and asynchronous modes.
- Synchronous mode supports only a single snapshot and generates the image when the API call returns.
- Asynchronous mode does not guarantee immediate processing. After you submit a snapshot job, it enters a pipeline, where it is queued and scheduled for execution. Therefore, the snapshot is not guaranteed to be generated when the API call returns. After the job is complete, you can poll for the results by calling the Query snapshot job results API or receive message notifications by binding MNS to the pipeline. For more information, see Receive message notifications.
- Specifying either the Interval or Num parameter triggers asynchronous mode.
Currently, only images in JPG format are supported.
For more information about common snapshot issues, see Snapshot FAQ.

QPS limit

The QPS limit for this API is 50 requests per second per user. API calls that exceed this limit are subject to throttling, which may impact your business. Please call this API at a reasonable rate. For more information, see QPS limit.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

mts:SubmitSnapshotJob

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
Input	string	Yes	The job input. For more information, see Input. Note In ApsaraVideo for Media Processing (MPS) APIs, you must URL-encode the value of `Object` in UTF-8. The OSS region must be the same as the MPS region.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Yes	The snapshot configurations. For more information, see SnapshotConfig.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	No	The custom data. The value can contain letters, digits, and hyphens (-), but cannot start with a special character. The value can be up to 1,024 bytes in length.	testid-001
PipelineId	string	No	The ID of the MPS queue. For more information, see Basic concepts. You can view or create MPS queues in the MPS console by choosing Global Settings > Pipelines. To receive asynchronous notifications, you must bind a Message Service (MNS) queue to the MPS queue. For more information, see Receive message notifications.	dd3dae411e704030b921e52698e5****

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	The snapshot job.
CreationTime	string	The time the job was created.	2021-05-19T03:11:48Z
SnapshotConfig	object	The snapshot configuration.
Time	string	The snapshot start time. Unit: milliseconds.	5
TileOut	object	The tiling configuration.
Padding	string	The padding between images. Default value: 0. Unit: pixels.	0
Color	string	The background color. Default value: black. Valid values: color keyword or random. Note Color keywords can be specified in three formats. For example, to specify black, you can use `Black`, `black`, or `#000000`.	black
CellSelStep	string	The step for selecting individual images to include in the tiled output.	3
CellHeight	string	The height of an individual image in the tiled output. Defaults to the height of the output snapshot.	100
CellWidth	string	The width of an individual image in the tiled output. Defaults to the width of the output snapshot.	100
Margin	string	The width of the outer margin for the tiled image. Default value: 0. Unit: pixels.	5
Columns	string	The number of columns in the tiled image. Default value: 10.	10
IsKeepCellPic	string	Specifies whether to keep the individual snapshots. Valid values: true: Keeps the individual snapshots. false: Deletes the individual snapshots. Default value: true.	false
Lines	string	The number of rows in the tiled image. Default value: 10.	10
Interval	string	The interval for capturing a sequence of snapshots. The value must be greater than 0. Unit: seconds. Default value: 10.	20
FrameType	string	The type of frames to capture. Default value: normal. Valid values: normal: normal frames. intra: I-frames (keyframes). Note If this parameter is set to `intra`, only keyframes are captured. If a specified time point is not a keyframe, the system uses the nearest keyframe. Capturing keyframes is typically faster than capturing normal frames.	intra
Width	string	The width of the output snapshot.	8
Height	string	The height of the output snapshot.	8
OutputFile	object	The OSS configuration for the output snapshot.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the output OSS object.	test.png
Location	string	The data center of the output OSS bucket.	example-location
Bucket	string	The OSS bucket for the output file.	example
Num	string	The number of snapshots to capture in a sequence.	10
TileOutputFile	object	The OSS configuration for the output tiled image.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the output OSS object.	example.png
Location	string	The data center of the output OSS bucket.	example-location
Bucket	string	The OSS bucket for the output file.	example
TimeArray	object
TimePointList	array	An array of time points.
	integer	An array of up to 100 time points, in milliseconds, at which to capture snapshots. Values can be floating-point numbers with up to two decimal places. You can submit time points in any order and include duplicates; MPS automatically sorts them. If you specify this parameter, do not use the `Num`, `Time`, or `Interval` parameters. Otherwise, the API returns an `InvalidParameter.Ambiguity` error.	[10050, 50000, 110000, 1000500, 1100500]
State	string	The state of the snapshot job. Valid values: Submitted: The job has been submitted. Snapshotting: The snapshot job is in progress. Success: The job was successful. Fail: The job failed.	Snapshoting
Message	string	The error message. This parameter is returned only if the job fails.	The resource operated InputFile is bad
MNSMessageResult	object	The result of the MNS notification sent to the user upon job completion.
MessageId	string	The ID of the MNS message. This parameter is returned only on successful notification.	799454621135656C7F815F198A76****
ErrorMessage	string	The error message, returned only if the MNS notification fails.	The resource operated InputFile is bad
ErrorCode	string	The error code, returned only if the MNS notification fails.	InvalidParameter
Input	object	The job input.
RoleArn	string	The ARN of the role. Format: `acs:ram::$accountID:role/$roleName`.	acs:ram::1:role/testrole
Object	string	The name of the input OSS object.	example.flv
Location	string	The data center of the input OSS bucket.	example-location'
Bucket	string	The OSS bucket that contains the input file.	example
Count	string	The total number of captured snapshots.	1
TileCount	string	The number of tiled images.	5
UserData	string	The user-defined data.	testid-001
Code	string	The error code. This parameter is returned only when the job status is Fail.	ResourceContentBad
PipelineId	string	The pipeline ID.	dd3dae411e704030b921e52698e5****
Id	string	The ID of the snapshot job.	f4e3b9ba9f3840c39d6e288056f0****

Examples

Success response

JSON format

{
  "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****"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.