capcut-mate/README.zh.md

CapCut Mate API

🌐 语言切换

中文版 | English

项目简介

CapCut Mate API 是一款完全开源免费、基于 FastAPI构建的剪映草稿自动化助手，支持独立部署。本项目专注于为大模型赋能基础视频编辑能力，提供开箱即用的视频剪辑 Skills，已将剪映核心功能全流程自动化。可直接对接大模型实现多样化智能视频剪辑，让普通用户也能快速制作出专业高级的视频作品。

项目使用灵活：既可独立部署，也可结合 Coze 或 n8n自动化工作流，还能对接剪映实现云渲染，直接将草稿生成最终视频。

项目相关资源

• ⭐ 剪映小助手
• 🔌 剪映小助手-扣子插件
• 🔗 工作流案例

⭐ 如果您觉得这个项目对您有点帮助，麻烦点个 Star 支持一下！您的支持是我持续维护和改进项目的最大动力 😊

功能特点

• 🎬 草稿管理：创建草稿、获取草稿、保存草稿
• 🎥 素材添加：添加视频、音频、图片、贴纸、字幕、特效、遮罩等
• 🔧 高级功能：关键帧控制、文字样式、动画效果等
• 📤 视频导出：云端渲染生成最终视频
• 🛡️ 数据验证：使用 Pydantic 进行请求数据验证
• 📖 RESTful API：符合标准的 API 设计规范
• 📚 自动文档：FastAPI 自动生成交互式 API 文档

技术栈

• Python 3.11+
• FastAPI：高性能的 Web 框架
• Pydantic：数据验证和模型定义
• Passlib：密码加密（如果使用用户认证）
• Uvicorn：ASGI 服务器
• uv：Python 包管理器和项目管理工具

快速开始

前提条件

• Python 3.11+
• uv：Python 包管理器和项目管理工具

安装方法:

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux/macOS

sh -c "$(curl -LsSf https://astral.sh/uv/install.sh)"

安装步骤

1. 克隆项目

git clone git@github.com:Hommy-master/capcut-mate.git
cd capcut-mate

2. 安装依赖

# 安装依赖
uv sync

# windows额外执行
uv pip install -e .[windows]

3. 启动服务器

uv run main.py

4. 访问API文档 启动后访问 http://localhost:30000/docs 查看自动生成的交互式API文档

Docker 部署

快速部署（推荐）

📺 视频教程：CapCut Mate 私有化部署完整教程

git clone https://github.com/Hommy-master/capcut-mate.git
cd capcut-mate
docker-compose pull && docker-compose up -d

部署完成后，访问 API 文档：http://localhost:30000/docs

一键导入扣子插件

1. 打开扣子平台：https://coze.cn/home

   

2. 添加插件

   

3. 导入插件

   

4. 上传当前工程目录下的openapi.yaml文件

   

5. 完成文件上传

   

6. 替换logo完成

   

7. 启用插件

   

API 接口文档

以下是 CapCut Mate API 提供的核心接口，支持完整的视频创作工作流程：

🏗️ 草稿管理

接口	功能	描述	文档链接
create_draft	创建草稿	创建新的剪映草稿项目，设置画布尺寸	📖 查看文档
save_draft	保存草稿	保存当前草稿状态，确保编辑内容持久化	📖 查看文档
get_draft	获取草稿	获取草稿文件列表和详细信息	📖 查看文档

🎥 视频素材

接口	功能	描述	文档链接
add_videos	添加视频	批量添加视频素材，支持裁剪、缩放、特效	📖 查看文档
add_images	添加图片	批量添加图片素材，支持动画和转场效果	📖 查看文档
add_sticker	添加贴纸	添加装饰贴纸，支持位置和大小调整	📖 查看文档

🎵 音频处理

接口	功能	描述	文档链接
add_audios	添加音频	批量添加音频素材，支持音量和淡入淡出	📖 查看文档
get_audio_duration	获取音频时长	获取音频文件的精确时长信息	📖 查看文档

📝 文本字幕

接口	功能	描述	文档链接
add_captions	添加字幕	批量添加字幕，支持关键词高亮和样式设置	📖 查看文档
add_text_style	文本样式	创建富文本样式，支持关键词颜色和字体	📖 查看文档

✨ 特效动画

接口	功能	描述	文档链接
add_effects	添加特效	添加视觉特效，如滤镜、边框、动态效果	📖 查看文档
add_keyframes	关键帧动画	创建位置、缩放、旋转等属性动画	📖 查看文档
add_masks	遮罩效果	添加各种形状遮罩，控制画面可见区域	📖 查看文档

🎨 动画资源

接口	功能	描述	文档链接
get_text_animations	文本动画	获取可用的文本入场、出场、循环动画	📖 查看文档
get_image_animations	图片动画	获取可用的图片动画效果列表	📖 查看文档

🎬 视频生成

接口	功能	描述	文档链接
gen_video	生成视频	提交视频渲染任务，异步处理	📖 查看文档
gen_video_status	查询状态	查询视频生成任务的进度和状态	📖 查看文档

🚀 快速工具

接口	功能	描述	文档链接
easy_create_material	快速创建	一次性添加多种类型素材，简化创建流程	📖 查看文档

🛠️工具类接口

接口	功能	描述	文档链接
get_url	提取URL	从输入内容中提取URL信息	📖 查看文档
search_sticker	搜索贴纸	根据关键词搜索贴纸素材	📖 查看文档
objs_to_str_list	对象转字符串列表	将对象列表转换为字符串列表格式	📖 查看文档
str_list_to_objs	字符串列表转对象	将字符串列表转换为对象列表格式	📖 查看文档
str_to_list	字符串转列表	将字符串转换为列表格式	📖 查看文档
timelines	创建时间线	生成视频编辑所需的时间线配置	📖 查看文档
audio_timelines	音频时间线	根据音频时长计算时间线	📖 查看文档
audio_infos	音频信息	根据URL和时间线生成音频信息	📖 查看文档
imgs_infos	图片信息	根据URL和时间线生成图片信息	📖 查看文档
caption_infos	字幕信息	根据文本和时间线生成字幕信息	📖 查看文档
effect_infos	特信息	根据名称和时间线生成特效信息	📖 查看文档
keyframes_infos	关键帧信息	根据配置生成关键帧信息	📖 查看文档
video_infos	视信息信息	根据URL和时间线生成视频信息	📖 查看文档

API 使用示例

工作流案例

查看完整的真实工作流案例，了解如何将 CapCut Mate 接口与 Coze、n8n 等自动化平台结合使用：

👉 访问工作流案例

创建草稿

curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/create_draft" \
-H "Content-Type: application/json" \
-d '{"width": 1080, "height": 1920}'

添加视频

curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/add_videos" \
-H "Content-Type: application/json" \
-d '{
  "draft_url": "http://localhost:30000/openapi/capcut-mate/v1/get_draft?draft_id=20251126212753cab03392",
  "video_infos": [
    {
      "url": "https://example.com/video.mp4",
      "start": 0,
      "end": 1000000
    }
  ]
}'

API 文档

• 本地访问: http://localhost:30000/docs
• ReDoc 版本: http://localhost:30000/redoc

剪映小助手客户端

剪映小助手客户端提供了桌面端的便捷操作界面，以下是启动方法：

macOS 沙箱权限说明

在 macOS 上运行时，应用可能会请求访问特定文件夹的权限。请按照以下步骤操作：

1. 如果首次运行时出现权限提示，请允许应用访问所需文件夹
2. 如需手动配置，请前往 系统偏好设置 > 安全性与隐私 > 隐私 > 文件夹访问
3. 确保 CapCut Mate 应用已被添加到允许列表中

更多详细信息，请参阅 macOS 沙箱权限配置指南。

1. 安装依赖

# 切换npm镜像源 - 适用于windows
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# 切换yarn镜像源 - 适用于linux 或 mac
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

# 安装依赖
npm install --verbose

2. 启动项目

npm run web:dev
npm start

开源社区问题交流群

• 微信群：

  

商业合作

• 微信：

  

• 邮箱：taohongmin51@gmail.com

---