文档首页> 媒体处理 MPC> API参考> 媒资转码接口> 新建转码任务

更新时间：2024-03-25 GMT+08:00

在线调试

CLI示例

查看PDF

新建转码任务

功能介绍

新建转码任务可以将视频进行转码，并在转码过程中压制水印、视频截图等。视频转码前需要配置转码模板。待转码的音视频需要存储在与媒体处理服务同区域的OBS桶中，且该OBS桶已授权。

调用方法

请参见如何调用API。

URI

POST /v1/{project_id}/transcodings

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。获取方法请参考获取项目ID

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	否	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
Authorization	否	String	使用AK/SK方式认证时必选，携带的鉴权信息。
X-Project_Id	否	String	使用AK/SK方式认证时必选，携带项目ID信息, 与路径参数中的项目ID相同。
X-Sdk-Date	否	String	使用AK/SK方式认证时必选，请求的发生时间。

表3 请求Body参数
参数	是否必选	参数类型	描述
input	否	ObsObjInfo object	源文件存储地址，非追加音频等场景，该参数必选。
output	是	ObsObjInfo object	输出文件存储地址。
trans_template_id	否	Array of integers	转码模板ID，没带av_parameter参数时，必须带该参数，数组，每一路转码输出对应一个转码配置模板ID，最多支持9个模板ID。多个转码模板中如下参数可变，其他都必须一致：视频bitrate，height，width。
av_parameters	否	Array of AvParameters objects	转码参数。若同时设置“trans_template_id”和此参数，则优先使用此参数进行转码，不带trans_template_id时，该参数必选。
output_filenames	否	Array of strings	输出文件名称，每一路转码输出对应一个名称，需要与转码模板ID数组的顺序对应。若设置该参数，表示输出文件按该参数命名。若不设置该参数，表示输出文件按默认方式命名。
user_data	否	String	用户自定义数据，该字段可在查询接口或消息通知中按原内容透传给用户。
watermarks	否	Array of WatermarkRequest objects	图片水印参数，数组，最多支持10个成员。
thumbnail	否	Thumbnail object	截图信息。说明：仅“trans_template_id”对应的转码模板或“av_parameters”中设置的输出分辨率为1920×1080、1280×720、854×480或480×270时，视频转码才会输出对应的截图文件；否则将不输出截图文件。
priority	否	Integer	任务优先级，取值如下： 9代表高优先级。 6代表中优先级，默认为6。暂时只支持6和9。
subtitle	否	Subtitle object	字幕参数。
encryption	否	Encryption object	视频加密控制参数。
crop	否	Crop object	截取前多少秒做转码。
audio_track	否	AudioTrack object	音轨参数。
multi_audio	否	MultiAudio object	音频多语言多声道参数。
video_process	否	VideoProcess object	视频处理控制参数
audio_process	否	AudioProcess object	音频处理控制参数

表4 AvParameters
参数	是否必选	参数类型	描述
video	否	VideoParameters object	视频参数
audio	否	Audio object	音频参数
common	是	Common object	公共参数

表5 VideoParameters
参数	是否必选	参数类型	描述
output_policy	否	String	输出策略: 当视频参数中的“output_policy”为“discard”，且音频参数中的“output_policy”为“transcode”时，表示只输出音频。当视频参数中的“output_policy”为“transcode”，且音频参数中的“output_policy”为“discard”时，表示只输出视频。当视频参数中的“output_policy”为“copy”，表示直接拷贝原始的视频，不做编解码。当音频参数中的“output_policy”为“copy”，表示直接拷贝原始的音频，不做编解码。同时为“discard”不合法。同时为“transcode”时，表示输出音视频。取值如下： discard transcode copy
codec	否	Integer	视频编码格式。取值如下： 1：VIDEO_CODEC_H264 2：VIDEO_CODEC_H265
bitrate	否	Integer	输出平均码率。取值范围：0或[40,50000]之间的整数。单位：kbit/s 若设置为0，则输出平均码率为自适应值。
profile	否	Integer	编码档次取值如下： 1：VIDEO_PROFILE_H264_BASE 2：VIDEO_PROFILE_H264_MAIN 3：VIDEO_PROFILE_H264_HIGH 4：VIDEO_PROFILE_H265_MAIN
level	否	Integer	编码级别取值如下： 0：AUTO 1：VIDEO_LEVEL_1_0 2：VIDEO_LEVEL_1_1 3：VIDEO_LEVEL_1_2 4：VIDEO_LEVEL_1_3 5：VIDEO_LEVEL_2_0 6：VIDEO_LEVEL_2_1 7：VIDEO_LEVEL_2_2 8：VIDEO_LEVEL_3_0 9：VIDEO_LEVEL_3_1 10：VIDEO_LEVEL_3_2 11：VIDEO_LEVEL_4_0 12：VIDEO_LEVEL_4_1 13：VIDEO_LEVEL_4_2 14：VIDEO_LEVEL_5_0 15：VIDEO_LEVEL_5_1
preset	否	Integer	编码质量等级。取值如下： 1：VIDEO_PRESET_SPEED，编码快速档位 2：VIDEO_PRESET_NORMAL，编码普通档位，不推荐使用2。 3：VIDEO_PRESET_HIGHQUALITY，编码高质量档位默认值1。
max_iframes_interval	否	Integer	I帧最大间隔取值范围：[2，10]。默认值：5。单位：秒。
bframes_count	否	Integer	最大B帧间隔。取值范围： H264：[0，8]，默认值为4。 H265：[0，8]，默认值为7。单位：帧。
frame_rate	否	Integer	帧率。取值范围：0或[5,60]，0表示自适应。单位：帧每秒。说明：若设置的帧率不在取值范围内，则自动调整为0，若设置的帧率高于片源帧率，则自动调整为片源帧率。
width	否	Integer	视频宽度（单位：像素） H264：范围[32,4096]，必须为2的倍数 H265：范围[320,4096]，必须是2的倍数
height	否	Integer	视频高度（单位：像素） H264：范围[32,2880]，必须为2的倍数 H265：范围[240,2880] ，必须是2的倍数
black_cut	否	Integer	黑边剪裁类型 0：不开启黑边剪裁 1：开启黑边剪裁，低复杂度算法，针对长视频（>5分钟） 2：开启黑边剪裁，高复杂度算法，针对短视频（<=5分钟）

表6 Audio
参数	是否必选	参数类型	描述
output_policy	否	String	输出策略: 当视频参数中的“output_policy”为“discard”，且音频参数中的“output_policy”为“transcode”时，表示只输出音频。当视频参数中的“output_policy”为“transcode”，且音频参数中的“output_policy”为“discard”时，表示只输出视频。当视频参数中的“output_policy”为“copy”，表示直接拷贝原始的视频，不做编解码。当音频参数中的“output_policy”为“copy”，表示直接拷贝原始的音频，不做编解码。同时为“discard”不合法。同时为“transcode”时，表示输出音视频。取值如下： discard transcode copy
codec	否	Integer	音频编码格式。取值如下： 1：AAC格式。 2：HEAAC1格式。 3：HEAAC2格式。 4：MP3格式。
sample_rate	否	Integer	音频采样率。取值如下： 1：AUDIO_SAMPLE_AUTO 2：AUDIO_SAMPLE_22050（22050Hz） 3：AUDIO_SAMPLE_32000（32000Hz） 4：AUDIO_SAMPLE_44100（44100Hz） 5：AUDIO_SAMPLE_48000（48000Hz） 6：AUDIO_SAMPLE_96000（96000Hz）说明：当编码格式为MP3时，音频采样率取值不为6
bitrate	否	Integer	音频码率。取值范围：0或[8,1000]。单位：kbit/s。
channels	是	Integer	声道数。取值如下： 1：AUDIO_CHANNELS_1，单声道 2：AUDIO_CHANNELS_2，双声道 6：AUDIO_CHANNELS_5_1，5.1声道当媒体的封装格式是音频格式（MP3）时，声道数不支持设为5.1声道。

表7 Common
参数	是否必选	参数类型	描述
PVC	否	Boolean	是否开启高清低码功能。取值如下： false：关闭。（当前默认关闭） true：开启。 (数字0表示关闭,其余正整数,负数都表示true)
hls_interval	否	Integer	HLS分片间隔，仅封装类型“pack_type”取值为1或3时，该参数生效。取值范围：[2，10]。单位：秒。
dash_interval	否	Integer	DASH间隔，仅封装类型“pack_type”取值为2或3时，该参数生效。取值范围：[2，10]。单位：秒。
pack_type	是	Integer	封装类型。取值如下： 1：HLS 2：DASH 3：HLS+DASH 4：MP4 5：MP3 6：ADTS 说明： pack_type设置为5和6时，不能设置视频参数。

表8 WatermarkRequest
参数	是否必选	参数类型	描述
input	否	ObsObjInfo object	源文件地址，如果是图片水印，则该参数必选。
template_id	否	String	水印模板。可通过新建水印模板接口创建水印模板。
text_context	否	String	文字水印内容，内容需做Base64编码，若类型为文字水印 (type字段为Text)，则此配置项不能为空示例：若想添加文字水印“测试文字水印”，那么Content的值为：5rWL6K+V5paH5a2X5rC05Y2w
image_watermark	否	ImageWatermark object	图片水印参数，用于覆盖图片水印模板中的同名参数。
text_watermark	否	TextWatermark object	文字水印配置，若设置“text_context”，则此配置项不能为空。

表9 ImageWatermark
参数	是否必选	参数类型	描述
dx	否	String	水印图片起点相对输出视频顶点的水平偏移量。设置方法有如下两种：整数型：表示图片起点水平偏移视频顶点的像素值，单位px。取值范围：[0，4096] 小数型：表示图片起点相对于视频分辨率宽的水平偏移比率。取值范围：(0，1)，支持4位小数，如0.9999，超出部分系统自动丢弃。示例：输出视频分辨率宽1920，设置“dx”为“0.1”，“referpos”为“TopRight”（右上角），则水印图片右上角到视频右顶点在水平方向上偏移距离为192。
dy	否	String	水印图片起点相对输出视频顶点的垂直偏移量。设置方法有如下两种：整数型：表示图片起点垂直偏移视频顶点的像素值，单位px。取值范围：[0，4096] 小数型：表示图片起点相对于视频分辨率高的垂直偏移比率。取值范围：(0，1)，支持4位小数，如0.9999，超出部分系统自动丢弃。示例：输出视频分辨率高1080，设置“dy”为“0.1”，“referpos”为“TopRight”（右上角），则水印图片右上角到视频右顶点在垂直方向上的偏移距离为108。
referpos	否	String	水印的位置。取值如下： TopRight：右上角。 TopLeft：左上角。 BottomRight：右下角。 BottomLeft：左下角。
timeline_start	否	String	水印开始时间，与“timeline_duration”配合使用。取值范围：数字。单位：秒。
timeline_duration	否	String	水印持续时间，与“timeline_start”配合使用。取值范围：[数字，ToEND]。“ToEND”表示持续到视频结束。默认值：ToEND。
image_process	否	String	图片水印处理方式，type设置为Image时有效。取值如下： Original：只做简单缩放，不做其他处理。 Grayed：图像灰度化处理。 Transparent：保持原始透明图像的透明化效果。
width	否	String	水印图片宽，值有两种形式：整数型代水印图片宽的像素值，范围[8，4096]，单位px。小数型代表相对输出视频分辨率宽的比率，范围(0,1)，支持4位小数，如0.9999，超出部分系统自动丢弃。
height	否	String	水印图片高，值有两种形式：整数型代表水印图片高的像素值，范围[8，4096]，单位px。小数型代表相对输出视频分辨率高的比率，范围(0，1)，支持4位小数，如0.9999，超出部分系统自动丢弃。
base	否	String	水印叠加母体取值如下： input ：水印叠加在输入片源上，转码输出后实际大小按图像等比例缩放 output ：水印叠加在转码输出文件上。

**表10** TextWatermark
参数	是否必选	参数类型	描述
dx	否	String	水印图片起点相对输出视频顶点的水平偏移量。设置方法有如下两种：整数型：表示图片起点水平偏移视频顶点的像素值，单位px。取值范围：[0，4096] 小数型：表示图片起点相对于视频分辨率宽的水平偏移比率。取值范围：(0，1)，支持4位小数，如0.9999，超出部分系统自动丢弃。示例：输出视频分辨率宽1920，设置“dx”为“0.1”，“referpos”为“TopRight”（右上角），则水印图片右上角到视频右顶点在水平方向上偏移距离为192。
dy	否	String	水印图片起点相对输出视频顶点的垂直偏移量。设置方法有如下两种：整数型：表示图片起点垂直偏移视频顶点的像素值，单位px。取值范围：[0，4096] 小数型：表示图片起点相对于视频分辨率高的垂直偏移比率。取值范围：(0，1)，支持4位小数，如0.9999，超出部分系统自动丢弃。示例：输出视频分辨率高1080，设置“dy”为“0.1”，“referpos”为“TopRight”（右上角），则水印图片右上角到视频右顶点在垂直方向上的偏移距离为108。
referpos	否	String	水印的位置。取值如下： TopRight：右上角。 TopLeft：左上角。 BottomRight：右下角。 BottomLeft：左下角。
timeline_start	否	String	水印开始时间，与“timeline_duration”配合使用。取值范围：数字。单位：秒。
timeline_duration	否	String	水印持续时间，与“timeline_start”配合使用。取值范围：[数字，ToEND]。“ToEND”表示持续到视频结束。默认值：ToEND。
font_name	否	String	字体，当前支持fzyouh
font_size	否	Integer	字体大小。取值范围：[4, 120]
font_color	否	String	字体颜色。目前颜色支持 black，blue，white，green，red，yellow，brown，gold，pink，orange，purple。
base	否	String	水印叠加母体取值如下： input：水印叠加在输入片源上，转码输出后实际大小按图像等比例缩放 output：水印叠加在转码输出文件上。默认值：input

**表11** Thumbnail
参数	是否必选	参数类型	描述
tar	否	Integer	是否压缩抽帧图片生成tar包 0：表示压缩 1：表示不压缩
out	否	ObsObjInfo object	截图输出路径，不填写时与转码输出在一起
params	是	ThumbnailPara object	截图参数。

**表12** ThumbnailPara
参数	是否必选	参数类型	描述
type	否	String	采样类型。取值如下： "TIME"：根据时间间隔采样截图。 "DOTS"：指定时间点截图。选择同步截图时，需指定此类型。 "DOTS_MS": 同步截图指定时间点毫秒值。默认值："TIME"
time	否	Integer	采样截图的时间间隔值。默认值：12。单位：秒
start_time	否	Integer	采样类型为“TIME”模式的开始时间，和“time”配合使用。默认值：0。单位：秒。说明： start_time超过片源时长,不进行抽帧
duration	否	Integer	采样类型为“TIME”模式的持续时间，和“time”、“start_time”配合使用，表示从视频文件的第“start_time”开始，持续时间为“duration”，每间隔“time”生成一张截图。取值范围：[数字，ToEND]。“ToEND”表示持续到视频结束。默认值： ToEND。单位：秒。说明： “duration”必须大于等0，若设置为0，则截图持续时间从“start_time”到视频结束。
dots	否	Array of integers	指定时间截图的时间点数组例如输入[1,3,5]，分别截取视频第1秒、第3秒、第5秒位置的图像帧异步截图：最多支持10个时间点同步截图时：只支持1个时间点
dots_ms	否	Array of integers	同步截图下，指定时间截图的时间点数组，单位毫秒例如输入[1000]，截取视频第1000毫秒位置的图像帧，仅支持一个时间点
output_filename	否	String	截图输出文件名。如果只抽一张图（即：按DOTS方式，指定1个时间点）则按该指定文件名输出图片。如果抽多张图（即：按DOTS方式指定多个时间点或按TIME间隔截图）则输出图片名在该指定文件名基础上在增加时间点（示例：output_filename_10.jpg）。如果指定了压缩抽帧图片生成tar包，则tar包按该指定文件名输出。
format	否	Integer	截图文件格式。取值如下： 1：表示jpg格式 2：表示png格式仅同步截图支持png格式
width	否	Integer	图片宽度取值范围： [96,3840] 0：自适应，保持原有宽高单位：px
height	否	Integer	图片高度取值范围： [96,2160] 0：自适应，保持原有宽高单位：px
max_length	否	Integer	截图最长边的尺寸。宽边尺寸按照该尺寸与原始视频像素等比缩放计算。参考取值范围：[240,3840] 单位：像素说明：该参数和width/height选择使用，以width/height优先，若width/height都不等于0，则图片尺寸按width/height得出；反之，则图片尺寸按max_length 得出;若该参数和width/height都未选择，则按源片源宽高输出截图

**表13** Subtitle
参数	是否必选	参数类型	描述
input	否	ObsObjInfo object	字幕文件地址。
inputs	否	Array of MulInputFileInfo objects	多字幕文件地址。
subtitle_type	否	Integer	字幕类型。取值如下： 0，表示不输出字幕 1，表示外部字幕文件嵌入视频流 2，表示输出WebVTT格式字幕

**表14** MulInputFileInfo
参数	是否必选	参数类型	描述
language	否	String	字幕语言标签。建议采用ISO 639-2编码。
input	否	ObsObjInfo object	输入字幕文件地址。

**表15** Encryption
参数	是否必选	参数类型	描述
hls_encrypt	否	HlsEncrypt object	视频加密控制参数。

**表16** HlsEncrypt
参数	是否必选	参数类型	描述
key	是	String	使用base64编码的内容加密密钥
url	是	String	密钥获取服务的地址，用于播放hls分片时解密使用。
iv	否	String	初始向量，base64binary，随机数
algorithm	否	String	加密算法。 AES-128-CTR AES-128-CBC 默认值：AES-128-CTR

**表17** Crop
参数	是否必选	参数类型	描述
duration	否	Integer	截取的视频时长。单位：秒从0秒开始算起

**表18** AudioTrack
参数	是否必选	参数类型	描述
type	否	Integer	音轨选取方式。 0：默认选取 1：手动选择
left	否	Integer	选取左声道所在的音轨编号。
right	否	Integer	选取右声道所在的音轨编号。

**表19** MultiAudio
参数	是否必选	参数类型	描述
tracks_info	否	Array of TracksInfo objects	音轨信息
audio_files	否	Array of AudioFile objects	音频文件
default_language	否	String	默认语言标签。建议采用ISO 639-2编码。

**表20** AudioFile
参数	是否必选	参数类型	描述
tracks_info	否	Array of TracksInfo objects	音轨信息
input	否	ObsObjInfo object	输入存储位置

**表21** TracksInfo
参数	是否必选	参数类型	描述
channel_layout	否	String	音频轨的声道layout
language	否	String	音频语言标签。建议采用ISO 639-2编码。

**表22** ObsObjInfo
参数	是否必选	参数类型	描述
bucket	是	String	OBS的bucket名称。
location	是	String	OBS桶所在的区域，且必须与使用的MPC区域保持一致。
object	是	String	OBS对象路径，遵守OSS Object定义。当用于指示input时，需要指定到具体对象。当用于指示output时，只需指定到转码结果期望存放的路径。在字幕场景下，字幕文件名称中禁止携带特殊符号，否则会导致转码任务失败，如：[ 正确示例: demo.srt 错误示例: [demo.srt
file_name	否	String	文件名当指定了此参数时，输出的对象名为object/file_name。当不指定此参数时，输出的对象名为object/xxx，其中xxx由MPC指定。在作为输出文件名时：在转封装场景有效，需要指定输出文件名称在转码场景下，如果需要指定输出的文件名称，请使用output_filenames参数在解析场景有效，解析场景如果指定文件名，则将解析参数写入指定文件名，通过查询接口响应json数据获取文件元数据信息在截图场景无效在转动图场景无效

**表23** VideoProcess
参数	是否必选	参数类型	描述
hls_init_count	否	Integer	需要单独设置时长的HLS起始分片数量。取值范围：[0,10]，默认值为：0 说明：与hls_init_interval配合使用，设置前面hls_init_count个HLS分片时长。为0表示不单独配置时长。
hls_init_interval	否	Integer	表示前面hls_init_count个HLS分片的时长。取值范围：[2,10] ，默认值为：5 说明： hls_init_count不为0时，该字段才起作用。
hls_storage_type	否	String	hls的音视频流存储方式。 composite：存储在同一个文件中。 separate：存储在不同的文件中
rotate	否	Integer	视频顺时针旋转角度。 0：表示不旋转 1：表示顺时针旋转90度 2：表示顺时针旋转180度 3：表示顺时针旋转270度
adaptation	否	String	长短边自适应控制字段： SHORT：表示短边自适应 LONG：表示长边自适应 NONE：表示不自适应
upsample	否	Integer	是否开启上采样，如支持从480P的片源转为720P，可取值为: 0：表示上采样关闭， 1：表示上采样开启.
hls_segment_type	否	String	HLS切片类型。取值如下所示： mpegts：ts切片 fmp4：fmp4切片不设置默认为ts切片。

**表24** AudioProcess
参数	是否必选	参数类型	描述
volume	否	String	音量调整方式： auto：表示自动调整音量。 dynamic：表示人为调整，需设定音量调整幅值。 original：表示不调整音量。
volume_expr	否	Integer	音量调整幅值，需指定volume为dynamic。取值范围：[-15,15] 单位：dB

响应参数

状态码： 202

**表25** 响应Body参数
参数	参数类型	描述
task_id	Integer	接受任务后，产生的任务ID。

状态码： 403

**表26** 响应Body参数
参数	参数类型	描述
error_code	String	错误码。
error_msg	String	错误描述。

请求示例

新建转码任务，可以将视频进行转码。

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
    }
  }
}

响应示例

状态码： 202

新建转码任务提交成功。

{
  "task_id" : 100211
}

状态码： 403

新建转码任务提交失败。

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

状态码

状态码	描述
202	新建转码任务提交成功。
403	新建转码任务提交失败。

错误码

请参见错误码。

父主题：媒资转码接口

上一篇：媒资转码接口

下一篇：取消转码任务

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消