All Products
Search
Document Center

ApsaraVideo VOD:SubmitSnapshotJob

Last Updated:Dec 14, 2022

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 is the authorization information corresponding to the API, which can be found in the RAM permission policy statement.Action Used in the element to grant the RAM user or RAM role permission to call this API. The specific instructions are as follows:

    • 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 keyword: refers to the condition keyword defined by the cloud product itself.
    • 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.
    Operateaccess levelResource typeconditional keywordAssociation operation
    vod:SubmitSnapshotJobWrite
    • VOD
      acs:vod:*:{#accountId}:*
      without
    without

    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****

    Example

    Normal return example

    JSONFormat

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

    Error codes

    For a list of error codes, visit the API error center.

    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.