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

更新时间：2024-11-12 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时，该参数必选。
additional_manifests	否	Array of AdditionalManifests objects	主索引定制参数。
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
crf	否	Object	视频恒定码率控制因子。取值范围为[0, 51]
max_bitrate	否	Integer	输出最大码率单位：kbit/s 带crf时使用，参考原片的平均码率进行设置（一般为1.5倍）
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分钟）
stream_name	否	String	流名称

表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 AdditionalManifests
参数	是否必选	参数类型	描述
manifest_name_modifier	否	String	定制的索引后缀名
selected_outputs	否	Array of strings	选择的流名称

表9 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”，则此配置项不能为空。

**表10** 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 ：水印叠加在转码输出文件上。

**表11** 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

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

**表13** 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都未选择，则按源片源宽高输出截图

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

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

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

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

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

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

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

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

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

**表23** 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数据获取文件元数据信息在截图场景无效在转动图场景无效输出文件为HLS格式时，文件名称不能命名为index，示例：index.m3u8，否则会导致播放失败。

**表24** 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切片。

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

响应参数

状态码： 202

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

状态码： 403

**表27** 响应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

直接提交取消