Creating a Clipping Task

Function

Creates a clip task on media files to generate a new file.

Scenarios:

Clips a single media file to generate a new file.
Clips multiple segments of a single media file and combine them into a new file.
Combines multiple media files to generate a new file.

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.

Note: This function does not support OpenGOP sources.

Calling Method

For details, see Calling APIs.

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

Write

-

-

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
mpc:editingTask:create	Write	-	-	-	-

URI

POST /v2/{project_id}/editing/jobs

**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
inputs	No	Array of EditingInput objects	Specifies multiple clipping segments of the source.
output	No	ObsObjInfo object	Output address
editing_settings	No	EditingSetting object	Media processing configuration to process the source files specified in input parameters.
metadata	No	Array of FileMetaData objects	Metadata setting. By default, only AIGC is supported.
user_data	No	String	User customized data
editing_type	No	Integer	Clipping type. You are advised to set this parameter to 1. If this parameter is set to 0, the performance and clipping capability do not meet the commercial use conditions. Options: 0: directly concatenates multiple files, or slices and concatenates segments from a single file. The default value is 0, which is not recommended because the performance and capability do not meet the commercial use conditions. 1: edits multiple files individually and then concatenates the edited segments in sequence.

**Table 4** EditingInput
Parameter	Mandatory	Type	Description
input	Yes	ObsObjInfo object	Input file storage location
timeline_start	No	String	Clipping start time, in seconds.
timeline_end	No	String	Clipping end time, in seconds.

**Table 5** 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 6** EditingSetting
Parameter	Mandatory	Type	Description
resolution_adaptation	No	String	Resolution adaptation policy. Values: open (default) and close. If the input is open, width indicates the long side and height indicates the short side.
resolution_upsample	No	String	Indicates whether to enable resolution upsampling. Values: on and off (default).
format	No	String	Output format. The options are HLS, MP4, FLV, MOV, and AVI. MP4 is the default value. FLV does not support multi-audio, and AVI does not support H.265 encoding.
width	No	Integer	Outputs width or the long side, in integer. For an input number with decimals, the integral part of it is used. Default: 0. If both width and height are 0, the source resolution is used. If width is 0 but height is not 0, width is scaled proportionally based on the source resolution. If width is not 0 but height is 0, height is scaled proportionally based on the source resolution. If neither width nor height is 0, resolution is manually specified.
height	No	Integer	Outputs height or the short side, in integer. For an input number with decimals, the integral part of it is used. Default: 0. If width and height are 0, the source resolution is used. If width is 0 but height is not 0, width is scaled proportionally based on the source resolution. If width is not 0 and height is 0, height is scaled proportionally based on the source resolution. If neither width nor height is 0, resolution is manually specified.
reference	No	String	(Optional) Outputs reference benchmark. Default: NONE NONE: The output resolution is the resolution of the first input source. The bitrate is adaptive to the output resolution. The frame rate is fixed at 25 FPS. MAX_BITRATE: The maximum bitrate among the sources is used. MAX_RESOLUTION: The maximum resolution among the sources is used.
video_codec	No	Integer	Video codec. The options include: 1: VIDEO_CODEC_H264 2: VIDEO_CODEC_H265

**Table 7** FileMetaData
Parameter	Mandatory	Type	Description
name	No	String	Metadata name.
value	No	String	Metadata value.

Response Parameters

Status code: 200

**Table 8** Response header parameters
Parameter	Type	Description
X-Request-Id	String	This field indicates the unique request identifier used for tracing task process. Format: request_id(uuid)-timestamp-hostname

**Table 9** Response body parameters
Parameter	Type	Description
job_id	String	Task ID generated after a task is accepted

Status code: 400

**Table 10** Response header parameters
Parameter	Type	Description
X-Request-Id	String	This field indicates the unique request identifier used for tracing task process. Format: request_id(uuid)-timestamp-hostname

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

Status code: 500

**Table 12** Response header parameters
Parameter	Type	Description
X-Request-Id	String	This field indicates the unique request identifier used for tracing task process. Format: request_id(uuid)-timestamp-hostname

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

Example Requests

Creates a clip task on media files to generate a new file.

POST https://{endpoint}/v2/{project_id}/editing

{
  "inputs" : [ {
    "input" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-path/input.ts"
    },
    "timeline_start" : "0",
    "timeline_end" : "10"
  }, {
    "input" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-path/input.ts"
    },
    "timeline_start" : "30",
    "timeline_end" : "40"
  }, {
    "input" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-path/input.ts"
    },
    "timeline_start" : "50",
    "timeline_end" : "0"
  } ],
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output",
    "file_name" : "output.m3u8"
  },
  "editing_settings" : {
    "resolution_adaptation" : "OPEN",
    "reference" : "MAX_RESOLUTION",
    "format" : "HLS",
    "width" : 0,
    "height" : 720
  },
  "user_data" : "example_user_data"
}