VectCut API

https://github.com/sun-guannan/capcutapi
Admin
VectCut is a toA (toAgent) video editing tool. It provides a rich set of cloud-based editing APIs...
Tokens:13,672
Snippets:154
Trust Score:6.6
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Clone and Install VectCutAPI

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README_EN.md

Clone the VectCutAPI project and install its dependencies. Configure the API by copying and editing the example configuration file. Start the HTTP API server.

```bash
git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI

pip install -r requirements.txt      # HTTP API basic dependencies
pip install -r requirements-mcp.txt  # MCP protocol support (optional)

cp config.json.example config.json
# Edit config.json as needed

python capcut_server.py  # HTTP API server (default port: 9001)
```

--------------------------------

### Install and Configure VectCutAPI

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README.md

Steps to clone the VectCutAPI project, install dependencies, and configure the server. Ensure you have Python 3.10+ and optionally FFmpeg installed.

```bash
# 克隆 VectCutAPI 项目
git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI

# 安装依赖
pip install -r requirements.txt      # HTTP API 基础依赖
pip install -r requirements-mcp.txt  # MCP 协议支持 (可选)

# 配置文件
cp config.json.example config.json
# 根据需要编辑 config.json

# 启动服务
python capcut_server.py  # HTTP API 服务器 (默认端口: 9001)
```

--------------------------------

### Run Installation Test

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Command to execute the Python test script for verifying the installation.

```bash
python test_installation.py
```

--------------------------------

### Clone Project and Install Dependencies

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Clone the project repository and install necessary Python dependencies. This includes setting up a virtual environment and installing packages for both HTTP API and optional MCP protocol support.

```bash
# 1. Clone the project
git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI

# 2. Create a virtual environment (recommended)
python -m venv venv-capcut
source venv-capcut/bin/activate  # Linux/macOS
# or venv-capcut\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt      # HTTP API basic dependencies
pip install -r requirements-mcp.txt  # MCP protocol support (optional)

# 4. Configuration file
cp config.json.example config.json
# Edit config.json as needed
```

--------------------------------

### Test Installation Script

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

A Python script to test the VectCutAPI connection, draft creation, and saving.

```python
from skill.scripts.vectcut_client import VectCutClient

def test_installation():
    """测试安装是否成功"""
    print("测试 VectCutAPI 连接...")

    try:
        # 创建客户端
        client = VectCutClient("http://localhost:9001")

        # 测试创建草稿
        draft = client.create_draft(width=1080, height=1920)
        print(f"✓ 草稿创建成功: {draft.draft_id}")

        # 测试保存草稿
        result = client.save_draft(draft.draft_id)
        print(f"✓ 草稿保存成功: {result.draft_url}")

        print("\n✅ 安装验证成功！")
        return True

    except Exception as e:
        print(f"\n❌ 安装验证失败: {e}")
        return False

if __name__ == "__main__":
    test_installation()
```

--------------------------------

### Add Video Method

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Example of an operation-type method for adding a video track to a draft. It takes draft ID, video URL, and start time, returning a boolean indicating success.

```python
def add_video(self,
             draft_id: str,
             video_url: str,
             start: float = 0,
             # ... 更多参数
             **kwargs) -> bool:
    """
    添加视频轨道

    Args:
        draft_id: 草稿 ID
        video_url: 视频 URL
        ...

    Returns:
        bool: 操作是否成功
    """
```

--------------------------------

### Verify Skill Files (Windows)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Lists the contents of the skill directory on Windows to verify installation.

```cmd
# Windows
dir %USERPROFILE%\.claude\skills\public\vectcut-api
```

--------------------------------

### Get Media Duration Method

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Example of a query-type method to retrieve the duration of a media file. It takes a media URL and returns the duration in seconds or None if retrieval fails.

```python
def get_duration(self, media_url: str) -> Optional[float]:
    """
    获取媒体文件时长

    Args:
        media_url: 媒体 URL

    Returns:
        Optional[float]: 时长(秒)，失败返回 None
    """
```

--------------------------------

### Install MCP Dependencies

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Installs necessary dependencies for the MCP client using pip. Ensure you are in a Python virtual environment.

```bash
# Create virtual environment
python3.10 -m venv venv-mcp
source venv-mcp/bin/activate  # macOS/Linux
# or venv-mcp\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements-mcp.txt
```

--------------------------------

### Verify Vectcut-skill Installation

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README_EN.md

Verify the installation by interacting with Claude Code and requesting a video draft. Claude should automatically load the vectcut-api skill.

```plaintext
I need to create a 1080x1920 video draft
```

--------------------------------

### Python Client: Basic Usage

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

A comprehensive example of using the VectCutClient to create a draft, add a video with transitions, add text with styling, and save the draft.

```APIDOC
## Python Client Usage

### Basic Usage

```python
from skill.scripts.vectcut_client import VectCutClient, Resolution, Transition

# Create client
with VectCutClient("http://localhost:9001") as client:

    # Create draft
    draft = client.create_draft(
        width=Resolution.VERTICAL.value[0],
        height=Resolution.VERTICAL.value[1]
    )

    # Add video
    client.add_video(
        draft_id=draft.draft_id,
        video_url="https://example.com/video.mp4",
        volume=0.6,
        transition=Transition.FADE_IN.value
    )

    # Add text
    client.add_text(
        draft_id=draft.draft_id,
        text="Title Text",
        start=0,
        end=5,
        font_size=56,
        font_color="#FFD700",
        shadow_enabled=True
    )

    # Save draft
    result = client.save_draft(draft.draft_id)
    print(f"Draft saved: {result.draft_url}")
```
```

--------------------------------

### Verify Skill Files (Linux/macOS)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Lists the contents of the skill directory on Linux or macOS to verify installation.

```bash
# Linux/macOS
ls -la ~/.claude/skills/public/vectcut-api
```

--------------------------------

### Full Python Client Usage for Video Creation

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Comprehensive example of using VectCutClient to create a draft, add a video with a fade-in transition, and add text with specific styling and shadow. This demonstrates advanced client capabilities.

```python
from skill.scripts.vectcut_client import VectCutClient, Resolution, Transition

# Create client
with VectCutClient("http://localhost:9001") as client:

    # Create draft
    draft = client.create_draft(
        width=Resolution.VERTICAL.value[0],
        height=Resolution.VERTICAL.value[1]
    )

    # Add video
    client.add_video(
        draft_id=draft.draft_id,
        video_url="https://example.com/video.mp4",
        volume=0.6,
        transition=Transition.FADE_IN.value
    )

    # Add text
    client.add_text(
        draft_id=draft.draft_id,
        text="Title Text",
        start=0,
        end=5,
        font_size=56,
        font_color="#FFD700",
        shadow_enabled=True
    )

    # Save draft
    result = client.save_draft(draft.draft_id)
    print(f"Draft saved: {result.draft_url}")
```

--------------------------------

### Create Draft Method

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Example of a creation-type method for creating a new draft with specified dimensions. It returns DraftInfo and raises an exception on failure.

```python
def create_draft(self, width: int = 1080, height: int = 1920) -> DraftInfo:
    """
    创建新草稿

    Args:
        width: 视频宽度
        height: 视频高度

    Returns:
        DraftInfo: 草稿信息对象

    Raises:
        Exception: 创建失败时抛出异常
    """
```

--------------------------------

### Install VectCut Skill for Claude Code

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README.md

Instructions for copying the skill files into the Claude Code skills directory for both Windows and Linux/macOS.

```bash
# 克隆本项目
git clone https://github.com/HUNSETO1413/vectcut-skill.git
cd vectcut-skill

# 复制 skill 文件到 Claude Code 技能目录
# Windows:
copy skill\* %USERPROFILE%\.claude\skills\public\vectcut-api\ /E

# Linux/macOS:
cp -r skill/* ~/.claude/skills/public/vectcut-api/
```

--------------------------------

### Test MCP Connection

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Run the `test_mcp_client.py` script to test the MCP connection. This verifies that the MCP server starts successfully, detects available tools, and passes basic tests like draft creation.

```bash
# Test MCP connection
python test_mcp_client.py

# Expected output
✅ MCP server started successfully
✅ Got 11 available tools
✅ Draft creation test passed
```

--------------------------------

### Start CapCut API Service

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Launch the CapCut API server. The HTTP API server defaults to port 9001, and the MCP protocol service supports stdio communication.

```bash
python capcut_server.py # Start the HTTP API server, default port: 9001

python mcp_server.py # Start the MCP protocol service, supports stdio communication
```

--------------------------------

### Python Client Error Handling

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Example of implementing try-except blocks to handle potential errors during client operations, such as creating a draft or adding videos. Ensures graceful failure and resource cleanup.

```python
from skill.scripts.vectcut_client import VectCutClient

try:
    client = VectCutClient("http://localhost:9001")
    draft = client.create_draft()

    if client.add_video(draft.draft_id, "video.mp4"):
        print("Video added successfully")
    else:
        print("Video addition failed")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    client.close()
```

--------------------------------

### Python Client: Error Handling

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Provides an example of implementing try-except blocks to gracefully handle potential errors during API operations and ensure client cleanup.

```APIDOC
### Error Handling

```python
from skill.scripts.vectcut_client import VectCutClient

try:
    client = VectCutClient("http://localhost:9001")
    draft = client.create_draft()

    if client.add_video(draft.draft_id, "video.mp4"):
        print("Video added successfully")
    else:
        print("Failed to add video")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    client.close()
```
```

--------------------------------

### API Response Format

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Example of a successful API response, indicating the structure for draft creation and other operations. Note the 'success' flag and 'result' object.

```json
{
  "success": true,
  "result": {
    "draft_id": "dfd_cat_xxx",
    "draft_url": "https://..."
  },
  "features_used": {
    "shadow": false,
    "background": false,
    "multi_style": false
  }
}
```

--------------------------------

### Add Background Video via API

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Use the `requests` library to send a POST request to the `/add_video` endpoint to add background video material. Specify the video URL, start and end times, volume, and transition effect.

```python
import requests

# Add background video
response = requests.post("http://localhost:9001/add_video", json={
    "video_url": "https://example.com/background.mp4",
    "start": 0,
    "end": 10,
    "volume": 0.8,
    "transition": "fade_in"
})

print(f"Video addition result: {response.json()}")
```

--------------------------------

### Basic Video Creation with VectCutClient

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README.md

Demonstrates creating a video draft, adding a background video with custom volume, and adding text with styling using the Python client.

```python
from skill.scripts.vectcut_client import VectCutClient

# 创建客户端
client = VectCutClient("http://localhost:9001")

# 创建草稿
draft = client.create_draft(width=1080, height=1920)

# 添加背景视频
client.add_video(
    draft.draft_id,
    "https://example.com/background.mp4",
    volume=0.6
)

# 添加标题文字
client.add_text(
    draft.draft_id,
    "欢迎使用 VectCutAPI",
    start=0,
    end=5,
    font_size=56,
    font_color="#FFD700",
    shadow_enabled=True
)

# 保存草稿
result = client.save_draft(draft.draft_id)
print(f"草稿已保存: {result.draft_url}")
```

--------------------------------

### Python Client: Using Presets

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Illustrates how to leverage predefined constants for resolution, transitions, and text animations when using the VectCutClient.

```APIDOC
### Using Presets

```python
from skill.scripts.vectcut_client import VectCutClient, Resolution, Transition, TextAnimation

with VectCutClient() as client:
    # Use preset resolution
    draft = client.create_draft(
        width=Resolution.VERTICAL.value[0],
        height=Resolution.VERTICAL.value[1]
    )

    # Use preset transition
    client.add_video(
        draft.draft_id,
        "video.mp4",
        transition=Transition.FADE_IN.value
    )

    # Use preset text animation
    client.add_text(
        draft.draft_id,
        "Hello",
        start=0,
        end=3,
        text_intro=TextAnimation.ZOOM_IN.value
    )
```
```

--------------------------------

### Python Client: Create Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Demonstrates how to initialize the VectCutClient and create a new video draft with specified dimensions.

```APIDOC
## Testing Python Client

```python
from skill.scripts.vectcut_client import VectCutClient

# Create client
client = VectCutClient("http://localhost:9001")

# Create draft
draft = client.create_draft(width=1080, height=1920)
print(f"Draft ID: {draft.draft_id}")

# Save draft
result = client.save_draft(draft.draft_id)
print(f"Draft URL: {result.draft_url}")
```
```

--------------------------------

### Python Client Usage with Presets

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Demonstrates using predefined values for resolution, transitions, and text animations with the VectCutClient. This simplifies common configurations.

```python
from skill.scripts.vectcut_client import VectCutClient, Resolution, Transition, TextAnimation

with VectCutClient() as client:
    # Use preset resolution
    draft = client.create_draft(
        width=Resolution.VERTICAL.value[0],
        height=Resolution.VERTICAL.value[1]
    )

    # Use preset transition
    client.add_video(
        draft.draft_id,
        "video.mp4",
        transition=Transition.FADE_IN.value
    )

    # Use preset text animation
    client.add_text(
        draft.draft_id,
        "Hello",
        start=0,
        end=3,
        text_intro=TextAnimation.ZOOM_IN.value
    )
```

--------------------------------

### AI Text-to-Video Workflow with HTTP Requests

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README.md

Illustrates an AI-driven video creation process using HTTP requests to the VectCutAPI. This workflow includes creating a draft, adding a background video, and overlaying segmented text with different colors.

```python
import requests

BASE_URL = "http://localhost:9001"

# 1. 创建草稿
draft = requests.post(f"{BASE_URL}/create_draft", json={
    "width": 1080,
    "height": 1920
}).json()
draft_id = draft["output"]["draft_id"]

# 2. 添加背景视频
requests.post(f"{BASE_URL}/add_video", json={
    "draft_id": draft_id,
    "video_url": "https://example.com/bg.mp4",
    "volume": 0.4
})

# 3. 添加分段文字
segments = ["第一段文字", "第二段文字", "第三段文字"]
colors = ["#FF6B6B", "#4ECDC4", "#45B7D1"]

for i, (segment, color) in enumerate(zip(segments, colors)):
    requests.post(f"{BASE_URL}/add_text", json={
        "draft_id": draft_id,
        "text": segment,
        "start": i * 4,
        "end": (i + 1) * 4,
        "font_size": 48,
        "font_color": color,
        "shadow_enabled": True
    })

# 4. 保存草稿
result = requests.post(f"{BASE_URL}/save_draft", json={
    "draft_id": draft_id
}).json()

print(f"视频已生成: {result['output']['draft_url']}")
```

--------------------------------

### Basic Video Production with VectCut Client

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README_EN.md

Use the VectCutClient to programmatically create drafts, add background videos, overlay text with styling, and save the final video.

```python
from skill.scripts.vectcut_client import VectCutClient

# Create client
client = VectCutClient("http://localhost:9001")

# Create draft
draft = client.create_draft(width=1080, height=1920)

# Add background video
client.add_video(
    draft.draft_id,
    "https://example.com/background.mp4",
    volume=0.6
)

# Add title text
client.add_text(
    draft.draft_id,
    "Welcome to VectCutAPI",
    start=0,
    end=5,
    font_size=56,
    font_color="#FFD700",
    shadow_enabled=True
)

# Save draft
result = client.save_draft(draft.draft_id)
print(f"Draft saved: {result.draft_url}")
```

--------------------------------

### Create Symbolic Link (macOS/Linux)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Creates a symbolic link for the skill directory on macOS or Linux, which is the recommended method.

```bash
# 或创建符号链接 (推荐)
ln -s $(pwd)/skill ~/.claude/skills/public/vectcut-api
```

--------------------------------

### Create and Save a Draft with Python Client

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Basic usage of the VectCutClient to create a new video draft and save it. This snippet demonstrates the fundamental client-server interaction for draft management.

```python
from skill.scripts.vectcut_client import VectCutClient

# Create client
client = VectCutClient("http://localhost:9001")

# Create draft
draft = client.create_draft(width=1080, height=1920)
print(f"Draft ID: {draft.draft_id}")

# Save draft
result = client.save_draft(draft.draft_id)
print(f"Draft URL: {result.draft_url}")
```

--------------------------------

### MCP Client Configuration

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Configure the MCP client by creating or updating the `mcp_config.json` file. This specifies how to run the MCP server, including the command, arguments, working directory, and environment variables.

```json
{
  "mcpServers": {
    "capcut-api": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/VectCutAPI",
      "env": {
        "PYTHONPATH": "/path/to/VectCutAPI",
        "DEBUG": "0"
      }
    }
  }
}
```

--------------------------------

### VectCutClient Class Structure

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Outlines the structure of the main VectCutClient class, including its initializer, core methods, and context manager implementation.

```python
# 主客户端类
class VectCutClient:
    """VectCutAPI Python 客户端"""

    def __init__(self, base_url: str, timeout: int = 120)
    def create_draft(...) -> DraftInfo
    def save_draft(...) -> DraftInfo
    def add_video(...) -> bool
    def add_audio(...) -> bool
    def add_text(...) -> bool
    # ... 更多方法

    def __enter__():
    def __exit__(self, exc_type, exc_val, exc_tb)
```

--------------------------------

### SKILL.md Metadata Format

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Illustrates the YAML frontmatter format for defining metadata in the SKILL.md file, including name and description fields.

```markdown
---
name: vectcut-api
description: VectCutAPI is a powerful cloud-based video editing API...
---

# 技能内容...
```

--------------------------------

### Configure MCP Server

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Sets up the `mcp_config.json` file to define the CapCut API server connection details.

```json
{
  "mcpServers": {
    "capcut-api": {
      "command": "python3.10",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/CapCutAPI-dev",
      "env": {
        "PYTHONPATH": "/path/to/CapCutAPI-dev"
      }
    }
  }
}
```

--------------------------------

### Complete Video Editing Workflow with MCP Protocol

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Execute a multi-step video editing workflow using the MCP client. This includes creating a draft, adding background video, adding text, applying keyframe animations, and saving the project.

```python
# 1. Create a new project
draft = mcp_client.call_tool("create_draft", {
    "width": 1080,
    "height": 1920
})
draft_id = draft["result"]["draft_id"]

# 2. Add background video
mcp_client.call_tool("add_video", {
    "video_url": "https://example.com/bg.mp4",
    "draft_id": draft_id,
    "start": 0,
    "end": 10,
    "volume": 0.6
})

# 3. Add title text
mcp_client.call_tool("add_text", {
    "text": "AI-Driven Video Production",
    "draft_id": draft_id,
    "start": 1,
    "end": 6,
    "font_size": 56,
    "shadow_enabled": True,
    "background_color": "#1E1E1E"
})

# 4. Add keyframe animation
mcp_client.call_tool("add_video_keyframe", {
    "draft_id": draft_id,
    "track_name": "main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],
    "values": ["1.0", "1.2", "0.8"]
})

# 5. Save the project
result = mcp_client.call_tool("save_draft", {
    "draft_id": draft_id
})

print(f"Project saved: {result['result']['draft_url']}")
```

--------------------------------

### Copy Skill Files (Windows - Git)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Copies the skill files to the specified directory after cloning the repository on Windows.

```powershell
# 复制 skill 文件
Copy-Item -Path "skill\*" -Destination "$env:USERPROFILE\.claude\skills\public\vectcut-api\" -Recurse -Force
```

--------------------------------

### create_draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Creates a new video draft project with specified dimensions.

```APIDOC
## create_draft

### Description
Creates a new video draft project with specified dimensions.

### Method
POST

### Endpoint
/create_draft

### Parameters
#### Request Body
- **width** (integer) - Required - The width of the video draft.
- **height** (integer) - Required - The height of the video draft.
```

--------------------------------

### Create a New Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Initiates a new video draft with specified dimensions. The returned `draft_id` is used for subsequent operations.

```python
# Create 1080x1920 portrait project
result = mcp_client.call_tool("create_draft", {
    "width": 1080,
    "height": 1920
})
draft_id = result["draft_id"]
```

--------------------------------

### Apply Keyframe Animation to Video

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Applies keyframe animations for properties like scale and opacity to a video track within a draft. Requires a valid `draft_id`.

```python
# Scale and opacity animation
mcp_client.call_tool("add_video_keyframe", {
    "draft_id": draft_id,
    "track_name": "video_main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],
    "values": ["1.0", "1.5", "0.5"]
})
```

--------------------------------

### Run Test Client

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Execute the test client script to verify CapCut API functionality. Ensure the script is executable.

```bash
# Run test client
python test_mcp_client.py
```

--------------------------------

### Copy Skill Files (macOS/Linux)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Copies the skill files to the specified directory on macOS or Linux.

```bash
# 复制 skill 文件
cp -r skill/* ~/.claude/skills/public/vectcut-api/
```

--------------------------------

### Copy Skill Files (Windows - CMD)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Use this command to copy skill files using CMD on Windows.

```cmd
xcopy "skill\*" "%USERPROFILE%\.claude\skills\public\vectcut-api\" /E /I /Y
```

--------------------------------

### Add Background Video to Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Appends a video to the draft with specified URL, duration, and volume. Requires a valid `draft_id`.

```python
# Add background video
mcp_client.call_tool("add_video", {
    "video_url": "https://example.com/video.mp4",
    "draft_id": draft_id,
    "start": 0,
    "end": 10,
    "volume": 0.8
})
```

--------------------------------

### add_video

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds a video track to the project with specified timing and transformations.

```APIDOC
## add_video

### Description
Adds a video track to the project with specified timing and transformations.

### Method
POST

### Endpoint
/add_video

### Parameters
#### Request Body
- **video_url** (string) - Required - URL of the video file.
- **start** (integer) - Optional - Start time of the video clip in milliseconds.
- **end** (integer) - Optional - End time of the video clip in milliseconds.
- **transform** (object) - Optional - Transformation properties (scale, rotation, position).
- **volume** (float) - Optional - Volume of the video clip (0.0 to 1.0).
```

--------------------------------

### add_text

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds text elements to the video draft with customizable styles.

```APIDOC
## add_text

### Description
Adds text elements to the video draft with customizable styles.

### Method
POST

### Endpoint
/add_text

### Parameters
#### Request Body
- **text** (string) - Required - The text content to add.
- **font_size** (integer) - Optional - The font size of the text.
- **color** (string) - Optional - The color of the text (e.g., hex code).
- **shadow** (object) - Optional - Shadow effect for the text.
- **background** (object) - Optional - Background for the text.
```

--------------------------------

### Create Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Creates a new video draft with specified dimensions. Returns the unique ID of the created draft.

```APIDOC
## create_draft

### Description
Creates a new video draft with specified width and height.

### Method
call_tool

### Parameters
#### Arguments
- **width** (integer) - Required - The width of the video draft.
- **height** (integer) - Required - The height of the video draft.

### Request Example
```python
result = mcp_client.call_tool("create_draft", {
    "width": 1080,
    "height": 1920
})
```

### Response
#### Success Response
- **draft_id** (string) - The unique identifier for the created draft.
```

--------------------------------

### Verify VectCutAPI Service

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Use curl or a web browser to verify that the VectCutAPI service is running.

```bash
# 使用 curl
curl http://localhost:9001/
```

```bash
# 或使用浏览器访问
# http://localhost:9001/
```

--------------------------------

### add_audio

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds an audio track to the project with adjustable volume and effects.

```APIDOC
## add_audio

### Description
Adds an audio track to the project with adjustable volume and effects.

### Method
POST

### Endpoint
/add_audio

### Parameters
#### Request Body
- **audio_url** (string) - Required - URL of the audio file.
- **volume** (float) - Optional - Volume of the audio track (0.0 to 1.0).
- **speed** (float) - Optional - Playback speed of the audio.
- **effects** (array) - Optional - List of audio effects to apply.
```

--------------------------------

### Clone VectCut Skill Repository (Windows)

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/INSTALLATION.md

Use this command to clone the VectCut Skill repository on Windows using Git.

```powershell
# 克隆项目
git clone https://github.com/your-username/vectcut-skill.git
cd vectcut-skill
```

--------------------------------

### add_sticker

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds sticker elements to the video with specified resource IDs and transformations.

```APIDOC
## add_sticker

### Description
Adds sticker elements to the video with specified resource IDs and transformations.

### Method
POST

### Endpoint
/add_sticker

### Parameters
#### Request Body
- **resource_id** (string) - Required - The ID of the sticker resource.
- **position** (object) - Optional - Position of the sticker on the screen.
- **scale** (float) - Optional - Scale factor for the sticker.
- **rotation** (float) - Optional - Rotation angle for the sticker.
```

--------------------------------

### Add Video

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds a video clip to the draft at a specified time range with adjustable volume.

```APIDOC
## add_video

### Description
Adds a video from a URL to the draft with specified start and end times and volume.

### Method
call_tool

### Parameters
#### Arguments
- **video_url** (string) - Required - The URL of the video to add.
- **draft_id** (string) - Required - The ID of the draft to add the video to.
- **start** (integer) - Required - The start time (in seconds) for the video clip.
- **end** (integer) - Required - The end time (in seconds) for the video clip.
- **volume** (float) - Optional - The volume of the video clip (0.0 to 1.0).

### Request Example
```python
mcp_client.call_tool("add_video", {
    "video_url": "https://example.com/video.mp4",
    "draft_id": draft_id,
    "start": 0,
    "end": 10,
    "volume": 0.8
})
```
```

--------------------------------

### Test VectCutAPI Service with cURL

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Use cURL to test if the VectCutAPI service is running locally. Accessing the root URL should display the API documentation.

```bash
# In a new terminal, test the API
curl http://localhost:9001/

# Or access via browser
# http://localhost:9001/
```

--------------------------------

### Testing VectCutAPI Service

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

Instructions to test the VectCutAPI service locally using curl or a web browser.

```APIDOC
## Testing VectCutAPI Service

```bash
# Test the API in a new terminal
curl http://localhost:9001/

# Or access via browser
# http://localhost:9001/
```

You should see the API documentation page.
```

--------------------------------

### Add Styled Text to Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds text with advanced styling options including shadow and background effects. Requires a valid `draft_id`.

```python
# Text with shadow and background
mcp_client.call_tool("add_text", {
    "text": "Advanced Text Effects",
    "draft_id": draft_id,
    "font_size": 56,
    "font_color": "#FFD700",
    "shadow_enabled": True,
    "shadow_color": "#000000",
    "shadow_alpha": 0.8,
    "background_color": "#1E1E1E",
    "background_alpha": 0.7,
    "background_round_radius": 15
})
```

--------------------------------

### Add Video Keyframe

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Applies keyframe animations to video properties like scale and opacity.

```APIDOC
## add_video_keyframe

### Description
Adds keyframe animation data for specified properties of a video track within a draft.

### Method
call_tool

### Parameters
#### Arguments
- **draft_id** (string) - Required - The ID of the draft.
- **track_name** (string) - Required - The name of the video track to animate.
- **property_types** (array of strings) - Required - The types of properties to animate (e.g., "scale_x", "scale_y", "alpha").
- **times** (array of floats) - Required - The time points (in seconds) for the keyframes.
- **values** (array of strings) - Required - The values for each property at the corresponding time points.

### Request Example
```python
# Scale and opacity animation
mcp_client.call_tool("add_video_keyframe", {
    "draft_id": draft_id,
    "track_name": "video_main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],
    "values": ["1.0", "1.5", "0.5"]
})
```
```

--------------------------------

### Core APIs

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/README_EN.md

This section details the core API functions for video manipulation. These functions allow for draft creation, saving, and the addition of various media elements and effects.

```APIDOC
## Core APIs

This section details the core API functions for video manipulation. These functions allow for draft creation, saving, and the addition of various media elements and effects.

### Functions

- **`create_draft()`**: Create video draft.
- **`save_draft()`**: Save draft and generate URL.
- **`add_video()`**: Add video track.
- **`add_audio()`**: Add audio track.
- **`add_image()`**: Add image material.
- **`add_text()`**: Add text element.
- **`add_subtitle()`**: Add SRT subtitle.
- **`add_effect()`**: Add video effect.
- **`add_sticker()`**: Add sticker.
- **`add_video_keyframe()`**: Add keyframe animation.

For complete API documentation, see [api_reference.md](skill/references/api_reference.md).
```

--------------------------------

### Add Multi-Style Text to Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds text where different segments can have distinct styles, such as different colors. Requires a valid `draft_id`.

```python
# Different colored text segments
mcp_client.call_tool("add_text", {
    "text": "Colorful Text Effect",
    "draft_id": draft_id,
    "text_styles": [
        {"start": 0, "end": 2, "font_color": "#FF0000"},
        {"start": 2, "end": 4, "font_color": "#00FF00"}
    ]
})
```

--------------------------------

### Save Draft Project

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Saves the current state of the video draft. Requires a valid `draft_id`.

```python
# Save draft
result = mcp_client.call_tool("save_draft", {
    "draft_id": draft_id
})
```

--------------------------------

### add_image

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds an image asset to the project with transformations and animations.

```APIDOC
## add_image

### Description
Adds an image asset to the project with transformations and animations.

### Method
POST

### Endpoint
/add_image

### Parameters
#### Request Body
- **image_url** (string) - Required - URL of the image file.
- **transform** (object) - Optional - Transformation properties (scale, rotation, position).
- **animation** (object) - Optional - Animation to apply to the image.
- **transition** (object) - Optional - Transition effect for the image.
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Enable verbose logging for the CapCut API server by setting the DEBUG environment variable. This is useful for troubleshooting.

```bash
# Enable verbose logging
export DEBUG=1
python mcp_server.py
```

--------------------------------

### Add Text

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds text to a video draft with various styling options. Supports basic text, styled segments, and advanced effects like shadows and backgrounds.

```APIDOC
## add_text

### Description
Adds text to a specified draft with options for content, timing, font, color, and advanced styling.

### Method
call_tool

### Parameters
#### Arguments
- **text** (string) - Required - The content of the text.
- **draft_id** (string) - Required - The ID of the draft to add text to.
- **start** (integer) - Optional - The start time (in seconds) for the text.
- **end** (integer) - Optional - The end time (in seconds) for the text.
- **font_size** (integer) - Optional - The size of the font.
- **font_color** (string) - Optional - The color of the font (e.g., "#FFFFFF").
- **shadow_enabled** (boolean) - Optional - Whether to enable text shadow.
- **shadow_color** (string) - Optional - The color of the text shadow.
- **shadow_alpha** (float) - Optional - The alpha transparency of the shadow.
- **background_color** (string) - Optional - The background color for the text.
- **background_alpha** (float) - Optional - The alpha transparency of the background.
- **background_round_radius** (integer) - Optional - The corner radius for the text background.
- **text_styles** (array) - Optional - An array of objects defining styles for text segments.
  - **start** (integer) - Required - Start time for the style.
  - **end** (integer) - Required - End time for the style.
  - **font_color** (string) - Required - Font color for the segment.

### Request Example
```python
# Basic text
mcp_client.call_tool("add_text", {
    "text": "My Video Title",
    "start": 0,
    "end": 5,
    "draft_id": draft_id,
    "font_size": 48,
    "font_color": "#FFFFFF"
})

# Text with advanced styling
mcp_client.call_tool("add_text", {
    "text": "Advanced Text Effects",
    "draft_id": draft_id,
    "font_size": 56,
    "font_color": "#FFD700",
    "shadow_enabled": True,
    "shadow_color": "#000000",
    "shadow_alpha": 0.8,
    "background_color": "#1E1E1E",
    "background_alpha": 0.7,
    "background_round_radius": 15
})

# Multi-style text
mcp_client.call_tool("add_text", {
    "text": "Colorful Text Effect",
    "draft_id": draft_id,
    "text_styles": [
        {"start": 0, "end": 2, "font_color": "#FF0000"},
        {"start": 2, "end": 4, "font_color": "#00FF00"}
    ]
})
```
```

--------------------------------

### Add Title Text to Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds a title with specified text, duration, font size, and color to a draft. Requires a valid `draft_id`.

```python
# Add title text
mcp_client.call_tool("add_text", {
    "text": "My Video Title",
    "start": 0,
    "end": 5,
    "draft_id": draft_id,
    "font_size": 48,
    "font_color": "#FFFFFF"
})
```

--------------------------------

### Advanced Text Effects with MCP Protocol

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Apply advanced text effects, including multi-style colored text, using the MCP protocol. This allows for dynamic styling of text segments within a specified duration.

```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"}
    ]
})
```

--------------------------------

### add_subtitle

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds subtitle files to the video draft with specified font styles and positions.

```APIDOC
## add_subtitle

### Description
Adds subtitle files to the video draft with specified font styles and positions.

### Method
POST

### Endpoint
/add_subtitle

### Parameters
#### Request Body
- **srt_path** (string) - Required - Path to the SRT subtitle file.
- **font_style** (object) - Optional - Font styling for the subtitles.
- **position** (string) - Optional - Position of the subtitles on the screen.
```

--------------------------------

### Python Enum Classes

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Defines Python Enum classes for common video resolutions and transition effects, promoting consistent usage.

```python
# 枚举类
class Resolution(Enum):
    """常用视频分辨率预设"""
    VERTICAL = (1080, 1920)
    HORIZONTAL = (1920, 1080)
    SQUARE = (1080, 1080)

class Transition(Enum):
    """转场效果类型"""
    FADE_IN = "fade_in"
    FADE_OUT = "fade_out"
```

--------------------------------

### add_video_keyframe

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Adds keyframe animations to video properties.

```APIDOC
## add_video_keyframe

### Description
Adds keyframe animations to video properties.

### Method
POST

### Endpoint
/add_video_keyframe

### Parameters
#### Request Body
- **property_types** (array) - Required - Types of properties to animate (e.g., 'position', 'scale').
- **times** (array) - Required - Array of timestamps for keyframes.
- **values** (array) - Required - Array of values corresponding to each keyframe.
```

--------------------------------

### Save Draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Saves the current state of the video draft.

```APIDOC
## save_draft

### Description
Saves the specified video draft.

### Method
call_tool

### Parameters
#### Arguments
- **draft_id** (string) - Required - The ID of the draft to save.

### Request Example
```python
result = mcp_client.call_tool("save_draft", {
    "draft_id": draft_id
})
```
```

--------------------------------

### Skill Structure

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Defines the required file structure for a Claude Code Skill, including the main SKILL.md document and optional resource directories.

```markdown
skill/
├── SKILL.md              # 必需 - 技能主文档
└── [资源目录]            # 可选 - scripts/, references/, assets/
```

--------------------------------

### Manual Skill Specification in Claude Code

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/USAGE.md

If automatic triggering of the vectcut-api skill fails, you can manually specify it in your prompt to Claude Code.

```text
User: Use vectcut-api skill to create a video draft
```

--------------------------------

### add_effect

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Applies visual effects to the video with specified types and parameters.

```APIDOC
## add_effect

### Description
Applies visual effects to the video with specified types and parameters.

### Method
POST

### Endpoint
/add_effect

### Parameters
#### Request Body
- **effect_type** (string) - Required - The type of visual effect to apply.
- **parameters** (object) - Optional - Parameters specific to the chosen effect.
- **duration** (integer) - Optional - Duration for which the effect should be applied in milliseconds.
```

--------------------------------

### Add Stylized Text via API

Source: https://github.com/sun-guannan/capcutapi/blob/main/README.md

Use the `requests` library to send a POST request to the `/add_text` endpoint to add stylized text. Customize text content, duration, font, color, size, and shadow effects.

```python
import requests

# Add title text
response = requests.post("http://localhost:9001/add_text", json={
    "text": "Welcome to VectCutAPI",
    "start": 0,
    "end": 5,
    "font": "Source Han Sans",
    "font_color": "#FFD700",
    "font_size": 48,
    "shadow_enabled": True,
    "background_color": "#000000"
})

print(f"Text addition result: {response.json()}")
```

--------------------------------

### save_draft

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Saves the current state of a draft project.

```APIDOC
## save_draft

### Description
Saves the current state of a draft project.

### Method
POST

### Endpoint
/save_draft

### Parameters
#### Request Body
- **draft_id** (string) - Required - The unique identifier for the draft project to save.
```

--------------------------------

### get_video_duration

Source: https://github.com/sun-guannan/capcutapi/blob/main/MCP_Documentation_English.md

Retrieves the duration of a given video file.

```APIDOC
## get_video_duration

### Description
Retrieves the duration of a given video file.

### Method
GET

### Endpoint
/get_video_duration

### Parameters
#### Query Parameters
- **video_url** (string) - Required - The URL of the video file.
```

--------------------------------

### Python Data Classes

Source: https://github.com/sun-guannan/capcutapi/blob/main/vectcut-skill/docs/ARCHITECTURE.md

Defines Python dataclasses for representing draft information and API results, ensuring type safety.

```python
# 数据类
@dataclass
class DraftInfo:
    """草稿信息"""
    draft_id: str
    draft_folder: Optional[str] = None
    draft_url: Optional[str] = None

@dataclass
class ApiResult:
    """API 响应结果"""
    success: bool
    output: Dict[str, Any]
    error: Optional[str] = None
```
Tokens:
Raw