项目概述

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 工具函数详解
7. 依赖关系分析
8. 性能考量
9. 故障排查指南
10. 结论
11. 附录

引言

capcut-mate 是一个面向剪映（CapCut）的完全开源免费的自动化处理与云端渲染辅助系统，基于 FastAPI 构建，支持独立部署。该项目的核心价值在于为大模型赋能基础视频编辑能力，提供开箱即用的视频编辑技能，并已完全自动化整个剪映核心功能工作流。项目能够直接连接大模型，实现多样化的智能视频编辑，使普通用户能够快速创建专业和高级的视频作品。

• 核心价值与目标

  • 开源免费：完全开源免费，降低视频内容生产的门槛，提升批量与自动化能力
  • 大模型集成：专注于为大模型赋能视频编辑能力，提供智能视频编辑解决方案
  • 独立部署：支持独立部署，满足不同环境和安全要求
  • 智能视频编辑：提供开箱即用的视频编辑技能，实现智能化视频创作
  • 灵活协作：可与 Coze 或 n8n 结合构建自动化工作流，也可连接剪映实现云端渲染

• 主要功能特性

  • 草稿创建与保存、素材批量添加（视频/音频/图片/贴纸）、字幕与特效配置、关键帧与遮罩、富文本样式生成
  • 时间线与素材信息生成工具，辅助自动化编排
  • 云端渲染提交与状态查询，以及草稿下载与本地剪映自动化导出
  • ：完整的工具函数集合，包括 URL 提取、贴纸搜索、数据格式转换等实用工具
  • ：智能视频编辑能力，支持与大模型的无缝集成

• 应用场景

  • 内容创作者批量生产短视频、图文混排视频
  • 企业级营销团队自动化生成系列视频
  • 教育/培训领域批量生成教学视频
  • 需要跨平台、可扩展的视频生产流水线
  • 国际化团队协作，支持多语言环境下的视频制作工作流
  • 大模型驱动的智能视频创作工作流
  • AI 辅助的视频内容生成与编辑

• 技术选型与设计理念

  • 后端：Python + FastAPI，OpenAPI 描述清晰，便于对接与测试
  • 自动化：基于 Windows UI 自动化库与剪映窗口交互，实现草稿导出自动化
  • 云渲染：通过腾讯云对象存储与 API Key 认证，实现云端渲染与素材分发
  • 桌面客户端：Electron + React，提供草稿下载、历史记录与日志查看等能力
  • 部署：Docker 化运行，便于在服务器或容器环境中部署
  • 智能化：支持与大模型集成，实现智能视频编辑和内容生成

项目结构

项目采用"API 层—服务层—工具层—自动化层"的分层设计，配合模板与草稿缓存机制，形成可复用的草稿基座与渲染管线。项目结构体现了开源免费、独立部署和智能视频编辑的设计理念。

核心组件

• 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 层接收外部请求，服务层组织业务逻辑，工具层与自动化层负责文件下载、草稿缓存与剪映自动化导出。架构设计体现了开源免费、独立部署和智能视频编辑的理念。

详细组件分析

组件 A：草稿创建与保存（create_draft）

• 功能要点

  • 基于模板目录复制并修改画布尺寸，生成唯一草稿 ID，并启用双文件兼容模式以确保草稿内容一致性
  • 自动添加空主轨道，便于后续素材落位
  • 更新草稿缓存并返回草稿 URL，供后续编辑与渲染使用
  • ：支持智能视频编辑的草稿创建，为大模型生成内容提供基础

• 关键流程

  • 生成草稿 ID → 复制模板 → 修改画布尺寸 → 保存草稿 → 添加主轨道 → 更新缓存 → 返回草稿 URL

组件 B：草稿下载与本地渲染（draft_downloader）

• 功能要点

  • 从草稿 URL 提取草稿 ID，获取文件清单并逐个下载，确保原子写入与磁盘同步
  • 下载完成后触发目录扫描，保证剪映能识别新增文件
  • 支持自定义保存路径（默认使用配置中的草稿保存路径）
  • ：支持智能视频编辑内容的下载和渲染

• 关键流程

  • 解析 URL → 提取 draft_id → 获取文件列表 → 逐个下载并写入 → 触发扫描 → 返回结果

组件 C：剪映自动化导出（JianyingController）

• 功能要点

  • 通过 UI 自动化定位剪映窗口，支持首页、编辑页、导出前置页的状态切换
  • 设置导出分辨率与帧率，点击最终导出按钮，并等待导出完成或成功提示
  • 导出完成后可将文件移动到指定位置，便于后续上传或归档
  • ：支持智能视频编辑内容的自动化导出

• 关键流程

  • 初始化窗口 → 切换到首页 → 定位草稿 → 进入编辑页 → 点击导出 → 设置分辨率/帧率 → 点击最终导出 → 等待完成 → 返回首页

组件 D：桌面客户端（Electron）

• 功能要点

  • Electron 主进程负责窗口创建、图标适配、开发/生产模式加载、IPC 初始化与异常处理
  • 前端页面提供下载、历史记录、日志模块与基础配置入口，便于本地用户操作与调试
  • ：智能视频编辑界面，支持大模型内容生成和编辑

• 关键流程

  • 应用启动 → 创建窗口 → 加载页面（开发/生产）→ 初始化 IPC → 监听事件 → 异常捕获与提示

组件 E：API 与 OpenAPI 描述

• 功能要点

  • API 路由集中在 v1，覆盖草稿、素材、特效、字幕、渲染、时间线与工具类接口
  • OpenAPI 描述文件提供接口规范、请求/响应示例与错误码说明，便于联调与自动化测试
  • ：支持智能视频编辑的 API 接口

• 关键流程

  • 客户端发起请求 → FastAPI 路由解析 → 服务层处理 → 工具/自动化层执行 → 返回统一响应

工具函数详解

工具函数概览

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 平台的对接
  • ：智能视频编辑框架，支持多种视频生成和编辑算法

性能考量

• 草稿创建

  • 模板复制与双文件保存需注意 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](file://docs/create_draft.md#L1-L165)
  • 云端渲染接口文档：[docs/gen_video.md](file://docs/gen_video.md#L1-L141)
  • ：智能视频编辑文档
  • ：大模型集成指南
  • ：工具函数文档
    • URL 提取工具：[docs/get_url.md](file://docs/get_url.md#L1-L107)
    • 贴纸搜索工具：[docs/search_sticker.md](file://docs/search_sticker.md#L1-L148)
    • 数据格式转换工具：[docs/objs_to_str_list.md](file://docs/objs_to_str_list.md#L1-L124)、[docs/str_list_to_objs.md](file://docs/str_list_to_objs.md#L1-L121)、[docs/str_to_list.md](file://docs/str_to_list.md#L1-L109)

文档信息

• 接口文档： docs.jcaigc.cn
• 效果案例： www.jcaigc.cn/workflow
• 开源仓库： capcut-mate