Creating a Transcoding Task
Function
This API is used to create a transcoding task to transcode media files, and add watermarks and capture snapshots during transcoding. A transcoding template must be configured before video transcoding. 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.
Calling Method
For details, see Calling APIs.
URI
POST /v1/{project_id}/transcodings
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
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
input |
No |
ObsObjInfo object |
Storage location of an input file. This parameter is mandatory in scenarios where audio is not added. |
output |
Yes |
ObsObjInfo object |
Storage location of an output file |
trans_template_id |
No |
Array of integers |
Transcoding template ID. If the av_parameter parameter is not contained, this parameter must be carried and its value is an array. Each transcoding output corresponds to a transcoding template ID. A maximum of nine template IDs are supported. Only the following parameters in transcoding templates can be changed: Video bitrate, height, and width |
av_parameters |
No |
Array of AvParameters objects |
Transcoding parameter If both trans_template_id and this parameter are specified, this parameter is preferentially used for transcoding. If trans_template_id is not specified, this parameter is mandatory. |
output_filenames |
No |
Array of strings |
Name of an output file. Each transcoded file has a name that corresponds to the sequence of the transcoding template ID array.
|
user_data |
No |
String |
Custom user data. You can call a query API or send a notification to transfer this field to users. |
watermarks |
No |
Array of WatermarkRequest objects |
Array of image watermarks. Up to 10 watermarks are supported. |
thumbnail |
No |
Thumbnail object |
Snapshot information
NOTE:
Snapshots are generated only when the transcoding template specified by trans_template_id or the output resolution specified by av_parameters is 1920 x 1080, 1280 x 720, 854 x 480, or 480 x 270. |
priority |
No |
Integer |
Task priority. Possible values:
|
subtitle |
No |
Subtitle object |
Subtitle parameters |
encryption |
No |
Encryption object |
Encryption parameters |
crop |
No |
Crop object |
Number of seconds cropped from a video for which transcoding is performed on. |
audio_track |
No |
AudioTrack object |
Audio track parameters |
multi_audio |
No |
MultiAudio object |
Multi-language and multi-channel audio parameters |
video_process |
No |
VideoProcess object |
Video processing parameters |
audio_process |
No |
AudioProcess object |
Audio processing parameters |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
video |
No |
VideoParameters object |
Video parameters |
audio |
No |
Audio object |
Audio parameters |
common |
Yes |
Common object |
Common parameters |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
output_policy |
No |
String |
Output policy:
The options are as follows:
|
codec |
No |
Integer |
Video codec. Possible values:
|
bitrate |
No |
Integer |
Average output bitrate Its value is 0 or an integer ranging from 40 to 50,000. Unit: kbit/s If this parameter is set to 0, the average output bitrate is an adaptive value. |
profile |
No |
Integer |
Encoding profile. Possible values:
|
level |
No |
Integer |
Encoding level Options:
|
preset |
No |
Integer |
Encoding quality. Possible options:
Default value: 1 |
max_iframes_interval |
No |
Integer |
Maximum I-frame interval. The value ranges from 2 to 10. Default value: 5 Unit: second |
bframes_count |
No |
Integer |
Maximum B-frame interval The options are as follows:
Unit: frame |
frame_rate |
No |
Integer |
Frame rate. The value is 0 (adaptive) or ranges from 5 to 60. 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. |
width |
No |
Integer |
Video width, in pixels
|
height |
No |
Integer |
Video height, in pixels
|
black_cut |
No |
Integer |
Whether to enable black bar removal.
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
output_policy |
No |
String |
Output policy:
The options are as follows:
|
codec |
No |
Integer |
Audio codec Possible options are:
|
sample_rate |
No |
Integer |
Audio sampling rate The options are as follows:
NOTE:
When the encoding format is MP3, the audio sampling ratio cannot be 6. |
bitrate |
No |
Integer |
Audio bitrate. The value is 0 or ranges from 8 to 1,000. Unit: kbit/s |
channels |
Yes |
Integer |
Number of audio channels Options:
When the media packaging format is audio (MP3), the number of audio channels cannot be set to 5.1. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
PVC |
No |
Boolean |
Whether to enable low-bitrate HD The options are as follows:
(The value 0 indicates that the function is disabled. Other positive integers and negative values indicate true.) |
hls_interval |
No |
Integer |
HLS segment duration. This parameter is used only when pack_type is set to 1 or 3. The value ranges from 2 to 10. Unit: second |
dash_interval |
No |
Integer |
DASH segment duration. This parameter is used only when pack_type is set to 2 or 3. The value ranges from 2 to 10. Unit: second |
pack_type |
Yes |
Integer |
Packaging type Possible options are:
NOTE:
If pack_type is set to 5 or 6, do not configure video parameters. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
input |
No |
ObsObjInfo object |
Storage location of an input file. This parameter is mandatory if an image watermark is used. |
template_id |
No |
String |
ID of a watermark template. You can call an API to create a watermark template. |
text_context |
No |
String |
Base64-coded text watermark. This parameter must be configured when type is set to Text. For example, if the text watermark to be added is "Test Text Watermark", the value of content is 5rWL6K+V5paH5a2X5rC05Y2w. |
image_watermark |
No |
ImageWatermark object |
Watermark parameters used for overwriting the parameters with the same names in the watermark template |
text_watermark |
No |
TextWatermark object |
Text watermark configurations. If text_context is set, this field cannot be left blank. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
dx |
No |
String |
Horizontal offset between the start point of the watermark and the vertex of the output video Possible options are:
For example, if the output video width is 1920 pixels, dx is set to 0.1, and referpos is set to TopRight, the horizontal offset between the upper right corner of the watermark and the right vertex of the video is 192. |
dy |
No |
String |
Vertical offset between the start point of the watermark and the vertex of the output video
For example, if the output video height is 1080 pixels, dy is set to 0.1, and referpos is set to TopRight, the vertical offset between the upper right corner of the watermark and the right vertex of the video is 108. |
referpos |
No |
String |
Watermark position. Possible values:
|
timeline_start |
No |
String |
Watermark start time, which is used together with timeline_duration. Its value is a digit. Unit: second |
timeline_duration |
No |
String |
Watermark duration, which is used together with timeline_start. The value ranges from number to ToEND. ToEND indicates that the watermark lasts until the end of the video. Default value: ToEND |
image_process |
No |
String |
Image watermark processing mode. This parameter is valid only when type is set to Image. The options are as follows:
|
width |
No |
String |
Watermark image width. The options are as follows:
|
height |
No |
String |
Watermark image height. The options are as follows:
|
base |
No |
String |
Video on which the watermark is overlaid. Possible values:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
dx |
No |
String |
Horizontal offset between the start point of the watermark and the vertex of the output video Possible options are:
For example, if the output video width is 1920 pixels, dx is set to 0.1, and referpos is set to TopRight, the horizontal offset between the upper right corner of the watermark and the right vertex of the video is 192. |
dy |
No |
String |
Vertical offset between the start point of the watermark and the vertex of the output video
For example, if the output video height is 1080 pixels, dy is set to 0.1, and referpos is set to TopRight, the vertical offset between the upper right corner of the watermark and the right vertex of the video is 108. |
referpos |
No |
String |
Watermark position. Possible values:
|
timeline_start |
No |
String |
Watermark start time, which is used together with timeline_duration. Its value is a digit. Unit: second |
timeline_duration |
No |
String |
Watermark duration, which is used together with timeline_start. The value ranges from number to ToEND. ToEND indicates that the watermark lasts until the end of the video. Default value: ToEND |
font_name |
No |
String |
Font. Only fzyouh is supported. |
font_size |
No |
Integer |
Font size The value ranges from 4 to 120. |
font_color |
No |
String |
Font color. The options are as follows: black, blue, white, green, red, yellow, brown, gold, pink, orange, and purple |
base |
No |
String |
Video on which the watermark is overlaid. Possible values:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
tar |
No |
Integer |
Whether to compress captured snapshots to a TAR package. Possible values:
|
out |
No |
ObsObjInfo object |
Storage location of snapshots. If this parameter is not set, snapshots are stored in the same location as the output file. |
params |
Yes |
ThumbnailPara object |
Snapshot parameters |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
type |
No |
String |
Sampling type Possible options are:
Default value: TIME |
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.
|
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
|
format |
No |
Integer |
Snapshot file format. The value is: 1: JPG |
width |
No |
Integer |
Image width The options are as follows:
Unit: pixel |
height |
No |
Integer |
Image height The options are as follows:
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. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
input |
No |
ObsObjInfo object |
Storage location of an SRT file |
inputs |
No |
Array of MulInputFileInfo objects |
Storage location of SRT files |
subtitle_type |
No |
Integer |
Subtitle file type. Possible values:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
language |
No |
String |
Subtitle language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended. |
input |
No |
ObsObjInfo object |
Storage location of a subtitle file |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
hls_encrypt |
No |
HlsEncrypt object |
Encryption parameters for HLS videos |
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:
Default value: AES-128-CTR |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
duration |
No |
Integer |
Duration of a captured video, starting from 0 seconds. Unit: second |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
type |
No |
Integer |
Audio track selection method. Possible values:
|
left |
No |
Integer |
ID of the audio track where the left audio channel is |
right |
No |
Integer |
ID of the audio track where the right audio channel is |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
tracks_info |
No |
Array of TracksInfo objects |
Audio track information |
audio_files |
No |
Array of AudioFile objects |
Parameters about a single audio file |
default_language |
No |
String |
Default language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
tracks_info |
No |
Array of TracksInfo objects |
Audio track information |
input |
No |
ObsObjInfo object |
Storage location of an input file |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
channel_layout |
No |
String |
Audio channel layout of the audio track |
language |
No |
String |
Audio language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended. |
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.
|
file_name |
No |
String |
File name
When it is used as the output file name:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
hls_init_count |
No |
Integer |
Number of HLS start segments The value ranges from 0 to 10 and defaults to 0.
NOTE:
This parameter is used together with hls_init_interval to specify the duration of the first hls_init_count HLS segments. The value 0 indicates that there are no HLS start segments. |
hls_init_interval |
No |
Integer |
Duration of the first hls_init_count HLS segments The value ranges from 2 to 10 and defaults to 5.
NOTE:
This parameter is valid only when the value of hls_init_count is not 0. |
hls_storage_type |
No |
String |
HLS media streams storage
|
rotate |
No |
Integer |
Clockwise rotation angle of a video. Possible values:
|
adaptation |
No |
String |
Adaptive resolution. Possible values:
|
upsample |
No |
Integer |
Whether to enable upsampling, for example, converting a 480p video to a 720p one. Possible values:
|
hls_segment_type |
No |
String |
HLS slice type.
The default value is ts. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
volume |
No |
String |
Adjusts volume. The options are as follows:
|
volume_expr |
No |
Integer |
Volume adjustment amplitude. This parameter is used only when volume is set to dynamic. The value ranges from –15 to 15. Unit: dB |
Response Parameters
Status code: 202
Parameter |
Type |
Description |
---|---|---|
task_id |
Integer |
Task ID. If the returned status code is 200 OK, the value is the task ID generated after the task is accepted. |
Status code: 403
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code |
error_msg |
String |
Error description |
Example Requests
Creates a video transcoding task.
POST https://{endpoint}/v1/{project_id}/transcodings { "input" : { "bucket" : "example-bucket", "location" : "region01", "object" : "example-path/input.mp4" }, "output" : { "bucket" : "example-bucket", "location" : "region01", "object" : "example-path/output" }, "trans_template_id" : [ 1002, 1003, 1004, 1005 ], "priority" : "9", "subtitle" : { "subtitle_type" : 1, "input" : { "bucket" : "example-bucket", "location" : "region01", "object" : "example-subtitle.srt" } }, "encryption" : { "hls_encrypt" : { "iv" : "******", "key" : "******", "url" : "http://{your-keyserver}", "algorithm" : "AES-128-CBC" } }, "thumbnail" : { "out" : { "bucket" : "example-bucket", "location" : "region01", "object" : "example/path" }, "tar" : 1, "params" : { "time" : 2, "format" : 1, "max_length" : 480 } } }
Example Responses
Status code: 202
Transcoding task created successfully.
{ "task_id" : 100211 }
Status code: 403
Failed to create a transcoding task.
{ "error_code" : "MPC.10202", "error_msg" : "Invalid request parameter" }
Status Codes
Status Code |
Description |
---|---|
202 |
Transcoding task created successfully. |
403 |
Failed to create a transcoding task. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot