Help Center> Media Processing Center> API Reference> Snapshot APIs> Creating a Snapshot Task
View PDF

Creating a Snapshot Task

Function

This API is used to create a snapshot task to capture snapshots from a video 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 to access the OBS bucket has been granted. Constraints: Currently, only animated GIF files can be generated.

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 a 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 is obtained by calling the IAM API used to obtain a user token. The token is the value of X-Subject-Token in the response header.

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 enable synchronous processing. Synchronous processing quickly locates the snapshot position to take a snapshot.

Possible values:

  • 0: Synchronous processing is not enabled. Video metadata is not synchronized. It is queued for processing.

  • 1: Synchronous processing is enabled. Currently, only one snapshot can be captured at each interval. Default value: 0.

sync

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 delivered output directory to prevent the snapshots with the same output URI from being overwritten.

  • 1: The original output directory is used. Default value: 0.

original_dir

No

Integer

Whether to use the original output directory.

Possible values are:

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

File path.

  • If this parameter is used for an input, a specific path must be specified.

  • If this parameter is used for an output, only the directory for storing the outputs needs to be specified.

file_name

No

String

Name of an output file. This parameter is valid only for packaging tasks.

  • 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 allocated by MPC.
Table 5 ThumbnailPara

Parameter

Mandatory

Type

Description

type

No

String

Sampling type.

Possible values are:

  • PERCENT: Snapshots are captured based on the percentage of the video duration.

  • TIME: Snapshots are captured at certain intervals.

  • DOTS: Snapshots are captured a fixed time point.

Default value: TIME

time

No

Integer

Interval for taking snapshots.

Default value: 12

Unit: second

start_time

No

Integer

Start time if the sampling type is TIME. This parameter is used together with time.

Default value: 0

Unit: second

duration

No

Integer

Duration if the sampling type is TIME. This parameter is used together with time and start_time. Snapshots are captured every time.

ToEND indicates that sampling lasts until the end of the video.

Default value: ToEND

Unit: second

It must be greater than or equal to 0. If this is 0, snapshots are captured from start_time to the video end time.

dots

No

Array of integers

Array of time points when a snapshot is taken. A maximum of 10 time points are supported.

output_filename

No

String

Name of a snapshot file.

  • If only one image is extracted (the sampling type is DOTS), the image is output based on the specified file name.

  • If multiple images are extracted (the sampling type is DOTS or TIME), the time point is added to the name of the output image file, for example, output_filename_10.jpg.

  • If extracted images are going to be compressed into a TAR package, the TAR package is generated based on the specified file name.

format

No

Integer

Snapshot file format.

The value is:

1: jpg

aspect_ratio

No

Integer

Aspect ratio.

width

No

Integer

Snapshot width

height

No

Integer

Snapshot height

max_length

No

Integer

The longest side of a snapshot. The other side of the snapshot is scaled proportionally with the longest side and input video pixel.

Value range: 240 to 3,840

Default value: 480

Unit: pixel

NOTE:

If this parameter and width/height are both set, the width/height is used. If both the width and height are not 0, the longest side is the width/height. Otherwise, the longest side is the value of max_length. If this parameter and width/height are not set, max_length is 480 by default.

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

File path.

  • If this parameter is used for an input, a specific path must be specified.

  • If this parameter is used for an output, only the directory for storing the outputs needs to be specified.

file_name

String

Name of an output file. This parameter is valid only for packaging tasks.

  • 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 allocated by MPC.

Status code: 400

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

POST https://{endpoint}/v1/{project_id}/thumbnails
 {
    "input": {
               "bucket": "example-bucket",
               "location": "region1",
               "object": "/VOD/input/sample.MP4"
    },
    "output": {
               "bucket": "example-bucket",
               "location": "region1",
               "object": "/VOD/output/"
    },

    "tar" : 1,
    "thumbnail_para": {
        "time":2,
        "format":1,
        "aspect_ratio":1,
        "max_length":480
    }
    }

  }

Example Responses

Status code: 202

Snapshot task created successfully.

{
  "task_id" : 100211
}

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