capcut-mate README

The project's README from github.com/Hommy-master/capcut-mate. As one markdown file: README.md.

CapCut Mate API

🌐 Language Switch

中文版 | English

Project Introduction

CapCut Mate API is a completely open-source and free Jianying draft automation assistant built on FastAPI, supporting independent deployment. This project focuses on empowering large models with basic video editing capabilities, providing out-of-the-box video editing Skills, and has fully automated the entire Jianying core functionality workflow. It can directly connect with large models to achieve diverse intelligent video editing, enabling ordinary users to quickly create professional and advanced video works.

Flexible project usage: Can be independently deployed, or combined with Coze or n8n to build automated workflows, and can also connect with Jianying to achieve cloud rendering, directly generating final videos from drafts.

Project Resources

⭐ If you find this project helpful, please give us a Star! Your support is the greatest motivation for me to continuously maintain and improve the project 😊

Features

Tech Stack

Quick Start

Prerequisites

Installation:

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

Installation Steps

  1. Clone the project
git clone [email protected]:Hommy-master/capcut-mate.git
cd capcut-mate
  1. Install dependencies
# Install dependencies
uv sync

# Additional execution for Windows
uv pip install -e .[windows]
  1. Start the server
uv run main.py
  1. Access API documentation

Docker Deployment

📺 Video Tutorial: CapCut Mate Private Deployment Complete Tutorial

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

After deployment, access the API documentation at: http://localhost:30000/docs

One-Click Import Coze Plugin

  1. Open Coze platform: https://coze.cn/home

    Step 1

  2. Add Plugin

    Step 2

  3. Import Plugin

    Step 3

  4. Upload the openapi.yaml file in the current project directory

    Step 4

  5. Complete file upload

    Step 5

  6. Complete logo replacement

    Step 6

  7. Enable Plugin

    Step 7

API Documentation

The following are the core interfaces provided by CapCut Mate API, supporting a complete video creation workflow:

🏗️ Draft Management

Interface Function Description Documentation Link
create_draft Create Draft Create a new Jianying draft project, set canvas size 📖 View Documentation
save_draft Save Draft Save current draft state, ensure edit content persistence 📖 View Documentation
get_draft Get Draft Get draft file list and detailed information 📖 View Documentation

🎥 Video Materials

Interface Function Description Documentation Link
add_videos Add Videos Batch add video materials, support cropping, scaling, effects 📖 View Documentation
add_images Add Images Batch add image materials, support animations and transition effects 📖 View Documentation
add_sticker Add Stickers Add decorative stickers, support position and size adjustment 📖 View Documentation

🎵 Audio Processing

Interface Function Description Documentation Link
add_audios Add Audios Batch add audio materials, support volume and fade in/out 📖 View Documentation
get_audio_duration Get Audio Duration Get precise duration information of audio files 📖 View Documentation

📝 Text Subtitles

Interface Function Description Documentation Link
add_captions Add Captions Batch add captions, support keyword highlighting and style settings 📖 View Documentation
add_text_style Text Style Create rich text styles, support keyword colors and fonts 📖 View Documentation

✨ Effects & Animations

Interface Function Description Documentation Link
add_effects Add Effects Add visual effects, such as filters, borders, dynamic effects 📖 View Documentation
add_keyframes Keyframe Animation Create property animations for position, scale, rotation, etc. 📖 View Documentation
add_masks Mask Effects Add various shape masks, control visible areas of the screen 📖 View Documentation
add_mask_keyframes Mask Keyframes Animate mask position, size, feather, and rotation 📖 View Documentation
add_beauty Portrait Beautification Beauty, face shape, makeup and body sliders (smoothing, whitening, slim face, small head, ...) 📖 View Documentation

🎨 Animation Resources

Interface Function Description Documentation Link
get_text_animations Text Animations Get available text entrance, exit, and loop animations 📖 View Documentation
get_text_effects Text Effects Get available decorative text flower effects list 📖 View Documentation
get_image_animations Image Animations Get available image animation effects list 📖 View Documentation

🎬 Video Generation

Interface Function Description Documentation Link
gen_video Generate Video Submit video rendering task, asynchronous processing 📖 View Documentation
gen_video_status Query Status Query the progress and status of video generation tasks 📖 View Documentation

🚀 Quick Tools

Interface Function Description Documentation Link
easy_create_material Quick Creation Add multiple types of materials at once, simplify creation process 📖 View Documentation

📤 Material Upload

Interface Function Description Documentation Link
upload_file Upload File Server-relayed upload to object storage (max 500MB, 0.0005 CNY/MB), returns a usable signed URL 📖 View Documentation

🛠️ Utility Tools

Interface Function Description Documentation Link
get_url Extract URL Extract URL information from input content 📖 View Documentation
search_sticker Search Sticker Search sticker materials by keyword 📖 View Documentation
objs_to_str_list Objects to String List Convert object list to string list format 📖 View Documentation
str_list_to_objs String List to Objects Convert string list to object list format 📖 View Documentation
str_to_list String to List Convert string to list format 📖 View Documentation
timelines Create Timelines Generate timeline configurations for video editing 📖 View Documentation
audio_timelines Audio Timelines Calculate timelines based on audio durations 📖 View Documentation
audio_infos Audio Information Generate audio information from URLs and timelines 📖 View Documentation
imgs_infos Image Information Generate image information from URLs and timelines 📖 View Documentation
caption_infos Caption Information Generate caption information from text and timelines 📖 View Documentation
effect_infos Effect Information Generate effect information from names and timelines 📖 View Documentation
keyframes_infos Keyframe Information Generate keyframe information from configurations 📖 View Documentation
video_infos Video Information Generate video information from URLs and timelines 📖 View Documentation

API Usage Examples

Workflow Examples

Explore real-world workflow examples to learn how to integrate CapCut Mate with automation platforms like Coze and n8n:

👉 View Workflow Examples

Create Draft

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

Add Videos

video_infos is a JSON string (not a nested JSON array). Each item must include video_url, start, and end (microseconds on the timeline). See add_videos for optional fields.

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": "[{\"video_url\": \"https://example.com/video.mp4\", \"start\": 0, \"end\": 1000000}]"
}'

API Documentation

Jianying Assistant Client

The Jianying Assistant client provides a convenient desktop interface. Here are the startup methods:

macOS Sandbox Permissions Guide

When running on macOS, the application may request access permissions for specific folders. Please follow these steps:

  1. If permission prompts appear during the first run, allow the application to access the required folders
  2. For manual configuration, go to System Preferences > Security & Privacy > Privacy > Folder Access
  3. Ensure the CapCut Mate application is added to the allowed list

For more details, please refer to the macOS Sandbox Permissions Configuration Guide.

  1. Install Dependencies
# Switch npm mirror source - for Windows
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# Switch yarn mirror source - for Linux or macOS
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

# Install dependencies
npm install --verbose
  1. Start the Project
npm run web:dev
npm start

Contact

Type Method Description
📱 WeChat Group
Jianying Assistant
 Open Source Community Discussion Group
💬 WeChat
WeChat QR code
 Business Cooperation
📧 Email [email protected] Technical Support

capcut-mate (Hommy-master/capcut-mate)

Searching Database…

2K ·GitHub
Capcut-mate
这是什么？CapCut Mate API 是一个开源的 FastAPI 服务，可自动化 CapCut/剪映的视频剪辑草稿，让你能以编程方式或通过 LLM 创建草稿、添加素材并渲染最终视频。
这是托管服务，还是我自己运行的东西？它是你自己部署的自托管后端（通过 Python/uv 或 Docker），之后可以接入 Coze 或 n8n 工作流，或连接剪映进行云端渲染。
怎么把它跑起来？克隆仓库，用 uv 安装依赖，然后用 uvicorn 启动服务器；服务运行起来后 API 文档会自动可用。另外还提供基于 Docker 的快速部署选项。
运行之前我需要装好什么？你需要 Python 3.11+ 和 uv 包管理器；如果不想在本地配置 Python，也可以改用 Docker。
文件上传或渲染要花钱吗？中转文件上传到对象存储的上限为单文件 500MB，按每 MB 0.0005 元计费，因此尽管代码本身免费，大规模使用内置的上传/渲染管线并不是免费的。
我能在任意操作系统上运行这个服务器吗？可以，快速上手步骤同时覆盖 Windows 和 Linux/macOS，还有 Docker 部署路径。
我怎么把它接入 Coze？你打开 Coze 平台，添加插件并导入项目的 openapi.yaml 文件；替换 logo 并启用之后，CapCut Mate 的端点就可以在 Coze 工作流中使用了。
用这个 API 实际能做出什么？从草稿到成片的完整流水线：创建草稿、批量添加视频/音频/图片/贴纸素材、带关键词高亮的字幕、关键帧动画、蒙版、美颜滤镜，最后提交异步云端渲染任务。
剪映小助手桌面客户端是干什么的？它是一个配套桌面应用，在 API 之上提供图形界面；在 macOS 上需要通过系统偏好设置授予文件夹访问权限，应用才能处理剪映的本地文件。
除了 Coze，它也能连接 n8n 吗？可以，项目提供了工作流示例，展示如何把 CapCut Mate 的 REST 端点与 Coze 和 n8n 这两个自动化平台集成。
What are similar projects?MoneyPrinterTurbo, vlo, nocobase, dance-video-to-prompt, autoclip, n8n-workflows, fastapi_mcp, LangBot
Which topics is it in?coze, asgi, uv, pydantic, n8n, opensource, video-editing, openapi, audio-processing, fastapi, video-processing, workflow-automation
Creator
Hommy-master
Size
61.2 MB
Stars
2K
Updated
CommitOct 18Releasev8.1.8Oct 18
Age
1y
Commits · 90 Days