视频处理接口
目录
简介
视频处理接口是 CapCut Mate 项目的核心功能模块，用于向剪映草稿中批量添加视频素材。该接口支持多个视频的批量处理，包括时间范围控制、透明度调整、遮罩效果、转场动画、音量控制、缩放变换等高级功能。
重要更新：新增场景时间线功能，支持基于场景时长自动计算视频播放速度，为视频变速提供智能化解决方案。通过统一的 API 接口，开发者可以轻松将视频素材集成到剪映项目中，实现丰富的视频编辑功能，包括精确的速度控制和时间线同步。
项目结构
CapCut Mate 项目采用模块化设计，主要包含以下核心模块：
数据存储
核心引擎
业务逻辑层
API 层
路由层
数据模型
服务层
工具类
剪映草稿引擎
媒体处理
草稿缓存
本地存储
核心组件
API 接口定义
视频处理接口的核心是 /v1/add_videos 端点，提供完整的视频添加功能：
| 组件 | 描述 | 关键特性 |
|---|---|---|
| 请求参数 | 视频添加的输入参数 | 支持批量视频、时间范围、变换参数、场景时间线 |
| 响应格式 | 处理结果的标准输出 | 包含轨道ID、视频ID、片段ID |
| 验证机制 | 参数验证和错误处理 | 完整的输入验证和异常处理 |
| 缓存管理 | 草稿内容缓存 | 高效的内存缓存机制 |
数据模型结构
"包含多个"
"包含多个"
"响应"
AddVideosRequest
+string draft_url
+string video_infos
+float alpha
+float scale_x
+float scale_y
+int transform_x
+int transform_y
+SceneTimelineItem[] scene_timelines
AddVideosResponse
+string draft_url
+string track_id
+string[] video_ids
+string[] segment_ids
SceneTimelineItem
+int start
+int end
VideoInfo
+string video_url
+number width
+number height
+number start
+number end
+number duration
+string mask
+string transition
+number transition_duration
+number volume
架构概览
视频处理接口采用分层架构设计，确保代码的可维护性和扩展性：
"缓存系统" "剪映引擎" "服务层" "路由层" "客户端" "缓存系统" "剪映引擎" "服务层" "路由层" "客户端" POST /v1/add_videos 验证请求参数 获取草稿缓存 返回草稿对象 创建视频轨道 添加视频片段 应用变换效果 计算视频速度 返回片段ID 更新草稿缓存 返回处理结果 JSON 响应
核心处理流程
- 参数验证：检查必需参数的有效性
- 草稿获取：从缓存中获取指定的剪映草稿
- 轨道创建：为视频素材创建专用轨道
- 视频处理：下载、解析和添加视频素材
- 场景时间线处理：计算视频播放速度
- 效果应用：应用透明度、缩放、位置等变换
- 结果返回：返回处理完成的草稿URL和相关ID
详细组件分析
视频轨道管理系统
视频轨道是剪映项目中重要的概念之一，负责管理和组织各种媒体素材：
"枚举类型"
"包含片段"
TrackType
+video
+audio
+effect
+filter
+sticker
+text
Track
+string track_id
+string name
+int render_index
+boolean mute
+Segment[] segments
+end_time() : int
+add_segment(segment) : Track
VideoSegment
+string segment_id
+VideoMaterial material_instance
+Timerange target_timerange
+Timerange source_timerange
+float speed
+float volume
+ClipSettings clip_settings
+add_transition(transition, duration)
+add_mask(mask_type, ...)
轨道分配机制
系统采用智能轨道分配策略，确保视频素材不会与主轨道产生冲突：
| 轨道类型 | 渲染层级 | 用途 | 特殊规则 |
|---|---|---|---|
| 主视频轨道 | 0 | 基础视频内容 | 必须从0秒开始 |
| 自定义视频轨道 | 10+ | 批量视频添加 | 相对索引10，避免冲突 |
| 音频轨道 | 0 | 音频素材 | 与视频轨道分离 |
| 特效轨道 | 10000+ | 特效应用 | 最高层级 |
| 文本轨道 | 15000 | 文本内容 | 避免与贴纸冲突 |
视频变换参数系统
视频变换参数提供了丰富的视觉效果控制能力：
有效
无效
有效
无效
有效
无效
有效
无效
有效
无效
开始处理视频
解析变换参数
透明度检查
缩放参数检查
设置默认透明度
X轴缩放检查
Y轴缩放检查
设置默认X轴缩放
Y轴缩放有效?
位置参数检查
设置默认Y轴缩放
X轴位置检查
Y轴位置检查
设置默认X轴位置
Y轴位置有效?
应用变换设置
设置默认Y轴位置
转换坐标单位
创建剪辑设置
完成处理
变换参数详解
| 参数 | 类型 | 默认值 | 有效范围 | 说明 |
|---|---|---|---|---|
| alpha | float | 1.0 | [0.0, 1.0] | 全局透明度控制 |
| scale_x | float | 1.0 | [0.1, 5.0] | X轴缩放比例 |
| scale_y | float | 1.0 | [0.1, 5.0] | Y轴缩放比例 |
| transform_x | int | 0 | 任意整数 | X轴位置偏移（像素） |
| transform_y | int | 0 | 任意整数 | Y轴位置偏移（像素） |
坐标转换机制：
- 位置参数需要从像素转换为相对画布单位
- 转换公式：
transform_unit = transform_pixel / canvas_dimension - 以画布中心为原点的坐标系统
多视频片段组织方式
系统支持复杂的多视频组合场景，通过智能的时间线管理和轨道分配实现：
片段管理
轨道组织
时间线管理
时间线
起始点
结束点
主视频轨道
自定义视频轨道
特效轨道
片段1
片段2
片段3
重叠片段
时间范围控制
每个视频片段都有精确的时间控制：
| 参数 | 类型 | 单位 | 说明 |
|---|---|---|---|
| start | number | 微秒 | 片段在时间轴上的开始时间 |
| end | number | 微秒 | 片段在时间轴上的结束时间 |
| duration | number | 微秒 | 视频素材的总时长 |
| 播放时长 | number | 微秒 | 实际播放时长 = end - start |
重要更新：新增场景时间线功能，支持基于场景时长自动计算视频播放速度
时间参数的特殊处理：
duration参数用于素材创建，不参与播放控制- 实际播放时长由
end - start决定 - 支持不同的
duration和播放时长设置 - ：当提供
scene_timelines时，速度会根据场景时长自动计算
场景时间线功能详解
新增功能：场景时间线功能为视频变速提供智能化解决方案
是
否
是
否
开始处理视频
解析场景时间线
是否有场景时间线?
计算播放速度
使用正常速度(1.0)
获取场景时长
场景时长>0?
speed = 播放时长 / 场景时长
应用计算的速度
创建视频片段
完成处理
场景时间线参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| scene_timelines | array[object] | 可选 | 场景时间线数组，用于视频变速 |
| start | number | ✅ | 场景开始时间（微秒） |
| end | number | ✅ | 场景结束时间（微秒） |
速度计算公式：
speed = (video.end - video.start) / (scene_timeline.end - scene_timeline.start)使用示例：
- 视频时间线：0-2000000微秒（2秒）
- 场景时间线：0-1000000微秒（1秒）
- 结果：视频以2倍速播放，实际播放时长1秒
场景时间线应用场景
- 时间压缩：将较长的视频内容压缩到特定场景时长
- 节奏控制：根据音乐节拍或其他场景要求调整视频播放速度
- 多视频同步：确保多个视频片段与场景时间线保持同步
- 自动化变速：基于场景时长自动计算最优播放速度
遮罩和转场效果系统
系统提供了丰富的视觉效果选项，支持多种遮罩类型和转场动画：
遮罩类型支持
明确标注所有遮罩类型均为可选参数，默认为无遮罩效果
| 遮罩类型 | 描述 | 默认行为 |
|---|---|---|
| 圆形 | 圆形遮罩效果 | 保留圆形区域 |
| 矩形 | 矩形遮罩效果 | 保留矩形区域 |
| 爱心 | 爱心形状遮罩 | 保留爱心区域 |
| 星形 | 星形遮罩效果 | 保留星形区域 |
| 线性 | 线性渐变遮罩 | 线性过渡 |
| 镜面 | 镜面反射遮罩 | 反射效果 |
遮罩参数的可选性说明：
mask参数为可选参数，默认值为None（无遮罩）- 当不提供
mask参数时，视频将按原始状态显示 - 支持的遮罩类型包括：
circle、rectangle、heart、star、linear、mirror - 所有遮罩类型均为可选参数，不影响视频的基本播放
转场效果系统
系统支持超过300种转场效果，涵盖免费和付费效果：
| 转场类别 | 数量 | 默认时长 | 特点 |
|---|---|---|---|
| 免费效果 | 200+ | 0.4-2.0秒 | 基础转场效果 |
| 付费效果 | 100+ | 0.6-2.0秒 | 高级视觉效果 |
| 自定义效果 | 支持 | 可配置 | 用户自定义参数 |
转场效果的智能匹配：
- 根据转场名称自动查找对应的效果类型
- 支持默认时长和自定义时长
- 提供错误处理和降级机制
响应格式和数据结构
视频处理接口的响应包含完整的处理结果信息：
"扩展"
VideoProcessingResponse
+string draft_url
+string track_id
+string[] video_ids
+string[] segment_ids
ProcessingResult
+string draft_url
+string track_id
+string[] video_ids
+string[] segment_ids
+int videos_count
+int total_duration
响应字段说明
| 字段名 | 类型 | 说明 | 示例值 |
|---|---|---|---|
| draft_url | string | 更新后的草稿URL | "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258" |
| track_id | string | 视频轨道ID | "video-track-uuid" |
| video_ids | array | 视频素材ID列表 | ["video1-uuid", "video2-uuid"] |
| segment_ids | array | 视频片段ID列表 | ["segment1-uuid", "segment2-uuid"] |
依赖关系分析
视频处理接口涉及多个层次的依赖关系，形成了完整的处理链路：
核心组件
内部模块
外部依赖
FFmpeg 媒体处理
网络下载
文件系统
路由层
服务层
剪映引擎
工具类
草稿引擎
媒体处理器
缓存管理器
关键依赖关系
- 剪映引擎依赖 ：通过
src.pyJianYingDraft模块与剪映草稿系统交互 - 缓存系统依赖：使用内存缓存提高草稿访问效率
- 媒体处理依赖：集成 FFmpeg 进行视频处理和格式转换
- 网络下载依赖：支持远程视频文件的下载和处理
性能考虑
视频处理接口在设计时充分考虑了性能优化，特别是在处理大量视频素材时的性能表现：
缓存策略
- 内存缓存：草稿内容存储在内存中，避免重复读取
- 增量更新：只更新发生变化的部分，减少磁盘IO
- 生命周期管理：自动清理长时间未使用的草稿缓存
并发处理
- 异步下载：视频文件下载采用异步方式，提高并发处理能力
- 批处理优化：多个视频素材可以并行处理
- 资源池管理：数据库连接和文件句柄的池化管理
内存管理
- 流式处理：大文件采用流式处理，避免内存溢出
- 及时释放：处理完的资源及时释放，防止内存泄漏
- 垃圾回收：合理使用Python的垃圾回收机制
故障排除指南
常见错误类型和解决方案
| 错误类型 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 参数验证错误 | 400 | 缺少必需参数或参数格式错误 | 检查请求参数的完整性和格式 |
| 草稿不存在 | 404 | 指定的草稿URL无效 | 验证草稿URL的正确性 |
| 视频资源不可访问 | 404 | 视频URL无法访问 | 检查视频文件的可访问性 |
| 场景时间线无效 | 400 | 场景时长为0或负数 | 确保场景时间线参数有效 |
| 内部处理错误 | 500 | 视频处理失败 | 联系技术支持或检查服务器状态 |
调试和监控
- 日志记录：详细的处理过程日志，便于问题诊断
- 性能监控：关键操作的执行时间和资源使用情况
- 错误追踪：完整的异常堆栈信息和上下文数据
结论
视频处理接口为 CapCut Mate 项目提供了强大而灵活的视频添加功能。通过精心设计的架构和完善的错误处理机制，该接口能够满足各种复杂的视频编辑需求。
重要更新：新增的场景时间线功能显著增强了视频处理能力，为开发者提供了智能化的速度控制解决方案。通过基于场景时长自动计算视频播放速度，实现了精确的时间同步和节奏控制。
主要优势
- 功能完整性：支持透明度、缩放、位置变换等多种视觉效果
- 智能速度控制：新增场景时间线功能，支持自动视频变速
- 性能优化：高效的缓存机制和并发处理能力
- 易用性：简洁的API设计和详细的文档说明
- 扩展性：模块化设计便于功能扩展和维护
应用场景
- 批量视频处理：支持多个视频素材的同时添加
- 复杂视频合成：创建画中画、视频拼接等效果
- 自动化视频制作：与其他系统集成，实现自动化视频处理流程
- 智能变速控制：基于场景时长自动调整视频播放速度
- 多视频同步：确保多个视频片段与场景时间线保持同步
该接口为视频编辑应用开发提供了坚实的基础，开发者可以基于此接口快速构建各种视频处理功能，特别是需要精确速度控制和时间同步的高级应用场景。
文档信息
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate