视频云剪辑

更新时间：2024-11-08

创建视频云剪辑任务

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

请求语法

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

请求体参数

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

Timeline

字段	类型	必要性	轨道数范围	素材结点总数范围	说明
audioTracks	AudioTrack[]		[0,10]	[0,1000]	音频多轨道
videoTracks	VideoTrack[]	是	[1,10]	[1,1000]	视频多轨道（包括视频、图片）
subtitleTracks	SubtitleTrack[]		[0,10]	[0,1000]	字幕多轨道

Output

字段	类型	必要性	默认值	说明
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 帧最大间隔

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

AudioTrack

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

VideoTrack

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

SubtitleTrack

字段	类型	必要性	说明
subtitleItems	SubtitleItem[]	是	素材结点列表

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个。

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}表示对输入画面进行裁剪之后所保留的区域，裁剪区域不能超出输入画面范围。

SubtitleItem

字段	类型	必要性	默认值	说明
showStart	float	是		在作品中的播放起点，单位秒
showDuration	float	是		在作品中的播放时长，单位秒。必须大于0
xpos	float		0.5	放置到作品中的水平横坐标
ypos	float		0.9	放置到作品中的竖直纵坐标。xpos, ypos 是字幕锚点的坐标
text	string	是		文本内容。仅支持可见文字及其标点符号（不支持 emoji 表情、特殊字符等），如需换行请使用 Unix 换行符 \n。不能超过 600 个 UTF-8 字符数。注意字数过多或字体过大可能会导致文字超出屏幕而不可见。
textAlign	string(枚举)		center	文本对齐方式，即字幕锚点，取值：`left`, `center`, `right`, `bottomLeft`, `bottomCenter`, `bottomRight`, `topLeft`, `topCenter`, `topRight`
fontFamily	string(枚举)		方正黑体简体	字体名称。取值：`方正黑体简体`, `楷体`, `思源宋体 CN`, `Noto Sans SC Black`, `Noto Sans SC SemiBold`, `Noto Sans SC Medium`, `Noto Sans SC Thin`；全部字体名称列表及示例请参考文末附录
fontSize	int		40	字体大小，即字体高度的像素点数。无大小限制，注意过大会超出屏幕范围，过小会难以看到。
fontSpacing	int		0	字间距，单位为像素。无大小限制，注意过大会超出屏幕范围，过小会难以看到。
fontBold	bool		false	字体是否加粗
fontItalic	bool		false	斜体
fontUnderline	bool		false	下划线
fontStrikeOut	bool		false	删除线
fontColor	string		#FFFFFF	文字颜色，默认白色。取值范围[#000000, #FFFFFF]（十六进制）
fontAlpha	float		0	文字透明度，取值[0.0,1.0]，默认不透明
fontOutlineColor	string		#000000	字体描边颜色，默认黑色。取值范围[#000000, #FFFFFF]（十六进制）
fontOutlineAlpha	float		0	字体描边透明度，取值范围[0.9,1.0]，默认不透明
fontOutlineWidth	int		2	每个字的描边厚度，单位为像素。取值最小为 0，注意值过大会导致文字难以观看。

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内若共存以下多个字段，将按该参数表中的顺序执行。

响应参数

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

请求示例

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

{
  "timeline": {
    "videoTracks": [
      {
        "videoItems": [
          {
            "sourceUrl:": "https://example.com/background.jpg",
            "type": "image",
            "showStart": 0,
            "showDuration": 10
          }
        ]
      },
      {
        "videoItems": [
          {
            "mediaId:": "mda-jlsjdljrwsdfsdfe",
            "type": "video",
            "start": 3.5,
            "duration": 4,
            "showStart": 0,
            "showDuration": 4.5,
            "durationPaddingType": "last_frame",
            "audioOperations": [
              {
                "volume": 1.5
              }
            ],
            "imageOperations": [
              {
                "speed": 1.2,
                "crop": {
                  "xpos": 0.6,
                  "ypos": 0.6,
                  "width": 0.4,
                  "height": 0.4
                }
              }
            ],
            "xpos": 0.0,
            "ypos": 0.0,
            "width": 1.0,
            "height": 1.0
          },
          {
            "sourceUrl:": "https://example.com/video2.mp4",
            "type": "video",
            "start": 0.5,
            "duration": 5.5,
            "showStart": 4.5,
            "showDuration": 5.5,
            "imageOperations": [
              {
                "posMovement": {
                  "viewBox": "fixed",
                  "type": "zoomIn",
                  "speed": 0.001
                }
              }
            ]
          }
        ]
      }
    ],
    "audioTracks": [
      {
        "audioItems": [
          {
            "sourceUrl:": "https://example.com/audio1.mp3",
            "start": 0.5,
            "duration": 5.5,
            "showStart": 0.0,
            "showDuration": 10,
            "durationPaddingType": "loop",
            "imageOperations": [
              {
                "speed": 0.5
              }
            ]
          }
        ]
      }
    ]
  },
  "output": {
    "fileName": "my_first_video.mp4",
    "compression": "low"
  }
}

响应示例

{
  "taskId": "tsk-jiowe4f89j394f93"
}

任务状态回调通知

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

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

回调消息体参数

字段名	类型	说明
eventId	string	通知事件的唯一id
eventType	string(枚举)	通知事件的类型，取值：`COMPOSE_TASK_STATUS_CHANGE`
eventTime	string	通知事件的发生时间，例如2024-10-11T13:48:01Z
composeTaskStatusChangeEvent	object	视频合成任务状态变更事件
[+] taskId	string	任务id
[+] createTime	string	任务创建时间，例如2024-10-11T13:48:01Z
[+] finishTime	string	任务完成时间，例如2024-10-11T13:49:59Z
[+] status	string(枚举)	任务进度，取值：`READY`(排队中), `RUNNING`, `SUCCESS`, `FAILED`
[+] composeTaskInfo	object	视频合成任务状态
[+][+] errMsg	string	如果任务失败，这里给出错误原因
[+][+] output	object
[+][+][+] mediaId	string	当前作品的媒资id
[+][+][+] url	string	视频预览链接

回调消息体示例

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

查询视频云剪辑任务

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

请求语法

GET /v2/tasks/{taskId} HTTP/1.1
host: vod.bj.baidubce.com
authorization: <bce-authorization-string>
x-bce-date: <bce-authorization-utc-date>
content-type: application/json

请求路径参数

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

响应参数

字段名	类型	说明
taskId	string	任务id
createTime	string	任务创建时间，例如2024-10-11T13:48:01Z
finishTime	string	任务完成时间，例如2024-10-11T13:49:59Z
status	string(枚举)	任务进度，取值：`READY`(排队中), `RUNNING`, `SUCCESS`, `FAILED`
composeTaskInfo	object	视频合成任务状态
[+] errMsg	string	如果任务失败，这里给出错误原因
[+] output	object
[+][+] mediaId	string	当前作品的媒资id
[+][+] url	string	视频预览链接

请求示例

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

响应示例

示例1:

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

示例2:

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