【剪映API】批量向现有草稿中添加视频素材

ADD_VIDEOS API 接口文档

接口信息

POST /openapi/capcut-mate/v1/add_videos

功能描述

批量向现有草稿中添加视频素材。该接口是一个功能强大的视频添加工具，支持多个视频的批量处理，包括时间范围控制、透明度调整、遮罩效果、转场动画、音量控制、缩放变换等高级功能。特别适合创建复杂的多视频组合场景，如画中画效果、视频拼接、过渡动画等。

更多文档

📖 更多详细文档和教程请访问：https://docs.jcaigc.cn

请求参数

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "video_infos": "[{/"video_url/":/"https://assets.jcaigc.cn/video1.mp4/",/"width/":1024,/"height/":1024,/"start/":0,/"end/":5000000,/"duration/":5000000,/"mask/":/"圆形/",/"transition/":/"淡入淡出/",/"transition_duration/":500000,/"volume/":0.8}]",
  "alpha": 0.5,
  "scale_x": 1.0,
  "scale_y": 1.0,
  "transform_x": 100,
  "transform_y": 200
}

参数说明

video_infos 数组结构

参数详解

时间参数

• start: 视频在时间轴上的开始时间，单位微秒（1秒 = 1,000,000微秒）
• end: 视频在时间轴上的结束时间，单位微秒
• duration: 视频文件的总时长，用于素材创建（可选参数，如果不传则默认为end-start）
• 播放时长: 实际播放时长 = end – start

透明度参数

• alpha: 全局透明度，应用于所有添加的视频

  • 1.0 = 完全不透明
  • 0.5 = 半透明
  • 0.0 = 完全透明
  • 范围：0.0 – 1.0

缩放参数

• scale_x/scale_y: X/Y轴方向的缩放比例
• 1.0 = 原始大小，0.5 = 缩小一半，2.0 = 放大两倍
• 建议范围：0.1 – 5.0

位置参数

• transform_x/transform_y: X/Y轴方向的位置偏移，单位像素
• 正值向右/下移动，负值向左/上移动
• 以画布中心为原点

遮罩类型

支持的遮罩类型：

• 圆形 – 圆形遮罩效果
• 爱心 – 爱心形状遮罩
• 星形 – 星形遮罩
• 矩形 – 矩形遮罩
• 线性 – 线性渐变遮罩
• 镜面 – 镜面反射遮罩

转场效果

• transition: 转场效果名称

• transition_duration: 转场持续时间

  • 最小值：100,000微秒（0.1秒）
  • 最大值：2,500,000微秒（2.5秒）
  • 推荐值：500,000微秒（0.5秒）

音量控制

• volume: 视频音量大小

  • 1.0 = 原始音量
  • 0.5 = 一半音量
  • 0.0 = 静音
  • 范围：0.0 – 1.0

响应格式

成功响应 (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "video-track-uuid",
  "video_ids": ["video1-uuid", "video2-uuid", "video3-uuid"],
  "segment_ids": ["segment1-uuid", "segment2-uuid", "segment3-uuid"]
}

响应字段说明

使用示例

cURL 示例

1. 基本视频添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos /
  -H "Content-Type: application/json" /
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{/"video_url/":/"https://assets.jcaigc.cn/video1.mp4/",/"width/":1920,/"height/":1080,/"start/":0,/"end/":5000000,/"duration/":10000000}]"
  }'

2. 多视频批量添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos /
  -H "Content-Type: application/json" /
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{/"video_url/":/"https://assets.jcaigc.cn/video1.mp4/",/"width/":1920,/"height/":1080,/"start/":0,/"end/":5000000,/"duration/":10000000},{/"video_url/":/"https://assets.jcaigc.cn/video2.mp4/",/"width/":1280,/"height/":720,/"start/":5000000,/"end/":10000000,/"duration/":8000000}]",
    "alpha": 0.8
  }'

3. 带遮罩和转场的视频

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos /
  -H "Content-Type: application/json" /
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{/"video_url/":/"https://assets.jcaigc.cn/video1.mp4/",/"width/":1024,/"height/":1024,/"start/":0,/"end/":5000000,/"duration/":10000000,/"mask/":/"圆形/",/"transition/":/"淡入淡出/",/"transition_duration/":500000,/"volume/":0.8}]",
    "alpha": 1.0,
    "scale_x": 1.2,
    "scale_y": 1.2
  }'

4. 画中画效果

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos /
  -H "Content-Type: application/json" /
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{/"video_url/":/"https://assets.jcaigc.cn/main.mp4/",/"width/":1920,/"height/":1080,/"start/":0,/"end/":10000000,/"duration/":15000000},{/"video_url/":/"https://assets.jcaigc.cn/pip.mp4/",/"width/":640,/"height/":360,/"start/":2000000,/"end/":8000000,/"duration/":10000000}]",
    "transform_x": 300,
    "transform_y": -200,
    "scale_x": 0.3,
    "scale_y": 0.3
  }'

错误码说明

注意事项

1. JSON格式: video_infos必须是合法的JSON字符串
2. 时间单位: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. 视频格式: 确保视频文件格式被支持（如MP4、AVI等）
4. 文件大小: 大视频文件可能影响处理速度
5. 网络访问: 视频URL必须可以正常访问
6. 遮罩限制: 只支持预定义的遮罩类型
7. 转场限制: 转场时长有固定范围限制
8. 性能考虑: 批量添加大量视频可能影响性能

工作流程

1. 验证必填参数（draft_url, video_infos）
2. 解析video_infos JSON字符串
3. 验证每个视频的参数配置
4. 获取并解密草稿内容
5. 创建视频轨道
6. 添加视频片段到轨道
7. 应用透明度、缩放和位置变换
8. 添加遮罩和转场效果
9. 设置音量
10. 保存并加密草稿
11. 返回处理结果

相关接口

• 创建草稿
• 添加音频
• 添加图片
• 保存草稿
• 生成视频

📚 项目资源
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

https://segmentfault.com/a/1190000047519844