edit-icon download-icon

SubmitSnapshotJob

Last Updated: Apr 20, 2018

Description

The SubmitSnapshotJob API submits screenshot tasks. JPG images are supported currently.

  • Synchronous mode: A screenshot result is synchronously returned over the API, and a screenshot is generated in the corresponding bucket during result returning.
  • Asynchronous mode: A screenshot may not be generated when a screenshot result is returned over the API. The screenshot task queues at the background, and the screenshot is taken asynchronously. If either the Interval or Num parameter is set, the asynchronous mode is used.
  • Message notification: If the PipelineId parameter is set, an asynchronous message is sent when a screenshot task is submitted.

Request parameters

Parameter Type Required or not Description
Action String Yes API of the action, system required parameter. Set this parameter to SubmitSnapshotJob.
Input String Yes Task input, which is a JSON object. For the Input definition, see the glossary. Example: {"Bucket":"example-bucket", "Location": "oss-cn-hangzhou", "Object": "example.flv"} The bucket permission must be granted to Media Transcoding in the console.
SnapshotConfig String Yes Screenshot configuration, which is a JSON object. For details, see “11. SnapshotConfig” in Parameters” of “Appendix.” Example:
- Synchronous mode:
{"OutputFile": {"Bucket": "example-001","Location": "oss-cn-hangzhou", "Object": "example.jpg"}, "Time": "5"}
- Asynchronous mode: (start at 5 ms, one screenshot is taken per 20s, and 10 screenshots need to be taken): {"OutputFile": {"Bucket": "example-001", "Location": "oss-cn-hangzhou", "Object": "{Count}.jpg"}, "Time": "5", "Num":"10", "Interval":"20" }
PipelineId String No Media Processing queue ID. Ensure that the Media Processing queue is bound to an available message subject. Otherwise, the message cannot be properly sent.
UserData String No Custom data, up to 1,024 bytes.

Return parameters

Name Type Description
SnapshotJob AliyunSnapshotJob Screenshot task

Example

Request example

  1. http://mts.cn-hangzhou.aliyuncs.com?Action=SubmitSnapshotJob&Input=%7b%22Bucket%22%3a%22example-bucket%22%2c%22Location%22%3a%22oss-cn-hangzhou%22%2c%22Object%22%3a%22example.flv%22%7d&SnapshotConfig=%7B%22OutputFile%22%3A%7B%22Bucket%22%3A%22example-001%22%2C%22Location%22%3A%22oss-cn-hangzhou%22%2C%22Object%22%3A%22example.jpg%22%7D%2C%22Time%22%3A%225%22%7D&PipelineId=88c6ca184c0e47098a5b665e2a126797<Public parameter>

Return example

XML

  1. <SubmitSnapshotJobResponse>
  2. <RequestId>
  3. 25818875-5F78-4A13-BEF6-D7393642CA58
  4. </RequestId>
  5. <SnapshotJob>
  6. <Id>88c6ca184c0e47098a5b665e2a126797</Id>
  7. <State>Success</State>
  8. <Code> </Code>
  9. <Message> </Message>
  10. <SnapshotConfig>
  11. <OutputFile>
  12. <Bucket>example-001</Bucket>
  13. <Location>oss-cn-hangzhou</Location>
  14. <Object>example.png</Object>
  15. </OutputFile>
  16. <Time>4</Time>
  17. </SnapshotConfig>
  18. <PipelineId>88c6ca184c0e47098a5b665e2a126797</PipelineId>
  19. <UserData>testid-001</UserData>
  20. <CreationTime>2014-01-10T12:00:00Z</CreationTime>
  21. </SnapshotJob>
  22. </SubmitSnapshotJobResponse>

JSON

  1. {
  2. "RequestId": "25818875-5F78-4A13-BEF6-D7393642CA58",
  3. "SnapshotJob": {
  4. "Id": "88c6ca184c0e47098a5b665e2a126797",
  5. "State": "Success",
  6. "Code": "",
  7. "Message": "",
  8. SnapshotConfig”:{
  9. "OutputFile": {
  10. "Bucket": "example-001",
  11. "Location": "oss-cn-hangzhou",
  12. "Object": "example.png"
  13. },
  14. Time”:”5
  15. },
  16. "PipelineId": "88c6ca184c0e47098a5b665e2a126797",
  17. "UserData": "testid-001",
  18. "CreationTime": "2014-01-10T12:00:00Z"
  19. }
  20. }

Screenshot error codes

Error code Description Detailed information
InvalidParameter.ResourceNotFound The screenshot file cannot be found. The resource operated cannot be found.
SnapshotTimeOut The screenshot times out. If time-out occurs frequently in synchronous mode, we recommend that the asynchronous mode be used to prevent time-out. Retry is not recommended. Snapshot times out.
InvalidParameter.ResourceContentBad The screenshot file is damaged, or the screenshot fails to be taken because it does not meet the specifications. The resource operated is broken.
EntityNotExist.Role The role does not exist. The role not exists.
PermissionDenied.ResourceAccess The operation has no authorization. MTS is not authorized to operate on the specified resource.
InternalError Internal unrecognized error The operation has failed due to some unknown error, exception or failure.
TransientNetWorkError A temporary network error occurs during data download. Generally, you can recover the download by retry. Snapshot fail, transient network error occurs, please try again.
Thank you! We've received your feedback.