ADD_VIDEOS API 接口文档

接口信息

请求方式: POST
接口地址: /openapi/capcut-tools/v1/add_videos

功能描述

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

更多文档: 📖 速创 AIGC-工具平台官方文档

请求参数

{
  "draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/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
}

参数说明

参数名	类型	必填	默认值	说明
draft_url	string	✅	-	目标草稿的完整 URL
video_infos	string	✅	-	视频信息数组的 JSON 字符串
alpha	number	❌	1.0	全局透明度(0-1)
scale_x	number	❌	1.0	X 轴缩放比例
scale_y	number	❌	1.0	Y 轴缩放比例
transform_x	number	❌	0	X 轴位置偏移(像素)
transform_y	number	❌	0	Y 轴位置偏移(像素)

video_infos 数组结构

字段名	类型	必填	默认值	说明
video_url	string	✅	-	视频文件的 URL 地址
width	number	✅	-	视频宽度(像素)
height	number	✅	-	视频高度(像素)
start	number	✅	-	视频开始播放时间(微秒)
end	number	✅	-	视频结束播放时间(微秒)
duration	number	✅	-	视频总时长(微秒)
mask	string	❌	-	遮罩类型
transition	string	❌	-	转场效果名称
transition_duration	number	❌	500000	转场持续时间(微秒)
volume	number	❌	1.0	音量大小(0-1)

参数详解

时间参数

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://agent.aigc-ai.com/openapi/capcut-tools/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"]
}

响应字段说明

字段名	类型	说明
draft_url	string	更新后的草稿 URL
track_id	string	视频轨道 ID
video_ids	array	添加的视频 ID 列表
segment_ids	array	片段 ID 列表

使用示例

cURL 示例

1. 基本视频添加

curl -X POST https://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/main_video.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":10000000,\"duration\":10000000},{\"video_url\":\"https://assets.jcaigc.cn/pip_video.mp4\",\"width\":640,\"height\":360,\"start\":2000000,\"end\":8000000,\"duration\":8000000}]",
    "alpha": 0.9,
    "scale_x": 0.5,
    "scale_y": 0.5,
    "transform_x": 400,
    "transform_y": 200
  }'