All Products
Search

This Product

    ApsaraVideo VOD:SubmitSnapshotJob

    Document Center

    ApsaraVideo VOD:SubmitSnapshotJob

    Last Updated:Aug 04, 2023

    Submits a snapshot job for a video and starts asynchronous snapshot processing.

    Operation Description

    Note
  • Only snapshots in the JPG format are generated.
  • After a snapshot job is complete, ApsaraVideo VOD sends a SnapshotComplete event notification that contains EventType=SnapshotComplete and SubType=SpecifiedTime.

    • Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    vod:SubmitSnapshotJobWrite
    • VOD
      acs:vod:*:{#accountId}:*
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    VideoIdstringYes

    The ID of the video.

    		d3e680e618708efbf2cae7cc9312****
    SpecifiedOffsetTimelongNo

    The start time of the specified snapshot time period.

    • Unit: milliseconds.
    • Default value: 0.
    		0
    WidthstringNo

    The width of each snapshot. Valid values: [8,4096]. By default, the width of the video mezzanine file is used. Unit: pixel.

    		1280
    HeightstringNo

    The height of each snapshot. Valid values: [8,4096]. By default, the height of the video mezzanine file is used. Unit: pixel.

    		720
    CountlongNo

    The maximum number of snapshots. Default value: 1.

    		1
    IntervallongNo

    The snapshot interval. The value must be greater than or equal to 0. Unit: seconds. If you set this parameter to 0, snapshots are taken at even intervals based on the video duration divided by the value of the Count parameter. Default value: 1.

    		1
    SpriteSnapshotConfigstringNo

    The sprite snapshot configuration. If you set this parameter, sprite snapshots are generated. For more information, see SpriteSnapshotConfig.

    		{'CellWidth': 120, 'CellHeight': 68, 'Columns': 3,'Lines': 10, 'Padding': 20, 'Margin': 50}
    SnapshotTemplateIdstringNo

    The ID of the snapshot template.

    • We recommend that you create a snapshot template before you specify the ID of the snapshot template.
    • If you set the SnapshotTemplateId parameter, all the other request parameters except the Action and VideoId parameters are ignored.
    • For more information about how to create a snapshot template, see AddVodTemplate.
    		f5b228fe693bf55bd87b789****
    UserDatastringNo

    The custom configurations, including the configuration of transparent data transmission and callback configurations. The value is a JSON-formatted string. For more information, see UserData.

    **

    Note The callback configurations take effect only when you specify the HTTP callback URL and select the specific callback events in the ApsaraVideo VOD console.

    		{"MessageCallback":{"CallbackURL":"http://.example.aliyundoc.com"},"Extend":{"localId":"xxx","example":"www"}}
    NoteYou must set at least one of the Count and Interval parameters. If you set both of them, the setting with fewer snapshots generated prevails.

    Response parameters

    ParameterTypeDescriptionExample
    object

    Response result.

    RequestIdstring

    The ID of the request.

    		25818875-5F78-5EB0-4AF6-D7393642****
    SnapshotJobobject

    The information about the snapshot job.

    JobIdstring

    The ID of the snapshot job.

    		ad90a501b1b94b72374ad0050464****

    Examples

    Sample success responses

    JSONformat

    {
  "RequestId": "25818875-5F78-5EB0-4AF6-D7393642****",
  "SnapshotJob": {
    "JobId": "ad90a501b1b94b72374ad0050464****"
  }
}

    Error codes

    For a list of error codes, visit the Service error codes.

    Common errors

    The following table describes the common errors that this operation can return.

    Error codeError messageHTTP status codeDescription
    InvalidVideo.NotFoundThe video does not exist.404The error message returned because the video does not exist.
    NoSuchResourceThe specified resource %s does not exist.404The error message returned because the specified resource does not exist.
    Forbidden.IllegalStatusStatus of the video is illegal.400The error message returned because the video status is invalid. You can submit a snapshot job for a video only when the video is in the UploadSucc, Normal, Checking, or Blocked state.