python - 【剪映API】批量向现有草稿中添加视频素材 - Hommy - SegmentFault 思否

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

失落的木瓜_esfWwz

1 月 4 日

广东

阅读

分钟

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

}

参数说明

参数名

类型

必填

默认值

说明

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

❌

end-start

视频总时长(微秒)

mask

string

❌

遮罩类型

transition

string

❌

转场效果名称

transition_duration

number

❌

500000

转场持续时间(微秒)

volume

number

❌

1.0

音量大小(0-1)

参数详解

时间参数

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"]

}

响应字段说明

字段名

类型

说明

draft_url

string

更新后的草稿URL

track_id

string

视频轨道ID

video_ids

array

添加的视频ID列表

segment_ids

array

片段ID列表

使用示例

cURL 示例

基本视频添加

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}]" }'

多视频批量添加

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 }'

带遮罩和转场的视频

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 }'

画中画效果

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 }'

错误码说明

错误码

错误信息

说明

解决方案

400

draft_url是必填项

缺少草稿URL参数

提供有效的草稿URL

400

video_infos是必填项

缺少视频信息参数

提供有效的视频信息JSON

400

video_infos格式错误

JSON格式不正确

检查JSON字符串格式

400

video_url是必填项

视频URL缺失

为每个视频提供URL

400

视频尺寸无效

width或height无效

提供正数的宽度和高度

400

时间范围无效

end必须大于start

确保结束时间大于开始时间

400

透明度值无效

alpha不在0-1范围内

使用0-1之间的透明度值

404

草稿不存在

指定的草稿URL无效

检查草稿URL是否正确

404

视频资源不存在

视频URL无法访问

检查视频URL是否可访问

500

视频处理失败

内部处理错误

联系技术支持

注意事项

JSON格式

: video_infos必须是合法的JSON字符串

时间单位

: 所有时间参数使用微秒（1秒 = 1,000,000微秒）

视频格式

: 确保视频文件格式被支持（如MP4、AVI等）

文件大小

: 大视频文件可能影响处理速度

网络访问

: 视频URL必须可以正常访问

遮罩限制

: 只支持预定义的遮罩类型

转场限制

: 转场时长有固定范围限制

性能考虑

: 批量添加大量视频可能影响性能

工作流程

验证必填参数（draft_url, video_infos）

解析video_infos JSON字符串

验证每个视频的参数配置

获取并解密草稿内容

创建视频轨道

添加视频片段到轨道

应用透明度、缩放和位置变换

添加遮罩和转场效果

设置音量

保存并加密草稿

返回处理结果

相关接口

创建草稿

添加音频

添加图片

保存草稿

生成视频

📚

项目资源

GitHub

:

https://github.com/Hommy-master/capcut-mate

Gitee

:

https://gitee.com/taohongmin-gitee/capcut-mate

python

aigc

赞

收藏

阅读

628

发布于

1 月 4 日

举报

失落的木瓜_esfWwz

1

声望

0

粉丝

关注作者

« 上一篇

【剪映API】向现有草稿中添加图片

下一篇 »

【剪映API】查询视频生成任务的状态和进度

▲

原文链接: [https://segmentfault.com/a/1190000047519844](https://segmentfault.com/a/1190000047519844)