diff --git a/README.md b/README.md index 4980066..1f9a389 100644 --- a/README.md +++ b/README.md @@ -1,202 +1,78 @@ -# 🎬 CapCutAPI - Open source CapCut API tool. +# Connect AI generates via CapCutAPI [Try it online](https://www.capcutapi.top) -
+\
-![CapCutAPI Logo](https://img.shields.io/badge/CapCutAPI-v1.1.0-blue?style=for-the-badge&logo=video&logoColor=white) +``` +πŸ‘πŸ‘πŸ‘πŸ‘ Celebrating 700 GitHub stars, giving away a 7000-point anonymous cloud rendering coupon: 08B88A2C-1D16-4CE1-982E-E3732F2655F3 +``` -[![GitHub Stars](https://img.shields.io/github/stars/sun-guannan/CapCutAPI?style=for-the-badge&logo=github)](https://github.com/sun-guannan/CapCutAPI/stargazers) -[![License](https://img.shields.io/badge/License-Apache%202.0-green?style=for-the-badge)](LICENSE) -[![Python Version](https://img.shields.io/badge/Python-3.8+-blue?style=for-the-badge&logo=python)](https://python.org) -[![MCP Support](https://img.shields.io/badge/MCP-Supported-orange?style=for-the-badge)](./MCP_Documentation_English.md) +\ -**πŸš€ Open source CapCut API tool with MCP (Model Context Protocol) support** +## Project Overview +**CapCutAPI** is a powerful cloud-based **editing** API that gives you precise control over AI-generated assets, including images, audio, video, and text. +It provides the exact editing capabilities to assemble raw AI outputs, such as adjusting video speed or mirroring an image. This effectively solves the problem of a lack of precise control and difficulty in replicating AI-generated results, allowing you to easily transform creative ideas into polished videos. +All these features are designed to be on par with the functionality of the Jianying software, ensuring you get a familiar and efficient editing experience in the cloud. -**MCP agent** +### Core Advantages -[![AI Cut](https://img.youtube.com/vi/fBqy6WFC78E/hqdefault.jpg)](https://www.youtube.com/watch?v=fBqy6WFC78E) +1. Provides CapCut/Jianying-level editing capabilities through an API. -**Connect AI generated via CapCutAPI** +2. Allows real-time preview of editing results on a webpage, without the need for downloads, greatly facilitating workflow development. -[![Airbnb](https://img.youtube.com/vi/1zmQWt13Dx0/hqdefault.jpg)](https://www.youtube.com/watch?v=1zmQWt13Dx0) +3. Lets you download editing results and import them into CapCut/Jianying for secondary editing. -[![Horse](https://img.youtube.com/vi/IF1RDFGOtEU/hqdefault.jpg)](https://www.youtube.com/watch?v=IF1RDFGOtEU) +4. Enables you to use the API to generate videos from your editing results, achieving a fully cloud-based operation. -[![Song](https://img.youtube.com/vi/rGNLE_slAJ8/hqdefault.jpg)](https://www.youtube.com/watch?v=rGNLE_slAJ8) - - -
+## Demos ---- +\
-## 🎯 Project Overview +**MCP, create your own editing Agent** -**CapCutAPI** is a powerful enterprise-grade video editing automation platform built with Python, providing complete CapCut video editing capabilities. Through dual interfaces of HTTP API and MCP protocol, it enables seamless integration with AI assistants and automation tools. +[](https://www.youtube.com/watch?v=fBqy6WFC78E) -### πŸ† Core Advantages +**Combine AI-generated images and videos using tools** - - - - - - - - - -
+[](https://www.youtube.com/watch?v=1zmQWt13Dx0) -**🎬 Professional Video Editing** -- Complete CapCut functionality support -- Multi-track timeline editing -- Advanced effects and transitions -- Keyframe animation system +[](https://www.youtube.com/watch?v=IF1RDFGOtEU) - +[](https://www.youtube.com/watch?v=rGNLE_slAJ8) -**πŸ€– AI Smart Integration** -- Native MCP protocol support -- Seamless AI assistant integration -- Automated workflow processes -- Batch processing capabilities +\ -
+## Key Features -**πŸ”Œ Dual API Interfaces** -- RESTful HTTP API -- Model Context Protocol -- Real-time processing response -- Enterprise-grade stability +| Feature Module | API | MCP Protocol | Description | +|---------|----------|----------|------| +| **Draft Management** | βœ… | βœ… | Create and save Jianying/CapCut draft files | +| **Video Processing** | βœ… | βœ… | Import, clip, transition, and apply effects to multiple video formats | +| **Audio Editing** | βœ… | βœ… | Audio tracks, volume control, sound effects processing | +| **Image Processing** | βœ… | βœ… | Image import, animation, masks, filters | +| **Text Editing** | βœ… | βœ… | Multi-style text, shadows, backgrounds, animations | +| **Subtitle System** | βœ… | βœ… | SRT subtitle import, style settings, time synchronization | +| **Effects Engine** | βœ… | βœ… | Visual effects, filters, transition animations | +| **Sticker System** | βœ… | βœ… | Sticker assets, position control, animation effects | +| **Keyframes** | βœ… | βœ… | Property animation, timeline control, easing functions | +| **Media Analysis** | βœ… | βœ… | Get video duration, detect format | - +## Quick Start -**🌍 Cross-platform Compatibility** -- CapCut International support -- JianYing China support -- Windows/macOS compatible -- Cloud deployment ready +### 1\. System Requirements -
+ - Python 3.10+ + - Jianying or CapCut International version + - FFmpeg ---- - -## πŸŽ₯ Product Showcase - -
- -### 🐎 AI Generated Video Cases - -[![Horse Video](https://img.youtube.com/vi/IF1RDFGOtEU/hqdefault.jpg)](https://www.youtube.com/watch?v=IF1RDFGOtEU) - -### 🎡 Music Video Production - -[![Song Video](https://img.youtube.com/vi/rGNLE_slAJ8/hqdefault.jpg)](https://www.youtube.com/watch?v=rGNLE_slAJ8) - -*AI-driven video generation powered by CapCutAPI* - -
- ---- - -## πŸš€ Core Features - -### πŸ“‹ Feature Matrix - -| Feature Module | HTTP API | MCP Protocol | Description | -|---------------|----------|--------------|-------------| -| 🎬 **Draft Management** | βœ… | βœ… | Create, read, modify, save CapCut draft files | -| πŸŽ₯ **Video Processing** | βœ… | βœ… | Multi-format video import, editing, transitions, effects | -| πŸ”Š **Audio Editing** | βœ… | βœ… | Audio tracks, volume control, audio effects | -| πŸ–ΌοΈ **Image Processing** | βœ… | βœ… | Image import, animations, masks, filters | -| πŸ“ **Text Editing** | βœ… | βœ… | Multi-style text, shadows, backgrounds, animations | -| πŸ“„ **Subtitle System** | βœ… | βœ… | SRT subtitle import, styling, time sync | -| ✨ **Effects Engine** | βœ… | βœ… | Visual effects, filters, transition animations | -| 🎭 **Sticker System** | βœ… | βœ… | Sticker assets, position control, animation effects | -| 🎯 **Keyframes** | βœ… | βœ… | Property animations, timeline control, easing functions | -| πŸ“Š **Media Analysis** | βœ… | βœ… | Video duration detection, format analysis | - -### πŸ› οΈ API Interface Overview - -
-πŸ“‘ HTTP API Endpoints (9 endpoints) - -🎬 Draft Management -β”œβ”€β”€ POST /create_draft # Create new draft -└── POST /save_draft # Save draft file - -πŸŽ₯ Media Assets -β”œβ”€β”€ POST /add_video # Add video material -β”œβ”€β”€ POST /add_audio # Add audio material -└── POST /add_image # Add image material - -πŸ“ Text Content -β”œβ”€β”€ POST /add_text # Add text elements -└── POST /add_subtitle # Add subtitle files - -✨ Effect Enhancement -β”œβ”€β”€ POST /add_effect # Add visual effects -└── POST /add_sticker # Add sticker elements - - -
- -
-πŸ”§ MCP Tool Set (11 tools) - -🎬 Project Management -β”œβ”€β”€ create_draft # Create video project -└── save_draft # Save project file - -πŸŽ₯ Media Editing -β”œβ”€β”€ add_video # Video track + transition effects -β”œβ”€β”€ add_audio # Audio track + volume control -└── add_image # Image assets + animation effects - -πŸ“ Text System -β”œβ”€β”€ add_text # Multi-style text + shadow background -└── add_subtitle # SRT subtitles + styling - -✨ Advanced Features -β”œβ”€β”€ add_effect # Visual effects engine -β”œβ”€β”€ add_sticker # Sticker animation system -β”œβ”€β”€ add_video_keyframe # Keyframe animations -└── get_video_duration # Media information retrieval - -
- ---- - -## πŸ› οΈ Quick Start - -### πŸ“‹ System Requirements - - - - - - - - - - - - - - - - - - -
🐍 Python EnvironmentPython 3.8.20+ (Recommended 3.10+)
🎬 CapCut ApplicationCapCut International or JianYing China
🎡 FFmpegFor media file processing and analysis
πŸ’Ύ Storage SpaceAt least 2GB available space
- -### ⚑ One-Click Installation +### 2\. Installation and Deployment ```bash # 1. Clone the project git clone https://github.com/sun-guannan/CapCutAPI.git cd CapCutAPI -# 2. Create virtual environment (recommended) +# 2. Create a virtual environment (recommended) python -m venv venv-capcut source venv-capcut/bin/activate # Linux/macOS # or venv-capcut\Scripts\activate # Windows @@ -205,47 +81,26 @@ source venv-capcut/bin/activate # Linux/macOS pip install -r requirements.txt # HTTP API basic dependencies pip install -r requirements-mcp.txt # MCP protocol support (optional) -# 4. Configuration +# 4. Configuration file cp config.json.example config.json # Edit config.json as needed ``` -### πŸš€ Start Services - - - - - - -
- -**🌐 HTTP API Server** +### 3\. Start the service ```bash -python capcut_server.py +python capcut_server.py # Start the HTTP API server, default port: 9001 + +python mcp_server.py # Start the MCP protocol service, supports stdio communication ``` -*Default port: 9001* +## MCP Integration Guide - +[MCP Documentation in Chinese](https://www.google.com/search?q=./MCP_%E6%96%87%E6%A1%A3_%E4%B8%AD%E6%96%87.md) β€’ [MCP English Guide](https://www.google.com/search?q=./MCP_Documentation_English.md) -**πŸ”§ MCP Protocol Server** +### 1\. Client Configuration -```bash -python mcp_server.py -``` - -*Supports stdio communication* - -
- ---- - -## πŸ”§ MCP Integration Guide - -### πŸ“± Client Configuration - -Create or update `mcp_config.json` configuration file: +Create or update the `mcp_config.json` configuration file: ```json { @@ -263,7 +118,7 @@ Create or update `mcp_config.json` configuration file: } ``` -### πŸ§ͺ Connection Testing +### 2\. Connection Test ```bash # Test MCP connection @@ -271,32 +126,15 @@ python test_mcp_client.py # Expected output βœ… MCP server started successfully -βœ… Retrieved 11 available tools +βœ… Got 11 available tools βœ… Draft creation test passed ``` -### 🎯 MCP Featured Functions +## Usage Examples -
+### 1\. API Example -| Feature | Description | Example | -|---------|-------------|----------| -| 🎨 **Advanced Text Styling** | Multi-color, shadow, background effects | `shadow_enabled: true` | -| 🎬 **Keyframe Animation** | Position, scale, opacity animations | `property_types: ["scale_x", "alpha"]` | -| πŸ”Š **Audio Precision Control** | Volume, speed, audio effects | `volume: 0.8, speed: 1.2` | -| πŸ“± **Multi-format Support** | Various video dimensions and formats | `width: 1080, height: 1920` | -| ⚑ **Real-time Processing** | Instant draft updates and previews | Millisecond response time | - -
- ---- - -## πŸ’‘ Usage Examples - -### 🌐 HTTP API Examples - -
-πŸ“Ή Adding Video Material +Add video material ```python import requests @@ -305,9 +143,7 @@ import requests response = requests.post("http://localhost:9001/add_video", json={ "video_url": "https://example.com/background.mp4", "start": 0, - "end": 10, - "width": 1080, - "height": 1920, + "end": 10 "volume": 0.8, "transition": "fade_in" }) @@ -315,20 +151,17 @@ response = requests.post("http://localhost:9001/add_video", json={ print(f"Video addition result: {response.json()}") ``` -
- -
-πŸ“ Creating Styled Text +Create stylized text ```python import requests # Add title text response = requests.post("http://localhost:9001/add_text", json={ - "text": "🎬 Welcome to CapCutAPI", + "text": "Welcome to CapCutAPI", "start": 0, "end": 5, - "font": "Arial", + "font": "Source Han Sans", "font_color": "#FFD700", "font_size": 48, "shadow_enabled": True, @@ -338,15 +171,14 @@ response = requests.post("http://localhost:9001/add_text", json={ print(f"Text addition result: {response.json()}") ``` -
+More examples can be found in the `example.py` file. -### πŸ”§ MCP Protocol Examples +### 2\. MCP Protocol Example -
-🎯 Complete Workflow +Complete workflow ```python -# 1. Create new project +# 1. Create a new project draft = mcp_client.call_tool("create_draft", { "width": 1080, "height": 1920 @@ -382,162 +214,71 @@ mcp_client.call_tool("add_video_keyframe", { "values": ["1.0", "1.2", "0.8"] }) -# 5. Save project +# 5. Save the project result = mcp_client.call_tool("save_draft", { "draft_id": draft_id }) + print(f"Project saved: {result['result']['draft_url']}") ``` -
+Advanced text effects -### Testing with REST Client - -You can use the `rest_client_test.http` file with REST Client IDE plugins for HTTP testing. - -### Draft Management - -Calling `save_draft` generates a folder starting with `dfd_` in the server's current directory. Copy this folder to your CapCut draft directory to access the generated draft in CapCut. - ---- - -## πŸ“š Documentation Center - -
- -| πŸ“– Document Type | 🌍 Language | πŸ“„ Link | πŸ“ Description | -|-----------------|-------------|---------|----------------| -| **MCP Complete Guide** | πŸ‡ΊπŸ‡Έ English | [MCP Documentation](./MCP_Documentation_English.md) | Complete MCP server usage guide | -| **MCP User Manual** | πŸ‡¨πŸ‡³ Chinese | [MCP δΈ­ζ–‡ζ–‡ζ‘£](./MCP_ζ–‡ζ‘£_δΈ­ζ–‡.md) | Detailed Chinese usage instructions | -| **API Reference** | πŸ‡ΊπŸ‡Έ English | [example.py](./example.py) | Code examples and best practices | -| **REST Testing** | 🌐 Universal | [rest_client_test.http](./rest_client_test.http) | HTTP interface test cases | - -
- ---- - -## 🌟 Enterprise Features - -### πŸ”’ Security - -- **πŸ›‘οΈ Input Validation**: Strict parameter validation and type checking -- **πŸ” Error Handling**: Comprehensive exception catching and error reporting -- **πŸ“Š Logging**: Detailed operation logs and debug information -- **🚫 Resource Limits**: Memory and processing time limit protection - -### ⚑ Performance Optimization - -- **πŸš€ Async Processing**: Non-blocking concurrent operation support -- **πŸ’Ύ Memory Management**: Smart resource recycling and caching mechanisms -- **πŸ“ˆ Batch Processing**: Efficient batch operation interfaces -- **⏱️ Response Time**: Millisecond-level API response speed - -### πŸ”§ Scalability - -- **πŸ”Œ Plugin Architecture**: Modular functionality extension support -- **🌐 Multi-protocol**: HTTP REST and MCP dual protocol support -- **☁️ Cloud Deployment**: Containerization and microservice architecture ready -- **πŸ“Š Monitoring Integration**: Complete performance monitoring and metrics collection - ---- - -## 🀝 Community & Support - -### πŸ’¬ Get Help - -
- -| πŸ“ž Support Channel | πŸ”— Link | πŸ“ Description | -|-------------------|---------|----------------| -| **πŸ› Bug Reports** | [GitHub Issues](https://github.com/sun-guannan/CapCutAPI/issues) | Bug reports and feature requests | -| **πŸ’‘ Feature Suggestions** | [Discussions](https://github.com/sun-guannan/CapCutAPI/discussions) | Community discussions and suggestions | -| **πŸ“– Documentation Feedback** | [Documentation Issues](https://github.com/sun-guannan/CapCutAPI/issues?q=label%3Adocumentation) | Documentation improvement suggestions | -| **πŸ”§ Technical Support** | [Stack Overflow](https://stackoverflow.com/questions/tagged/capcut-api) | Technical Q&A | - -
- -### 🎯 Contributing Guide - -We welcome all forms of contributions! - -```bash -# 1. Fork the project -git clone https://github.com/your-username/CapCutAPI.git - -# 2. Create feature branch -git checkout -b feature/amazing-feature - -# 3. Commit changes -git commit -m 'Add amazing feature' - -# 4. Push branch -git push origin feature/amazing-feature - -# 5. Create Pull Request +```python +# Multi-style colored text +mcp_client.call_tool("add_text", { + "text": "Colored text effect demonstration", + "draft_id": draft_id, + "start": 2, + "end": 8, + "font_size": 42, + "shadow_enabled": True, + "shadow_color": "#FFFFFF", + "background_alpha": 0.8, + "background_round_radius": 20, + "text_styles": [ + {"start": 0, "end": 2, "font_color": "#FF6B6B"}, + {"start": 2, "end": 4, "font_color": "#4ECDC4"}, + {"start": 4, "end": 6, "font_color": "#45B7D1"} + ] +}) ``` ---- +### 3\. Downloading Drafts -## πŸ“ˆ Project Statistics +Calling `save_draft` will generate a folder starting with `dfd_` in the current directory of `capcut_server.py`. Copy this to the CapCut/Jianying drafts directory to see the generated draft in the application. -
+## Community & Support -### ⭐ Star History +We welcome contributions of all forms\! Our iteration rules are: -[![Star History Chart](https://api.star-history.com/svg?repos=sun-guannan/CapCutAPI&type=Date)](https://www.star-history.com/#sun-guannan/CapCutAPI&Date) + - No direct PRs to main + - PRs can be submitted to the dev branch + - Merges from dev to main and releases will happen every Monday -### πŸ“Š Project Metrics +## Join our group -![GitHub repo size](https://img.shields.io/github/repo-size/sun-guannan/CapCutAPI?style=flat-square) -![GitHub code size](https://img.shields.io/github/languages/code-size/sun-guannan/CapCutAPI?style=flat-square) -![GitHub issues](https://img.shields.io/github/issues/sun-guannan/CapCutAPI?style=flat-square) -![GitHub pull requests](https://img.shields.io/github/issues-pr/sun-guannan/CapCutAPI?style=flat-square) -![GitHub last commit](https://img.shields.io/github/last-commit/sun-guannan/CapCutAPI?style=flat-square) + - Feedback on issues + - Feature suggestions + - Latest news -
+### 🀝 Collaboration Opportunities ---- + - **Overseas Video Production**: Want to use this API for batch production of overseas videos? I offer free consulting services to help you use this API. In return, I'll ask for the production workflow template to be **open-sourced** in the `template` directory of this project. -## πŸ“„ License + - **Join us**: Our goal is to provide a stable and reliable video editing tool that integrates well with AI-generated images, videos, and audio. If you are interested, you can start by translating the Chinese content in the project into English\! Submit a PR and I'll see it. For more in-depth involvement, the code for the MCP Editing Agent, web-based editing client, and cloud rendering modules has not been open-sourced yet. -
+ - **Contact**: -This project is open source under the Apache 2.0 License. See [LICENSE](LICENSE) file for details. + - WeChat: sguann + - Douyin: ε‰ͺζ˜ θ‰η¨ΏεŠ©ζ‰‹ -Apache License 2.0 +## πŸ“ˆ Star History -Copyright (c) 2025 CapCutAPI Contributors +\
-Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at +[](https://www.star-history.com/#sun-guannan/CapCutAPI&Date) - http://www.apache.org/licenses/LICENSE-2.0 +\ -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - -
- ---- - -
- -## πŸŽ‰ Get Started Now - -**Experience the power of CapCutAPI today!** - -[![Get Started](https://img.shields.io/badge/πŸš€_Get_Started-blue?style=for-the-badge&logo=rocket)](https://www.capcutapi.top) -[![Download](https://img.shields.io/badge/πŸ“₯_Download-green?style=for-the-badge&logo=download)](https://github.com/sun-guannan/CapCutAPI/archive/refs/heads/main.zip) -[![Documentation](https://img.shields.io/badge/πŸ“–_Documentation-orange?style=for-the-badge&logo=book)](./MCP_Documentation_English.md) - ---- - -**πŸ†• New Feature**: Now with MCP protocol support for seamless AI assistant integration! Try the MCP server for advanced video editing automation. - -*Made with ❀️ by the CapCutAPI Community* - -
+*Made with ❀️ by the CapCutAPI Community* \ No newline at end of file