Help Center/ Media Processing Center/ API Reference/ Snapshot APIs/ Creating a Snapshot Task

Updated on 2024-03-14 GMT+08:00

View PDF

Creating a Snapshot Task

Function

This API is used to create a task for capturing snapshots from the first to the last frame at every set interval. Ensure that an input media file is stored in an OBS bucket in the same region as MPC and the permission for accessing the OBS bucket has been granted to MPC.

Constraints: Currently, only JPG image files can be generated.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/thumbnails

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID .

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.
Authorization	No	String	Authentication information. This parameter is mandatory when AK/SK-based authentication is used.
X-Project_Id	No	String	Project ID. This parameter is mandatory when AK/SK-based authentication is used. It is same as the project ID in path parameters.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
input	Yes	ObsObjInfo object	Storage location of an input file
output	Yes	ObsObjInfo object	Storage location of an output file
user_data	No	String	Custom user data
thumbnail_para	Yes	ThumbnailPara object	Snapshot parameters
tar	No	Integer	Whether to compress captured snapshots to a TAR package. Possible values: 0: Captured snapshots are compressed to a TAR package. 1: Captured snapshots are not compressed to a TAR package. Default value: 1
sync	No	Integer	Whether to enable synchronous processing. Synchronous processing quickly locates the snapshot position to capture a snapshot. The options are as follows: 0: queuing and asynchronous snapshot capturing 1: synchronous snapshot capturing. Only one snapshot can be captured at each set interval. Default value: 0
original_dir	No	Integer	Whether to use the original output directory. Possible values: 0: The original output directory is not used. A random directory is added to the end of the output directory to prevent the snapshot file with the same outputUri from being overwritten. 1: The original output directory is used. Default value: 0

**Table 4** ObsObjInfo
Parameter	Mandatory	Type	Description
bucket	Yes	String	OBS bucket name
location	Yes	String	Region where an OBS bucket is located. It must be the same as the region where MPC is deployed.
object	Yes	String	OBS object path, which complies with the OSS Object definition. If this parameter is used for an input, an object must be specified. If this parameter is used for an output, only the directory for storing the output needs to be specified.
file_name	No	String	File name If this parameter is specified, the output object name is object/file_name. If this parameter is not specified, the output object name is object/xxx, where xxx is specified by MPC. When it is used as the output file name: Specifies the name of the output file. This parameter is valid for packaging. If the output file name needs to be specified during transcoding, use the output_filenames parameter. This parameter is valid for parsing. If a file name is specified during parsing, the parsing parameters are written to the specified file name and the file metadata is obtained through the query API response in JSON format. This parameter is invalid for snapshot capturing. This parameter is invalid for conversion into animated GIFs.

**Table 5** ThumbnailPara
Parameter	Mandatory	Type	Description
type	No	String	Sampling type Possible options are: TIME: Snapshots are captured at certain intervals. DOTS: Snapshots are captured at specific time points. Select this type for single snapshot capture. Default value: TIME
time	No	Integer	Interval for capturing snapshots. Default value: 12 Unit: second
start_time	No	Integer	Start time for the sampling type set to TIME. This parameter is used together with time. Default value: 0 Unit: second NOTE: If the value of start_time exceeds the media file duration, frames are not extracted.
duration	No	Integer	Capture duration when the sampling type is set to TIME. This parameter is used together with time and start_time, indicating that the first snapshot is captured at the time specified by start_time and snapshots are captured at the interval specified by time until the duration specified by this parameter elapses. Value range: [Number, ToEND]. ToEND indicates that snapshot capturing lasts till the end of the video. Default value: ToEND Unit: second NOTE: 0 indicates that snapshot capturing lasts from start_time to the end of the video.
dots	No	Array of integers	Array of time points when a snapshot is captured For example, if you enter [1,3,5], the image frames at the first, third, and fifth seconds of the video are captured. Asynchronous snapshot capturing: A maximum of 10 time points are supported. Synchronous snapshot capturing: Only one time point is supported.
dots_ms	No	Array of integers	Time point array of snapshot at a specified time in synchronous snapshot mode, in milliseconds. For example, enter [1000] to capture the image frame at the 1000th ms position of the video. Only one time point is allowed.
output_filename	No	String	Snapshot file name If only one snapshot is captured (the sampling type is DOTS and only one time point is specified), the output file name is the specified snapshot file name. If multiple snapshots are captured (the sampling type is DOTS and multiple time points are specified or the sampling type is TIME), an output file name contains the specified snapshot file name followed by the time point, for example, output_filename_10.jpg. If you specify the snapshots to be compressed into a TAR package, the output file name is the TAR package name.
format	No	Integer	Snapshot file format. The value is: 1: JPG
width	No	Integer	Image width The options are as follows: [96,3840] 0: adaptive (the original aspect ratio is retained) Unit: pixel
height	No	Integer	Image height The options are as follows: [96,2160] 0: adaptive (the original aspect ratio is retained) Unit: pixel
max_length	No	Integer	The longest side of a snapshot. The width of the snapshot is scaled proportionally with the longest side and input video pixel. The value ranges from 240 to 3,840. Unit: pixel NOTE: This parameter is used together with width/height. If neither width nor height is 0, the image size is calculated based on width/height. Otherwise, the image size is calculated based on max_length. If this parameter and width/height are not selected, snapshots are output based on the aspect ratio of the source media file.

Response Parameters

Status code: 202

**Table 6** Response body parameters
Parameter	Type	Description
task_id	String	Task ID
status	String	Task status
create_time	String	Time when a task is created
output	ObsObjInfo object	Storage location of snapshots
output_file_name	String	Snapshot file name
thumbnail_time	String	Capture time
description	String	Task description

**Table 7** ObsObjInfo
Parameter	Type	Description
bucket	String	OBS bucket name
location	String	Region where an OBS bucket is located. It must be the same as the region where MPC is deployed.
object	String	OBS object path, which complies with the OSS Object definition. If this parameter is used for an input, an object must be specified. If this parameter is used for an output, only the directory for storing the output needs to be specified.
file_name	String	File name If this parameter is specified, the output object name is object/file_name. If this parameter is not specified, the output object name is object/xxx, where xxx is specified by MPC. When it is used as the output file name: Specifies the name of the output file. This parameter is valid for packaging. If the output file name needs to be specified during transcoding, use the output_filenames parameter. This parameter is valid for parsing. If a file name is specified during parsing, the parsing parameters are written to the specified file name and the file metadata is obtained through the query API response in JSON format. This parameter is invalid for snapshot capturing. This parameter is invalid for conversion into animated GIFs.

Status code: 400

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

Example Requests

Creates an asynchronous snapshot capturing task to capture snapshots from a video at every set interval.

POST https://{endpoint}/v1/{project_id}/thumbnails

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.mp4"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output"
  },
  "tar" : 1,
  "thumbnail_para" : {
    "time" : 2,
    "format" : 1,
    "max_length" : 480
  },
  "sync" : 0
}

Creates a synchronous snapshot capturing task (sync set to 1) to capture snapshots from a video at every set interval.

POST https://{endpoint}/v1/{project_id}/thumbnails

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.mp4"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output"
  },
  "tar" : 1,
  "thumbnail_para" : {
    "time" : 2,
    "format" : 1,
    "max_length" : 480
  },
  "sync" : 1
}

Example Responses

Status code: 202

Snapshot task created successfully.

Asynchronous snapshot capturing task created.
```
{
  "task_id" : "100211"
}
```

Synchronous snapshot capturing task created.

{
  "task_id" : "100212",
  "status" : "FINISHED",
  "create_time" : "20231201020412",
  "output" : {
    "bucket" : "bucket-demo",
    "location" : "cn-north-4",
    "object" : "output/demo_object",
    "file_name" : ""
  },
  "output_file_name" : "H_270.png",
  "thumbnail_time" : "30",
  "description" : "Task completed."
}

Status code: 400

Failed to create a snapshot task.

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter"
}

Status Codes

Status Code	Description
202	Snapshot task created successfully.
400	Failed to create a snapshot task.

Error Codes

See Error Codes.

Parent Topic: Snapshot APIs

Previous topic: Snapshot APIs

Next topic: Querying Snapshot Tasks

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot