Help Center/ Video On Demand/ API Reference/ Media Asset Editing/ Creating an Editing Task
Updated on 2026-03-20 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating an Editing Task

Function

This API is used to create an editing task.

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

    vod:asset:createEditTask

    Write

    assets *

    vod:AssetLabel

    -

    -

URI

POST /v1/{project_id}/asset/editing/tasks

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token. This parameter is mandatory when token authentication is used.

It 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 for AK/SK authentication.

X-Sdk-Date

No

String

Time when a request is sent. This parameter is mandatory for AK/SK authentication.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

inputs

Yes

Array of EditInput objects

List of media assets to be edited. A maximum of 20 media assets are supported.

editing_settings

No

VodEditingSetting object

Editing configuration.
Table 4 EditInput

Parameter

Mandatory

Type

Description

asset_id

Yes

String

Media asset ID.

timeline_start

Yes

String

Editing start time, in seconds. The maximum length is 32 characters.

timeline_end

Yes

String

Editing end time, in seconds. The maximum length is 32 characters.
Table 5 VodEditingSetting

Parameter

Mandatory

Type

Description

resolution_adaptation

No

Boolean

Resolution adaptation policy. The options are true (default) and false.

If it is set to true, width indicates the long side, and height indicates the short side.

If it is set to false, width indicates the width, and height indicates the height.

resolution_upsample

No

Boolean

Resolution upsampling. The options are true and false (default). If this parameter is set to false, the output follows the input resolution.

format

No

String

Output container format. The options are HLS, MP4 (default), MP3, MOV, FLV, and AVI.

Videos cannot be output to audio container formats.

width

No

Integer

Output width or long side. The value must be an integer. If a decimal is provided, only the integer part is used. The default value is 0, indicating the source aspect ratio is followed.

  • If both width and height are 0, the source resolution is maintained.

  • If width is 0 but height is not 0, the width is scaled proportionally based on the source aspect ratio.

  • If width is not 0 but height is 0, the height is scaled proportionally based on the source aspect ratio.

  • If neither width nor height is 0, the specified resolution is used.

  • For H.264, the width ranges from 32 to 4,096.

  • For H.265, the width ranges from 160 to 4,096.

height

No

Integer

Output height or short side. The value must be an integer. If a decimal is provided, only the integer part is used. The default value is 0, indicating the source aspect ratio is followed.

  • If both width and height are 0, the source resolution is maintained.

  • If width is 0 but height is not 0, the width is scaled proportionally based on the source aspect ratio.

  • If width is not 0 but height is 0, the height is scaled proportionally based on the source aspect ratio.

  • If neither width nor height is 0, the specified resolution is used.

  • For H.264, the height ranges from 32 to 2,880.

  • For H.265, the height ranges from 160 to 2,880.

reference

No

String

Output reference benchmark, which is optional. The default value is NONE.

  • NONE: uses the resolution of the first input. The bitrate scales adaptively based on the output resolution.

  • MAX_BITRATE: uses the highest bitrate found among all inputs.

  • MAX_RESOLUTION: uses the highest resolution among all inputs.

video_codec

No

Integer

Video codec.

Options:

  • 1: VIDEO_CODEC_H264

  • 2: VIDEO_CODEC_H265

Response Parameters

Status code: 200

Table 6 Response body parameters

Parameter

Type

Description

task_id

String

Editing task ID.

asset_id

String

Media asset ID.

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error description.

Example Requests

This example creates an editing task.

POST https://{endpoint}/v1/{project_id}/asset/editing/tasks

{
  "inputs" : [ {
    "asset_id" : "xxxxxx",
    "timeline_start" : "0",
    "timeline_end" : "5687"
  } ],
  "editing_settings" : {
    "format" : "MP4"
  }
}

Example Responses

Status code: 200

Returned when the request succeeded.

{
  "task_id" : "5723efduytasfd752352635",
  "asset_id" : "xxxxxxxxx"
}

Status Codes

Status Code

Description

200

Returned when the request succeeded.

400

Returned when the request failed.

Error Codes

See Error Codes.

Parent topic: Media Asset Editing