SubmitSnapshotJob-阿里云帮助中心

Submits a snapshot job. After you call this operation, ApsaraVideo Media Processing takes snapshots and generates image sprites for the input file.

Operation description

The maximum size of a single input file is 100 GB. Exceeding this limit may cause the job to fail.
Make sure that the file is successfully uploaded to OSS before you submit a snapshot job. Otherwise, the job may fail. You can configure OSS callback messages to check the file upload status.
Snapshot jobs support synchronous and asynchronous modes.
- The synchronous mode supports only single-frame snapshots. The image is generated when the API response is returned.
- The asynchronous mode does not guarantee real-time processing. After a snapshot job is submitted, the task is added to an MPS queue for scheduling and execution. Therefore, the snapshot may not be generated when the API response is returned. After the execution is complete, you must call the query snapshot job results operation to poll the execution result, or bind an MNS message to the MPS queue to receive the execution result. For more information, see Receive message notifications.
- If you specify the Interval or Num parameter, the asynchronous mode is used.
Only JPG images are supported.
For more information about snapshot FAQs, see Snapshot FAQ.

QPS limits

The QPS limit for a single user is 50 queries per second. If the limit is exceeded, API calls are throttled, which may affect your business. Make API calls properly. For more information, see QPS limits.

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 details. Note In ApsaraVideo Media Processing API operations, the Object parameter must be URL-encoded based on UTF-8. The region of the OSS bucket must be the same as the region of MPS.	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	Yes	The snapshot configuration. For more information, see SnapshotConfig parameter details.	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	No	The custom user data. The value can contain Chinese and English characters, digits, and hyphens (-), and cannot start with a special character. The maximum length is 1,024 bytes.	testid-001
PipelineId	string	No	The MPS queue ID. For more information, see Terms. Valid values: You can query and create MPS queues in the MPS console by choosing Global Settings > Pipelines. If you need asynchronous notifications, attach an MNS message to the MPS queue. For more information, see Accept 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 when the task was created. The time is displayed in UTC and follows the ISO 8601 standard in the YYYY-MM-DDTHH:mm:ssZ format.	2021-05-19T03:11:48Z
SnapshotConfig	object	The snapshot configuration.
Time	string	The start time of the snapshot. Unit: milliseconds.	5
TileOut	object	The image sprite configuration.
Padding	string	The spacing between images. Default value: 0. Unit: pixels.	0
Color	string	The background color. Default value: black. Valid values: color keyword and random. Note A color keyword supports three formats. For example, black can be specified as Black, black, or #000000.	black
CellSelStep	string	The step size for selecting single images.	3
CellHeight	string	The height of a single image. Default value: the height of the snapshot output resolution.	100
CellWidth	string	The width of a single image. Default value: the width of the snapshot output resolution.	100
Margin	string	The width of the outer frame. Default value: 0. Unit: pixels.	5
Columns	string	The number of columns in the image sprite. Default value: 10.	10
IsKeepCellPic	string	Specifies whether to retain single images. Valid values: true: Retains single images. false: Does not retain single images. Default value: true.	false
Lines	string	The number of rows in the image sprite. Default value: 10.	10
Interval	string	The time interval between snapshots. If this parameter is specified, multi-frame snapshots are taken, and the value must be greater than 0. Unit: seconds. Default value: 10.	20
FrameType	string	The snapshot type. Default value: normal. Valid values: normal: normal frame. intra: I-frame (keyframe). Note If the Settings for the FrameType request parameter specify I-frame (keyframe), only keyframes are captured. If the specified time point is not a keyframe, the nearest keyframe is captured. Under the same snapshot rules, capturing keyframes is faster than capturing normal frames.	intra
Width	string	The width of the output snapshot image.	8
Height	string	The height of the output snapshot image.	8
OutputFile	object	The OSS configuration for the snapshot output.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The snapshot output file (OSS object).	test.png
Location	string	The data center where the OSS bucket for the snapshot output is located (OSS location).	example-location
Bucket	string	The OSS bucket where the snapshot output file is stored.	example
Num	string	The number of snapshots. If this parameter is specified, multi-frame snapshots are taken.	10
TileOutputFile	object	The OSS configuration for the output image sprite.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The output file (OSS object).	example.png
Location	string	The data center where the output OSS bucket is located (OSS location).	example-location
Bucket	string	The OSS bucket where the output file is stored.	example
TimeArray	object
TimePointList	array	The array of specified time points.
	integer	The array of specified time points. Unit: milliseconds. The value is a floating-point number with two decimal places. The values can be duplicate and submitted out of order, and are sorted by MPS. A maximum of 100 time points can be specified. When this parameter is specified, do not specify the Num, Time, or Interval parameter. Otherwise, the InvalidParameter.Ambiguity error is returned.	[10050, 50000, 110000, 1000500, 1100500]
State	string	The snapshot status. Valid values: Submitted: The job is submitted. Snapshoting: The snapshot is being taken. Success: The job is successful. Fail: The job fails.	Snapshoting
Message	string	The error message returned when the job fails. This parameter is not returned if the job is successful.	The resource operated InputFile is bad
MNSMessageResult	object	The result of the MNS notification for job completion.
MessageId	string	The message ID returned when the job is successful. This parameter is not returned if the job fails.	799454621135656C7F815F198A76****
ErrorMessage	string	The error message returned when the job fails. This parameter is not returned if the job is successful.	The resource operated InputFile is bad
ErrorCode	string	The error code returned when the job fails. This parameter is not returned if the job is successful.	InvalidParameter
Input	object	The job input.
RoleArn	string	The ARN of the specified role. Format: acs:ram::$accountID:role/$roleName.	acs:ram::1:role/testrole
Object	string	The input file (OSS object).	example.flv
Location	string	The data center where the input OSS bucket is located (OSS location).	example-location'
Bucket	string	The OSS bucket where the input file is stored.	example
Count	string	The number of captured images.	1
TileCount	string	The number of images in the image sprite.	5
UserData	string	The custom user data.	testid-001
Code	string	The error code returned when the job fails. This parameter is not returned if the job is successful.	ResourceContentBad
PipelineId	string	The MPS queue ID.	dd3dae411e704030b921e52698e5****
Id	string	The snapshot job ID.	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.