视频云剪辑

更新时间：2026-01-27

视频云剪辑（视频渲染合成）提供专业的在线视频剪辑服务，支持视频裁剪、拼接、转码、字幕、音频、特效等操作，生产出新的视频。文本介绍如何通过API使用视频云剪辑服务。

操作支持	描述
多轨道	支持视频剪辑所必需的多个图层叠加，音频混合
剪辑操作	裁剪：支持对视频片段、音频片段进行裁剪，提取所需部分；拼接：支持将多个视频片段、音频、图片等素材拼接成一个完整的视频旋转：支持将素材旋转任意角度变速：支持对素材进行加速或减速缩放：支持将素材放大或缩小循环播放、静帧播放
字幕	支持为视频添加文字字幕
音频	支持调整视频的音频音量、添加背景音乐等
转码	将视频转换成不同的格式或分辨率
添加特效	为视频添加运镜特效、滤镜、动画等效果

1. 创建视频云剪辑任务

调用该接口可以创建一个视频云剪辑异步任务。发起请求后，任务将被创建并加入到当前用户的任务队列。用户可以在「任务中心」查询到该任务的状态。如果用户在VOD创建了回调通知事件，则任务被开始处理、处理完成、处理失败时都将自动向用户发送通知。若通知失败会连续尝试3次，均失败后则放弃通知。

请求结构

Http

1POST /v2/media_compose HTTP/1.1
2host: vod.bj.baidubce.com
3authorization: <bce-authorization-string>
4x-bce-date: <bce-authorization-utc-date>
5content-type: application/json

请求参数

字段	类型	必要性	说明
timeline	ComposeTimeline	是	剪辑时间轴
output	ComposeOutput	是	导出配置

ComposeOutput

字段	类型	必要性	默认值	说明
fileName	string	是		导出视频保存到媒资库的文件名
videoCodec	string（枚举）		h264	导出视频编码，取值：h264, h265
audioCodec	string（枚举）		aac	导出音频编码，取值：aac, mp3
width	int		1920	导出分辨率宽度
height	int		1080	导出分辨率高度
frameRate	float		30	导出帧率
audioSampleRateInHz	int		44100	导出音频采样率。各编码支持的采样率： mp3: 44100, 48000, 32000, 22050, 24000, 16000, 11025, 12000, 8000. aac: 96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350.
audioChannels	int		2	导出音频声道数，取值范围 [1,7]
compressionType	string（枚举）		mid	导出视频压缩质量，取值：high（高）, mid（中）, low（低）
gop	int		125	导出视频 i 帧最大间隔

注意：导出配置将影响任务处理耗时，例如较高的分辨率、帧率、质量等都将增加任务耗时，请合理配置。

ComposeTimeline

字段	类型	必要性	轨道数范围	素材总数范围	说明
audioTracks	AudioTrack[]		[0,10]	[0,1000]	音频轨道列表
videoTracks	VideoTrack[]	是	[1,10]	[1,1000]	视频轨道列表（包括视频、图片）
textTracks	TextTrack[]		[0,10]	[0,1000]	文本轨道列表

AudioTrack

字段	类型	必要性	说明
items	AudioItem[]	是	素材列表（音频文件）

VideoTrack

字段	类型	必要性	说明
items	VideoItem[]	是	素材列表（视频文件或图片）

TextTrack

字段	类型	必要性	说明
items	TextItem[]	是	文本列表

AudioItem

字段	类型	必要性	默认值	说明
mediaId	string	与 sourceUrl 二选一		媒资库的媒资 id
sourceUrl	string			文件链接。当 `mediaId` 为空时必须提供 `sourceUrl`，发起任务后将自动保存到 VOD 媒资库
start	float	是		视频片段取自素材文件的起始时间，单位为秒，支持 3 位小数，默认为 0。
duration	float	是		视频片段时长，单位为秒。必须大于 0
showStart	float	是		截取片段在作品中的播放起点，单位秒
showDuration	float	是		截取片段在作品中的播放时长，单位秒。必须大于 0
durationPaddingType	string（枚举）		loop	当 `duration < showDuration` 时，不足部分的填充方式。 `loop`：循环播放截取的片段 `last_frame`：静止播放截取片段的最后一帧
audioOperations	AudioOperation[]			对截取的音频片段进行的操作，如音量调节等。列表元素最多 1 个。

注意事项

优先使用mediaId而不是sourceUrl，因为提供sourceUrl会在处理之前先将其存储到媒资库，有一定的时间消耗。

VideoItem

字段	类型	必要性	默认值	说明
mediaId	string	与 sourceUrl 二选一		媒资库的媒资 id
sourceUrl	string			文件链接。当 `mediaId` 为空时必须提供 `sourceUrl`，发起任务后将自动保存到 VOD 媒资库
type	string（枚举）	是	video	素材类型，取值：`video`, `image`, `mosaic`。注意 gif 动图请填 `video` 类型。
start	float	type=video 时必需	0	视频片段取自素材文件的起始时间，单位为秒
duration	float	type=video 时必需		视频片段时长，单位为秒。必须大于 0
showStart	float	是	0	截取片段在作品中的播放起点，单位秒
showDuration	float	是		截取片段在作品中的播放时长，单位秒。必须大于 0
durationPaddingType	string（枚举）		loop	当 `duration < showDuration` 时，不足部分的填充方式。 `loop`：循环播放截取的片段 `last_frame`：静止播放截取片段的最后一帧
audioOperations	AudioOperation[]			对输入音频的操作。列表元素最多 1 个。
imageOperations	ImageOperation[]			对输入图像的操作（包括视频、图片、马赛克）。列表元素最多 5 个，且裁剪/旋转/镜像三种不允许放在同一个元素内。
position	string（枚举）		custom	处理后的画面放置到作品中的位置，取值： `custom`自定义`xpos`,`ypos`,`width`,`height`; `fill`保持宽高比不变，缩放至填充满整个屏幕，并居中，多余部分裁剪掉； `fit`保持宽高比不变，完整显示整个图像，缩放至最大并居中，可能会留下黑边； `stretch`自动拉伸宽高与屏幕重合，注意图像可能会变形； `center`保持原图像尺寸不变，居中
xpos	float		0.0	素材放置到作品中的水平横坐标，允许超出屏幕范围，超出部分在屏幕外自然不可见
ypos	float		0.0	素材放置到作品中的竖直纵坐标
width	float		1.0	素材放置到作品中的宽度，取值大于 0。允许超出屏幕范围
height	float		1.0	素材放置到作品中的高度，取值大于 0。允许超出屏幕范围

温馨提示

VideoItem.{xpos,ypos,width,height}表示素材经过imageOperations 一系列操作之后得到的结果放置到作品中的位置，允许超出作品画面范围，超出部分在屏幕外自然不可见。

ImageOperation.crop.{xpos,ypos,width,height}表示对输入画面进行裁剪之后所保留的区域，裁剪区域不能超出输入画面范围。

AudioOperation

字段	类型	必要性	默认值	说明
volume	float		1.0	音量调节倍数，0 表示静音，取值范围 [0, 16]
speed	float		1.0	播放倍速，取值范围 [0.01, 16]

ImageOperation

字段	类型	默认值	说明
speed	float	1.0	播放倍速，精确到小数点后 2 位，取值范围为 [0.01,16]
crop	object		裁剪区域
[+] xpos	float	0	裁剪区域的左上角横坐标比例，取值范围为 [0.0~1.0]
[+] ypos	float	0	裁剪区域的左上角纵坐标比例，取值范围为 [0.0~1.0]
[+] width	float	1	裁剪区域的宽度比例，取值范围为 [0.0~1.0]。要求 `xpos + width <= 1.0`
[+] height	float	1	裁剪区域的高度比例，取值范围为 [0.0~1.0]。要求 `ypos + height <= 1.0`
rotate	int	0	顺时针旋转角度，取值 [0,359]
mirror	string（枚举）		镜像效果，取值：`hori`（左右镜像），`vert`（上下镜像），`full`（旋转 180 度）
posMovement	object		运动效果
[+] viewBox	string（枚举）	fixed	画布上用于展示运动效果的区域。取值： `fixed`：素材运动效果的展示区域固定在 `VideoItem.{xpos, ypos, width, height}`（默认全屏），输入视频会提前放大到适当比例再运动，保证运动过程中视频边缘不进入该区域。
[+] type	string（枚举）		运动方式。取值：`left` （向左）, `right` （向右）, `up` （向上）, `down` （向下）, `leftUp` （向左上）, `leftDown` （向左下）, `rightUp` （向右上）, `rightDown` （向右下）, `zoomIn` （放大）, `zoomOut` （缩小）
[+] speed	float	0	运动速度，单位“比例/秒”（每秒相对于输入画面的变化比例）。例如 `speed=0.1`，则 `x` 方向每秒可变化 `0.1VideoItem.width`，`y` 方向每秒可变化 `0.1VideoItem.height`。

注意事项

由于裁剪、旋转、镜像等操作的顺序不同则效果不同，请放置到列表VideoItem.imageOperations不同元素内以确保执行顺序；

在同一个 ImageOperation 内若共存以下多个字段，将按该参数表中的顺序执行。

TextItem

字段名	类型	必填	默认值	详细说明
text	string	是		文本内容
showStart	float		0	在输出视频中播放的起始时间，单位秒
showDuration	float	是		在输出视频中播放的持续时长，单位秒
anchor	string		topLeft	字幕区域的定位锚点，即xpos,ypos的定位点，取值有 topLeft:左上角 bottomLeft:左下角
xpos	float		0	字幕区域的定位锚点在屏幕上的横坐标，值为0代表屏幕左边界，值为1代表屏幕右边界，可超出
ypos	float		0	字幕区域的定位锚点在屏幕上的纵坐标，值为0代表屏幕上边界，值为1代表屏幕下边界，可超出
width	float	是		字幕区域的宽度，值为输出视频宽度的倍数。例如1代表与屏幕等宽
height	float			字幕区域的高度，值为输出视频高度的倍数。一般不需要填，系统会自动排版文字（达到width宽度时自动换行），即字数越多，行数越多，高度越大
padding	int		0	字幕区域的内边缘留空宽度，单位为像素值
color	string		#00000000	字幕区域的背景颜色，默认完全透明
font	object			字体具体信息
[+] family	string		Hei	字体名称，取值有 `Hei`:思源黑体 `Song`:思源宋体 `Kai`:楷体（仅中文。其它语言自动以黑体显示）
[+] alignment	string		center	文本对齐方式，取值有 `left`:左对齐 `center`:居中对齐 `right`:右对齐
[+] size	int			字号，单位为像素。不填则默认与OCR检测到的原字幕同等字号
[+] spacing	int		0	字间距，单位为像素，默认0
[+] lineSpacing	float		0	行间距，取值为字号的倍数。例如 0.2 表示两行之间的距离是`size*0.2`，即1.2倍行高
[+] bold	boolean		false	是否加粗
[+] italic	boolean		false	是否斜体
[+] underline	boolean		false	是否下划线
[+] strikeOut	boolean		false	是否删除线
[+] color	string		#FFFFFFFF	字体颜色，默认白色不透明
[+] outlineThickness	int		1	字体描边宽度，单位是像素值
[+] outlineColor	string		#000000FF	字体描边颜色，默认黑色不透明
layout	object			布局设置
[+] avoidOverlap	boolean		false	开启后，若与已出现的字幕发生重叠，则自动移动到附近区域避开重叠
[+] fitWidth	boolean		false	开启后，当文本不足一行时，字幕区域宽度自动收缩到与文字一致。收缩方向与alignment对齐方式一致，例如右对齐则右边界不动，左边界向右收缩
[+] fitFontSize	boolean		false	开启后，当字数过多时将适当缩小字号以显示为更少的行数。策略： ①尝试缩小至75%以上显示在1行； ②否则尝试缩小至50%以上显示在2行； ③否则无限制缩小显示在3行以内

注意：上述设置颜色的字段必须是#RRGGBB或#RRGGBBAA格式，其中AA是透明通道，不填则默认为FF不透明。示例: #FFFFFF88 表示半透明白色，#000000FF表示黑色不透明。

响应参数

字段	类型	说明
taskId	string	任务ID ，可作为当前任务的唯一标识

请求示例

Http

1POST /v2/media_compose HTTP/1.1
2host: vod.bj.baidubce.com
3authorization: <bce-authorization-string>
4x-bce-date: <bce-authorization-utc-date>
5content-type: application/json
6
7{
8    "timeline": {
9        "videoTracks": [
10            {
11                "items": [
12                    {
13                        "sourceUrl": "https://example.com/background.jpg",
14                        "type": "image",
15                        "showStart": 0,
16                        "showDuration": 10
17                    }
18                ]
19            },
20            {
21                "items": [
22                    {
23                        "mediaId": "mda-jlsjdljrwsdfsdfe",
24                        "type": "video",
25                        "start": 3.5,
26                        "duration": 4,
27                        "showStart": 0,
28                        "showDuration": 4.5,
29                        "durationPaddingType": "last_frame",
30                        "audioOperations": [
31                            {
32                                "volume": 1.5
33                            }
34                        ],
35                        "imageOperations": [
36                            {
37                                "speed": 1.2,
38                                "crop": {
39                                    "xpos": 0.6,
40                                    "ypos": 0.6,
41                                    "width": 0.4,
42                                    "height": 0.4
43                                }
44                            }
45                        ],
46                        "xpos": 0.0,
47                        "ypos": 0.0,
48                        "width": 1.0,
49                        "height": 1.0
50                    },
51                    {
52                        "sourceUrl": "https://example.com/video2.mp4",
53                        "type": "video",
54                        "start": 0.5,
55                        "duration": 5.5,
56                        "showStart": 4.5,
57                        "showDuration": 5.5,
58                        "imageOperations": [
59                            {
60                                "posMovement": {
61                                    "viewBox": "fixed",
62                                    "type": "zoomIn",
63                                    "speed": 0.001
64                                }
65                            }
66                        ]
67                    }
68                ]
69            }
70        ],
71        "audioTracks": [
72            {
73                "items": [
74                    {
75                        "sourceUrl": "https://example.com/audio1.mp3",
76                        "start": 0.5,
77                        "duration": 5.5,
78                        "showStart": 0.0,
79                        "showDuration": 10,
80                        "durationPaddingType": "loop",
81                        "imageOperations": [
82                            {
83                                "speed": 0.5
84                            }
85                        ]
86                    }
87                ]
88            }
89        ],
90        "textTracks": [
91            {
92                "items" [
93                    {
94                        "text": "你好，这是一条文本字幕",
95                        "showStart": 0,
96                        "showDuration": 10,
97                        "xpos": 0.2,
98                        "ypos": 0.8,
99                        "width": 0.6,
100                        "font": {
101                            "family": "Hei",
102                            "size": 50
103                        },
104                        "layout":{
105                            "avoidOverlap": true
106                        }
107                    }
108                ]
109            }
110        ]
111    },
112    "output": {
113        "fileName": "my_first_video.mp4",
114        "compression": "low",
115        "width": 1280,
116        "height": 720
117    }
118}

响应示例

                JSON
                
                {
    "taskId": "tsk-jiowe4f89j394f93"
}

2. 任务状态回调通知事件

当任务状态发生变更时，VOD支持向用户设定的通知服务地址以POST请求方式发送通知消息。

请注意，通知只在短时间内最多尝试3次，若均未成功响应，则放弃通知。因此，为保证用户不丢失任务状态，建议用户端增加主动轮询机制。

回调消息体参数

字段名	类型	说明
eventId	string	通知事件的唯一id
eventType	string(枚举)	通知事件的类型，取值：`COMPOSE_TASK_STATUS_CHANGE`
eventTime	string	通知事件的发生时间，例如2024-10-11T13:48:01Z
composeTaskStatusChangeEvent	ComposeTaskStatusChangeEvent	视频合成任务状态变更事件

回调消息体示例

                JSON
                
            

                {
    "eventId": "evt-ekaqzhzm3nzts0ws",
    "eventTime": "2024-11-01T06:50:07Z",
    "eventType": "COMPOSE_TASK_STATUS_CHANGE",
    "composeTaskStatusChangeEvent": {
        "taskId": "tsk-ekaqbp3ghsk2syyz",
        "status": "SUCCESS",
        "createTime": "2024-11-01T06:49:06Z",
        "finishTime": "2024-11-01T06:50:07Z",
        "composeTaskInfo": {
            "errMsg": "OK",
            "output": {
                "mediaId": "mda-ekaqqmfj2a2f1fqf",
                "url": "https://sefsgrvsdegvde.exp.bcevod.com/mda-ekaqqmfj2a2f1fqf/_src/mda-ekaqqmfj2a2f1fqf.mp4"
            }
        }
    }
}
            

3. 查询视频云剪辑任务

调用该接口可以查询一个视频云剪辑异步任务的状态和结果。

请求结构

Http

1GET /v2/tasks/{taskId} HTTP/1.1
2host: vod.bj.baidubce.com
3authorization: <bce-authorization-string>
4x-bce-date: <bce-authorization-utc-date>

请求路径参数

字段名	类型	说明
taskId	string	任务ID，任务创建时返回的唯一标识

响应参数

字段名	类型	说明
taskId	string	任务id
type	string	任务类型，值为`COMPOSE`
status	string(枚举)	任务进度，取值：`READY`(排队中), `RUNNING`, `SUCCESS`, `FAILED`
createTime	string	任务创建时间，例如2024-10-11T13:48:01Z
finishTime	string	任务完成时间，例如2024-10-11T13:49:59Z
composeTaskInfo	ComposeTaskInfo	视频云剪辑任务信息

请求示例

Http

1GET /v2/tasks/tsk-jiowe4f89j394f93 HTTP/1.1
2host: vod.bj.baidubce.com
3authorization: <bce-authorization-string>
4x-bce-date: <bce-authorization-utc-date>

响应示例

示例1:

                JSON
                
            

                {
    "taskId": "tsk-ekapq4e0fdd6v0x1",
    "type": "COMPOSE",
    "status": "RUNNING",
    "createTime": "2024-11-01T05:18:28Z"
}
            

示例2:

                JSON
                
            

                {
    "taskId": "tsk-ekaqbp3ghsk2syyz",
    "type": "COMPOSE",
    "status": "SUCCESS",
    "createTime": "2024-11-01T06:49:06Z",
    "finishTime": "2024-11-01T06:50:07Z",
    "composeTaskInfo": {
        "output": {
            "mediaId": "mda-svfsjdssfgdsgds",
            "url": "https://jwoiejfiow.exp.bcevod.com/mda-svfsjdssfgdsgds/_src/mda-svfsjdssfgdsgds.mp4"
        }
    }
}
            