Help Center/ Media Processing Center/ API Reference/ Video Metadata Extraction APIs/ Creating a Video Parsing Task

Updated on 2025-03-20 GMT+08:00

Online Debugging

CLI Examples

View PDF

Creating a Video Parsing Task

Function

This API is used to create a task to parse the metadata of a video file.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/extract-metadata

**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	No	ObsObjInfo object	Input file information. NOTE: Videos in M3U8 format cannot be converted to animated GIFs, perform synchronous parsing or snapshot capturing.
output	No	ObsObjInfo object	Output file information
user_data	No	String	Custom user data
sync	No	Integer	Whether to enable synchronous processing. 0: Synchronous processing is not enabled. Video metadata is not synchronized. It is queued for processing. 1: Synchronous processing is enabled. Video metadata is synchronized. Default value: 0
encryption	No	Encryption object	Video encryption parameter.

**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** Encryption
Parameter	Mandatory	Type	Description
hls_encrypt	No	HlsEncrypt object	Encryption parameters for HLS videos

**Table 6** HlsEncrypt
Parameter	Mandatory	Type	Description
key	Yes	String	Base64-encoded content encryption key
url	Yes	String	The key carries the service address, and can be decrypted to play HLS segments.
iv	No	String	Initial vector, which is a random number in base64Binary format
algorithm	No	String	Encryption algorithm. Possible values: AES-128-CTR AES-128-CBC Default value: AES-128-CTR

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
task_id	String	Task ID.
status	String	Task status.
create_time	String	Task creation time.
output	ObsObjInfo object	Output file information.
output_file_name	String	Output file name.
description	String	Task description. If a task is abnormal, this parameter indicates error details.
metadata	MetaData object	Metadata of a video file.

**Table 8** 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.

**Table 9** MetaData
Parameter	Type	Description
size	Long	File size Unit: byte
duration_ms	Double	Video duration, with decimal places Unit: second
duration	Long	Video duration Unit: second
format	String	File container format
md5	String	The MD5 value of the video.
bitrate	Long	Total bitrate Unit: bit/s
video	Array of VideoInfo objects	Video metadata
audio	Array of AudioInfo objects	Audio metadata

**Table 10** VideoInfo
Parameter	Type	Description
width	Integer	Video width
height	Integer	Video height
bitrate	Integer	Video bitrate. Unit: kbit/s NOTE: On August 7, 2024, the following modification was made on the video parsing API: Before: If sync in a synchronous video parsing task is set to 1, the unit of bitrate in VideoInfo of the response is bit/s. After: In a synchronous video parsing task, the unit of bitrate in VideoInfo of the response is changed to kbit/s. The preceding update may impact your transcoding workloads. Pay attention to the update and adjust your workloads accordingly.
bitrate_bps	Long	Video bitrate Unit: bit/s
frame_rate	Integer	Frame rate. The value is 0 or ranges from 5 to 60. The value 0 indicates adaptive frame rate. Unit: FPS NOTE: If the configured frame rate is not within the value range, the value is automatically changed to 0. If the configured frame rate is higher than the frame rate of the input file, the value is automatically changed to the frame rate of the input file.
codec	String	Video codec
duration	String	Video stream duration, unit: seconds
duration_ms	String	Video stream duration, unit: milliseconds
rotate	Float	The angle of the video shot, in degrees.

**Table 11** AudioInfo
Parameter	Type	Description
codec	String	Audio codec
sample	Integer	Audio sampling rate
channels	Integer	Number of audio channels
bitrate	Integer	Audio bitrate Unit: kbit/s
bitrate_bps	Long	Audio bitrate Unit: bit/s
duration	String	Audio stream duration, unit: seconds
duration_ms	String	Audio stream duration, unit: milliseconds

Status code: 400

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

Example Requests

Creates a task to parse the metadata of a video file.

POST https://{endpoint}/v1/{project_id}/extract-metadata

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.flv"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output"
  },
  "sync" : 0
}

Example Responses

Status code: 400

Failed to create a video parsing task.

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

Status Codes

Status Code	Description
200	Video parsing task created successfully.
400	Failed to create a video parsing task.

Error Codes

See Error Codes.

Parent Topic: Video Metadata Extraction APIs

Previous topic: Video Metadata Extraction APIs

Next topic: Querying Video Parsing 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