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

透明度参数

• 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. 返回处理结果

相关接口

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