项目概述
目录
引言
capcut-mate 是一个面向剪映(CapCut)的完全开源免费的自动化处理与云端渲染辅助系统,基于 FastAPI 构建,支持独立部署。该项目的核心价值在于为大模型赋能基础视频编辑能力,提供开箱即用的视频编辑技能,并已完全自动化整个剪映核心功能工作流。项目能够直接连接大模型,实现多样化的智能视频编辑,使普通用户能够快速创建专业和高级的视频作品。
核心价值与目标
- 开源免费:完全开源免费,降低视频内容生产的门槛,提升批量与自动化能力
- 大模型集成:专注于为大模型赋能视频编辑能力,提供智能视频编辑解决方案
- 独立部署:支持独立部署,满足不同环境和安全要求
- 智能视频编辑:提供开箱即用的视频编辑技能,实现智能化视频创作
- 灵活协作:可与 Coze 或 n8n 结合构建自动化工作流,也可连接剪映实现云端渲染
主要功能特性
- 草稿创建与保存、素材批量添加(视频/音频/图片/贴纸)、字幕与特效配置、关键帧与遮罩、富文本样式生成
- 时间线与素材信息生成工具,辅助自动化编排
- 云端渲染提交与状态查询,以及草稿下载与本地剪映自动化导出
- :完整的工具函数集合,包括 URL 提取、贴纸搜索、数据格式转换等实用工具
- :智能视频编辑能力,支持与大模型的无缝集成
应用场景
- 内容创作者批量生产短视频、图文混排视频
- 企业级营销团队自动化生成系列视频
- 教育/培训领域批量生成教学视频
- 需要跨平台、可扩展的视频生产流水线
- 国际化团队协作,支持多语言环境下的视频制作工作流
- 大模型驱动的智能视频创作工作流
- AI 辅助的视频内容生成与编辑
技术选型与设计理念
- 后端:Python + FastAPI,OpenAPI 描述清晰,便于对接与测试
- 自动化:基于 Windows UI 自动化库与剪映窗口交互,实现草稿导出自动化
- 云渲染:通过腾讯云对象存储与 API Key 认证,实现云端渲染与素材分发
- 桌面客户端:Electron + React,提供草稿下载、历史记录与日志查看等能力
- 部署:Docker 化运行,便于在服务器或容器环境中部署
- 智能化:支持与大模型集成,实现智能视频编辑和内容生成
项目结构
项目采用"API 层—服务层—工具层—自动化层"的分层设计,配合模板与草稿缓存机制,形成可复用的草稿基座与渲染管线。项目结构体现了开源免费、独立部署和智能视频编辑的设计理念。
graph TB
subgraph "智能视频编辑架构"
AI["大模型集成<br/>AI Video Editing"]
ML["机器学习模型<br/>Video Generation"]
INT["智能协作<br/>Coze/n8n Workflows"]
end
subgraph "开源免费架构"
OPEN["开源免费<br/>完全开源免费"]
DEPLOY["独立部署<br/>支持独立部署"]
TOOLS["工具函数<br/>Utility Functions"]
end
subgraph "API 层"
R["FastAPI 路由<br/>src/router/v1.py"]
M["中间件<br/>PrepareMiddleware / ResponseMiddleware"]
end
subgraph "服务层"
S1["业务服务<br/>src/service/*"]
end
subgraph "工具层"
U1["草稿下载器<br/>src/utils/draft_downloader.py"]
U2["日志/下载/媒体工具<br/>src/utils/*"]
U3["工具函数<br/>src/utils/*"]
end
subgraph "自动化层"
A1["剪映控制器<br/>src/pyJianYingDraft/jianying_controller.py"]
end
subgraph "配置与模板"
C1["配置中心<br/>config.py"]
T1["模板目录<br/>template/*"]
end
subgraph "桌面客户端"
D1["Electron 主进程<br/>desktop-client/main.js"]
D2["前端页面与组件<br/>desktop-client/web/src/*"]
end
AI --> R
ML --> R
INT --> R
OPEN --> R
DEPLOY --> R
TOOLS --> R
R --> S1
S1 --> U1
S1 --> U2
S1 --> U3
S1 --> A1
S1 --> C1
S1 --> T1
D1 --> R
核心组件
API 服务(FastAPI)
- 路由集中于 v1 版本,覆盖草稿创建/保存、素材添加、特效/字幕/贴纸、关键帧/遮罩、富文本样式、时间线与素材信息生成、云端渲染提交与状态查询、URL 提取与序列转换等
- 统一响应中间件与准备中间件保证请求与响应的一致性与可观测性
- :支持与大模型的智能视频编辑接口
服务层(service/*)
- 将路由层的请求参数转化为具体业务动作,如创建草稿、下载草稿、生成素材信息、提交渲染任务等
- 与工具层、自动化层协作,完成跨模块的编排
- :智能视频编辑服务,支持大模型驱动的内容生成
工具层(utils/*)
- 草稿下载器负责从 API 获取草稿文件清单并下载至本地;提供安全写入、目录扫描触发等能力
- 日志、媒体处理、草稿缓存等工具支撑业务稳定运行
- :工具函数模块,提供数据格式转换、URL 处理、贴纸搜索等实用工具
自动化层(pyJianYingDraft)
- 剪映控制器通过 UI 自动化定位窗口、切换状态、设置导出分辨率/帧率、点击导出按钮、等待导出完成并移动文件
- 适用于本地 Windows 环境下的剪映自动化导出
- :智能视频编辑自动化,支持大模型生成内容的自动渲染
配置中心(config.py)
- 定义草稿目录、临时目录、下载/提示/草稿 URL、模板目录、草稿保存路径、云存储配置、API Key 开关等
- 云渲染相关配置(COS、API Key)为云端渲染提供基础
- :智能视频编辑配置选项
桌面客户端(Electron + React)
- Electron 主进程负责窗口创建、权限处理与 IPC 初始化
- 前端页面提供草稿下载、历史记录、日志查看与基础配置入口
- :智能视频编辑界面,支持大模型内容生成和编辑
架构总览
capcut-mate 的整体架构分为三层:API 层、服务层与自动化/工具层。API 层接收外部请求,服务层组织业务逻辑,工具层与自动化层负责文件下载、草稿缓存与剪映自动化导出。架构设计体现了开源免费、独立部署和智能视频编辑的理念。
graph TB
Client["客户端/调用方"] --> API["FastAPI 应用<br/>main.py"]
API --> Router["路由 v1<br/>src/router/v1.py"]
Router --> Service["服务层<br/>src/service/*"]
Service --> Downloader["草稿下载器<br/>src/utils/draft_downloader.py"]
Service --> Config["配置中心<br/>config.py"]
Service --> Templates["模板目录<br/>template/*"]
Service --> Controller["剪映控制器<br/>src/pyJianYingDraft/jianying_controller.py"]
Service --> Tools["工具函数<br/>src/utils/*"]
Service --> AI["智能视频编辑<br/>AI Integration"]
Desktop["桌面客户端<br/>desktop-client/main.js"] --> API
OPEN["开源免费"] --> API
DEPLOY["独立部署"] --> API
AI --> API
详细组件分析
组件 A:草稿创建与保存(create_draft)
功能要点
- 基于模板目录复制并修改画布尺寸,生成唯一草稿 ID,并启用双文件兼容模式以确保草稿内容一致性
- 自动添加空主轨道,便于后续素材落位
- 更新草稿缓存并返回草稿 URL,供后续编辑与渲染使用
- :支持智能视频编辑的草稿创建,为大模型生成内容提供基础
关键流程
- 生成草稿 ID → 复制模板 → 修改画布尺寸 → 保存草稿 → 添加主轨道 → 更新缓存 → 返回草稿 URL
flowchart TD
Start(["入口:create_draft"]) --> GenID["生成草稿ID"]
GenID --> CopyTpl["复制模板到草稿目录"]
CopyTpl --> LoadScript["加载草稿脚本并启用双文件兼容"]
LoadScript --> SetSize["设置画布宽高"]
SetSize --> SaveScript["保存草稿内容"]
SaveScript --> AddTrack["添加空主轨道"]
AddTrack --> UpdateCache["更新草稿缓存"]
UpdateCache --> ReturnURL["返回草稿URL"]
ReturnURL --> AIEnhance["智能视频编辑增强"]
AIEnhance --> End(["结束"])
组件 B:草稿下载与本地渲染(draft_downloader)
功能要点
- 从草稿 URL 提取草稿 ID,获取文件清单并逐个下载,确保原子写入与磁盘同步
- 下载完成后触发目录扫描,保证剪映能识别新增文件
- 支持自定义保存路径(默认使用配置中的草稿保存路径)
- :支持智能视频编辑内容的下载和渲染
关键流程
- 解析 URL → 提取 draft_id → 获取文件列表 → 逐个下载并写入 → 触发扫描 → 返回结果
flowchart TD
S(["入口:download_draft"]) --> ParseURL["解析草稿URL并提取draft_id"]
ParseURL --> BuildDir["准备目标目录"]
BuildDir --> FetchFiles["获取草稿文件清单"]
FetchFiles --> ForEach["遍历文件并下载"]
ForEach --> Scan["触发目录扫描"]
Scan --> AIProcess["智能视频编辑处理"]
AIProcess --> Done(["返回下载结果"])
组件 C:剪映自动化导出(JianyingController)
功能要点
- 通过 UI 自动化定位剪映窗口,支持首页、编辑页、导出前置页的状态切换
- 设置导出分辨率与帧率,点击最终导出按钮,并等待导出完成或成功提示
- 导出完成后可将文件移动到指定位置,便于后续上传或归档
- :支持智能视频编辑内容的自动化导出
关键流程
- 初始化窗口 → 切换到首页 → 定位草稿 → 进入编辑页 → 点击导出 → 设置分辨率/帧率 → 点击最终导出 → 等待完成 → 返回首页
sequenceDiagram
participant Dev as "调用方"
participant Ctrl as "JianyingController"
participant AI as "智能视频编辑"
participant UI as "剪映窗口"
Dev->>Ctrl : export_draft(draft_name, output_path, ...)
Ctrl->>AI : 获取智能编辑内容
AI-->>Ctrl : 返回编辑后的内容
Ctrl->>UI : 定位窗口并置顶
Ctrl->>UI : 切换到首页
Ctrl->>UI : 查找并点击草稿
Ctrl->>UI : 点击导出按钮
Ctrl->>UI : 设置分辨率/帧率
Ctrl->>UI : 点击最终导出
Ctrl->>UI : 等待导出完成/成功
Ctrl->>Ctrl : 移动导出文件
Ctrl-->>Dev : 返回完成状态
组件 D:桌面客户端(Electron)
功能要点
- Electron 主进程负责窗口创建、图标适配、开发/生产模式加载、IPC 初始化与异常处理
- 前端页面提供下载、历史记录、日志模块与基础配置入口,便于本地用户操作与调试
- :智能视频编辑界面,支持大模型内容生成和编辑
关键流程
- 应用启动 → 创建窗口 → 加载页面(开发/生产)→ 初始化 IPC → 监听事件 → 异常捕获与提示
sequenceDiagram
participant App as "Electron 应用"
participant AI as "智能视频编辑"
participant Win as "BrowserWindow"
participant IPC as "IPC处理器"
participant FE as "React 页面"
App->>Win : createWindow()
Win->>FE : 加载页面(开发/生产)
App->>IPC : setupIpcHandlers()
FE-->>App : 用户操作(下载/历史/日志/智能编辑)
App-->>FE : 返回结果/状态
AI-->>FE : 提供智能视频编辑功能
组件 E:API 与 OpenAPI 描述
功能要点
- API 路由集中在 v1,覆盖草稿、素材、特效、字幕、渲染、时间线与工具类接口
- OpenAPI 描述文件提供接口规范、请求/响应示例与错误码说明,便于联调与自动化测试
- :支持智能视频编辑的 API 接口
关键流程
- 客户端发起请求 → FastAPI 路由解析 → 服务层处理 → 工具/自动化层执行 → 返回统一响应
sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI"
participant Router as "路由 v1"
participant Service as "服务层"
participant Utils as "工具/自动化"
participant AI as "智能视频编辑"
Client->>API : HTTP 请求
API->>Router : 路由分发
Router->>Service : 参数校验与业务处理
Service->>AI : 智能视频编辑处理
AI-->>Service : 返回编辑结果
Service->>Utils : 下载/渲染/导出等
Utils-->>Service : 执行结果
Service-->>Router : 统一响应模型
Router-->>Client : JSON 响应
工具函数详解
工具函数概览
capcut-mate 提供了一套完整的工具函数集合,专门用于处理常见的数据格式转换和内容提取需求。这些工具函数通过统一的 API 接口暴露,方便开发者在视频制作流程中进行数据处理和格式转换。新增:支持智能视频编辑的工具函数。
get_url 工具函数
用于从输入内容中提取 URL 信息,支持从复杂的字符串格式中解析出有效的链接地址。
接口信息
- 请求方法:POST
- 请求路径:/openapi/capcut-mate/v1/get_url
- 功能描述:提取链接,用于多值返回变成单值返回
请求参数
- output (string, 必填):需要提取链接的内容
- 示例:
"[魂牵梦萦https://sf.com;中国人https://jcaigc.cn],\"[]\""
响应格式
- 成功响应:返回包含提取结果的 JSON 对象
- 错误响应:返回标准错误信息
search_sticker 工具函数
根据关键词搜索贴纸素材,返回匹配的贴纸列表,包括贴纸的详细信息如图片 URL、尺寸、类型等。
接口信息
- 请求方法:POST
- 请求路径:/openapi/capcut-mate/v1/search_sticker
- 功能描述:根据关键词搜索贴纸
请求参数
- keyword (string, 必填):搜索贴纸的关键词
- 示例:"人"、"花"、"动物"
响应格式
- 成功响应:返回包含贴纸数据列表的 JSON 对象
- 响应字段:包含贴纸详细信息、贴纸 ID、标题等
objs_to_str_list 工具函数
将对象列表转换为字符串列表格式,主要用于处理包含 URL 地址的数据结构。
接口信息
- 请求方法:POST
- 请求路径:/openapi/capcut-mate/v1/objs_to_str_list
- 功能描述:对象列表转化成字符串列表
请求参数
- outputs (array[object], 必填):数据对象列表
- 示例:
[{"output": "https://assets.jcaigc.cn/min.mp4"}, {"output": "https://assets.jcaigc.cn/max.mp4"}]
响应格式
- 成功响应:返回包含字符串列表的 JSON 对象
- 返回值:将输入的对象列表中的 output 字段提取出来组成字符串列表
str_list_to_objs 工具函数
将字符串列表转换为对象列表格式,与 objs_to_str_list 功能相反,用于数据格式的逆向转换。
接口信息
- 请求方法:POST
- 请求路径:/openapi/capcut-mate/v1/str_list_to_objs
- 功能描述:字符串列表转化成对象列表
请求参数
- infos (array[string], 必填):字符串列表
- 示例:
["https://assets.jcaigc.cn/min.mp4", "https://assets.jcaigc.cn/max.mp4"]
响应格式
- 成功响应:返回包含对象列表的 JSON 对象
- 返回值:将输入的字符串列表转换为包含 output 字段的对象列表
str_to_list 工具函数
将输入的字符串转换为列表格式,主要用于处理单个字符串内容的包装。
接口信息
- 请求方法:POST
- 请求路径:/openapi/capcut-mate/v1/str_to_list
- 功能描述:字符转列表
请求参数
- obj (string, 必填):对象内容
- 示例:
"{ \"infos\": [ \"https://assets.jcaigc.cn/min.mp4\", \"https://assets.jcaigc.cn/max.mp4\" ] }"
响应格式
- 成功响应:返回包含字符串列表的 JSON 对象
- 返回值:将输入的字符串作为单个元素放入列表中返回
依赖关系分析
组件耦合与内聚
- API 层与服务层通过统一的 Pydantic 模型解耦,便于扩展与测试
- 服务层与工具层/自动化层通过函数调用解耦,职责清晰
- 配置中心集中管理路径与云存储参数,避免散落的硬编码
- :工具函数模块独立于核心业务逻辑,提供可重用的数据处理能力
- :智能视频编辑模块与核心业务逻辑松耦合,支持插件式集成
外部依赖
- Python 生态:FastAPI、uiautomation(剪映自动化)、requests(HTTP)、腾讯云 COS SDK(云渲染)
- 前端生态:Electron、React、Vite(开发/打包)
- :大模型集成依赖,支持与各种 AI 平台的对接
- :智能视频编辑框架,支持多种视频生成和编辑算法
graph LR
API["API 层<br/>main.py + v1.py"] --> SVC["服务层<br/>service/*"]
SVC --> UTIL["工具层<br/>utils/*"]
SVC --> AUTO["自动化层<br/>pyJianYingDraft"]
SVC --> CFG["配置中心<br/>config.py"]
UTIL --> TOOLS["工具函数<br/>get_url/search_sticker/*"]
SVC --> AI["智能视频编辑<br/>AI Integration"]
DESK["桌面客户端<br/>desktop-client"] --> API
OPEN["开源免费"] --> API
DEPLOY["独立部署"] --> API
AI --> API
性能考量
草稿创建
- 模板复制与双文件保存需注意 I/O 性能,建议在 SSD 上运行并合理设置草稿目录
- :智能视频编辑内容的创建需要额外的计算资源,建议预留充足的 CPU 和内存
草稿下载
- 并行下载与断点续传可进一步优化,当前实现采用逐个下载与原子写入,保证可靠性
- :大模型生成内容的下载需要考虑网络带宽和存储空间
云端渲染
- 素材 URL 稳定性与带宽直接影响渲染时长;建议使用 CDN 与高质量素材
- :智能视频编辑内容的渲染需要更强的 GPU 性能支持
剪映自动化导出
- 导出超时与分辨率/帧率设置需结合硬件性能与素材复杂度进行权衡
- :大模型生成内容的导出需要考虑文件大小和导出质量
桌面客户端
- 开发模式下启用调试工具会增加内存占用,生产打包后性能更佳
- :智能视频编辑界面需要更多的内存和 CPU 资源
工具函数性能
- 数据格式转换操作通常为 O(n) 复杂度,其中 n 为数据项数量
- URL 提取和贴纸搜索操作受数据规模影响,建议对大量数据进行分批处理
- :智能视频编辑工具函数的性能取决于具体的算法复杂度
故障排查指南
常见问题与定位
- 草稿创建失败:检查模板目录是否存在、权限是否足够、画布尺寸是否合法
- 草稿下载失败:确认草稿 URL 有效、网络可达、目标目录可写
- 剪映自动化导出失败:确认剪映窗口可见、分辨率/帧率设置正确、导出超时阈值合理
- 云端渲染失败:检查 API Key 与 COS 配置、素材 URL 可达性、渲染服务器负载
- 桌面客户端权限错误:在系统偏好设置中授予应用所需文件夹访问权限
- :智能视频编辑失败:检查大模型连接、模型可用性和计算资源
- :工具函数调用失败:检查参数验证、数据格式和编码问题
日志与监控
- API 层与服务层均使用统一日志模块,便于追踪请求与异常
- 剪映控制器与下载器提供详细的步骤日志,有助于定位自动化环节的问题
- :智能视频编辑模块的日志,记录 AI 处理过程和异常情况
- :工具函数调用日志,记录数据转换过程和异常情况
结论
capcut-mate 通过清晰的分层架构与完善的 API 描述,实现了从草稿创建、素材编排到云端渲染与本地导出的全链路自动化。其设计理念强调"可扩展、可运维、易接入",既满足初学者快速上手,也具备足够的灵活性供高级用户定制。新增:完善的开源免费、独立部署和智能视频编辑支持进一步提升了项目的实用性,结合桌面客户端与容器化部署,项目可在多种场景下高效落地,支持多语言环境下的视频制作工作流,特别适合大模型驱动的智能视频创作应用。
附录
实际使用案例(概念性演示)
- 批量短视频生成:先调用创建草稿接口生成草稿,再批量添加视频/音频/图片与字幕,最后提交云端渲染并轮询状态,完成后下载成品
- 本地自动化导出:在本地通过桌面客户端下载草稿,使用剪映控制器一键导出到指定目录,便于离线处理与归档
- 模板化生产:基于模板目录快速生成标准规格的草稿,统一画布尺寸与轨道结构,减少重复配置成本
- :智能视频编辑工作流:通过大模型生成创意内容,自动创建草稿并进行智能编辑,最后导出成品
- :国际化协作:多语言团队可以通过统一的 API 接口和工具函数进行视频内容的创建和处理,支持不同语言环境下的协作
参考文档
- 草稿创建接口文档:docs/create_draft.md
- 云端渲染接口文档:docs/gen_video.md
- :智能视频编辑文档
- :大模型集成指南
- :工具函数文档
- URL 提取工具:docs/get_url.md
- 贴纸搜索工具:docs/search_sticker.md
- 数据格式转换工具:docs/objs_to_str_list.md、docs/str_list_to_objs.md、docs/str_to_list.md