Help Center/ Media Processing Center/ API Reference/ Snapshot APIs/ Creating a Snapshot Task
Updated on 2025-03-20 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

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. (tag:hc,hk)

Project ID. For details about how to obtain the project ID, see [Obtaining a Project ID]. (tag:hcso,g42,cmcc)

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

  • Correct example: demo.srt

  • Incorrect example: [demo.srt

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:

  • 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

amount

No

Integer

If the proportion of black pixels is greater than or equal to this value, the frame is considered black.

threshold

No

Integer

Pixels with values less than this value are considered black spots.

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

  • [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 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.

  • Correct example: demo.srt

  • Incorrect example: [demo.srt

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.

Error Codes

See Error Codes.

Parent Topic: Snapshot APIs