add_video

POST /add_video

接口说明

向草稿添加一个视频片段，并设置裁剪区间、时间轴位置、音量、速度、画面变换和转场。服务端只保存远程视频 URL，不下载视频文件；需要准确时长时先调用 get_duration。如果要单独添加蒙版，优先使用 add_masks。

请求参数

参数	必填	默认值	说明
draft_folder	否	—	草稿输出目录；本地部署时可指定剪映草稿根目录
video_url	是	—	远程视频 URL；服务端只保存 URL，不下载视频
start	否	0	源素材开始时间，单位秒
end	否	0	源素材结束时间，单位秒
width	否	1080	画布或素材宽度
height	否	1920	画布或素材高度
draft_id	否	—	草稿 ID；省略时创建新草稿
transform_y	否	0	Y 轴位置偏移
scale_x	否	1	X 轴缩放比例
scale_y	否	1	Y 轴缩放比例
transform_x	否	0	X 轴位置偏移
speed	否	1.0	播放速度，1.0 为原速
target_start	否	0	放到时间轴上的开始时间，单位秒
track_name	否	'video_main'	目标轨道名称
relative_index	否	0	轨道叠加顺序
duration	否	—	素材总时长，单位秒；建议先用 get_duration 获取
transition	否	—	转场名称；先查询 get_transition_types
transition_duration	否	0.5	转场时长，单位秒
volume	否	1.0	音量，1.0 为原始音量
mask_type	否	—	蒙版名称；先查询 get_mask_types
mask_center_x	否	0.5	蒙版中心 X 坐标
mask_center_y	否	0.5	蒙版中心 Y 坐标
mask_size	否	1.0	蒙版大小
mask_rotation	否	0.0	蒙版旋转角度
mask_feather	否	0.0	蒙版羽化程度
mask_invert	否	False	是否反转蒙版
mask_rect_width	否	—	矩形蒙版宽度
mask_round_corner	否	—	矩形蒙版圆角，范围 0-100
background_blur	否	—	背景模糊级别，可选 1-4

调用示例

curl -X POST https://your-domain.example/api/add_video \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VECTCUT_API_KEY" \
  -d '{
    "draft_id": "dfd_cat_demo_001",
    "video_url": "https://example.com/clip.mp4",
    "start": 0,
    "end": 12.345,
    "target_start": 0,
    "duration": 12.345,
    "transition": "_3D空间",
    "transition_duration": 0.5,
    "mask_type": "线性",
    "mask_center_x": 0.5,
    "mask_center_y": 0.5,
    "mask_size": 1.0,
    "mask_feather": 0,
    "volume": 1.0
  }'

返回格式

{
  "success": true,
  "output": {
    "draft_id": "dfd_cat_demo_001",
    "draft_url": "https://your-domain.example/api/draft/downloader?draft_id=dfd_cat_demo_001"
  },
  "error": ""
}