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.
Authorization Information
Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.
- If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
- If you are using identity policy-based authorization, the following identity policy-based permissions are required.
Action | Access Level | Resource Type (*: required) | Condition Key | Alias | Dependencies |
|---|
mpc:thumbnailsTask:create | Write | - | - | - | - |
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 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: 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: 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 where the output is to be stored needs to be specified.
A subtitle file name that contains special characters (such as [) will cause the transcoding task to fail. |
file_name | No | String | File name, which can contain a maximum of 180 characters. 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 an output file name: This parameter is valid for container format conversion. The output file name must be specified. If the output file name needs to be specified during transcoding, use the parameter output_filenames. 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 by querying JSON data in the API response. This parameter is invalid for snapshot capturing. This parameter is invalid for conversion into animated GIFs. When the output file is in HLS format, a file name containing index, such as index.m3u8, will cause playback failure.
|
Table 5 ThumbnailPara Parameter | Mandatory | Type | Description |
|---|
type | No | String | Sampling type Possible options are: Default value: TIME |
amount | No | Integer | If the black pixel ratio is greater than or equal to this threshold, the frame is classified as a black frame. |
threshold | No | Integer | If the pixel value is below this threshold, the pixel is treated as black. |
time | No | Integer | Interval for capturing snapshots. Value range: [1,100]. 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. |
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 snapshot 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: Unit: pixel |
height | No | Integer | Image height The options are as follows: 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. The options include: WAITING: pending PROCESSING: executing SUCCEEDED: successful FAILED: failed CANCELED: deleted
|
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 where the output is to be stored needs to be specified.
A subtitle file name that contains special characters (such as [) will cause the transcoding task to fail. |
file_name | String | File name, which can contain a maximum of 180 characters. 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 an output file name: This parameter is valid for container format conversion. The output file name must be specified. If the output file name needs to be specified during transcoding, use the parameter output_filenames. 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 by querying JSON data in the API response. This parameter is invalid for snapshot capturing. This parameter is invalid for conversion into animated GIFs. When the output file is in HLS format, a file name containing index, such as index.m3u8, will cause playback failure.
|
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. |
