DOCSEARCHbyAlgolia
Submit Docs

VectCutAPI Documentation

repository·main·Indexed 24 days ago

https://github.com/sun-guannan/vectcutapi

A 'toAgent' video editing tool providing cloud-based HTTP APIs and Model Context Protocol (MCP) skills. It enables AI agents and automated workflows to perform complex video editing tasks—including adding subtitles, keyframe animations, and multi-track editing—which can be exported as drafts for CapCut or Jianying. Features include a Python SDK (VectCutClient) and integration support for AI agents like Claude Code and Trae.

Tokens
21.6K
Snippets
50
Records
78
Agent score
84%

What's inside VectCutAPI

  1. Supported Video Editing Capabilities

    main

    VectCutAPI provides comprehensive control over video production modules:

    • Draft Management: Create, save, and query CapCut/JianYing draft files.
    • Video Processing: Multi-format import, transitions, effects, and masks.
    • Audio Editing: Track management, volume control, and audio effects.
    • Image Processing: Import, animations, masks, and filters.
    • Text Editing: Multi-style text, shadows, backgrounds, and animations.
    • Subtitle System: SRT import, styling, and time synchronization.
    • Effects Engine: Visual effects, filters, and transition animations.
    • Sticker System: Material usage, position control, and animations.
    • Keyframes: Property animations, timeline control, and easing.
    • Media Analysis: Duration retrieval and format detection.

  2. Understand the CapCut API response format

    main

    Tool calls return a JSON object indicating success and providing the resulting data (such as draft_id or draft_url) and metadata about the features used in the request.

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

  3. Handle errors in the VectCut Python Client

    main

    The Python client uses an ApiResult object to wrap responses. Errors can occur at the network level (handled via requests.RequestException) or the application level (indicated by the success field in the JSON response).

    When using high-level methods like create_draft(), the client checks the ApiResult.success status and raises an Exception if the operation failed, providing the error message from the server.

    # Example of how high-level methods handle errors internally
def create_draft(self, ...) -> DraftInfo:
    result = self._post("/create_draft", ...)
    if result.success:
        return DraftInfo(...)
    raise Exception(f"创建草稿失败: {result.error}")

  4. Understand the Video Production Data Flow

    main

    The video production process follows a specific sequence from user intent to the generation of CapCut (JianYing) draft files. The flow is as follows:

    1. Intent Parsing: Claude parses the user's request.
    2. Skill Loading: The vectcut-api Skill is loaded.
    3. Client Invocation: The Python client calls VectCutClient methods (e.g., create_draft, add_video, add_audio, add_text, save_draft).
    4. HTTP Request: The client sends POST requests to the VectCutAPI Server (typically http://localhost:9001/).
    5. Draft Generation: The Flask-based server uses pyJianYingDraft to generate CapCut draft files.
    6. Output: The final result is a draft directory (dfd_xxxxx/) containing draft_content.json and material_*.json files.

  5. Export and use generated drafts in CapCut or Jianying

    main

    When you call save_draft, the system generates a folder starting with dfd_ in the directory where capcut_server.py is running. To view the draft in your local application, copy this folder to your CapCut or Jianying drafts directory.

    The output format is determined by the draft_profile setting in config.json:

    • capcut_legacy: For existing CapCut templates.
    • jianying_legacy: For existing Jianying templates.
    • jianying_pro_10: For Jianying Pro 10.x (Windows-style layout using draft_content.json).

  6. How the VectCutAPI Skill architecture works

    main

    The VectCutAPI Skill is designed to integrate with Claude Code (Anthropic CLI Tool) to provide cloud-based video editing capabilities. The architecture follows a layered approach:

    1. Claude Code: The user interface where instructions are received.
    2. Skill System: A structured set of files including SKILL.md (main documentation), scripts/ (executable code like the Python client), and references/ (detailed documentation).
    3. VectCutAPI Server: An HTTP API server (capcut_server.py) running on port 9001 that utilizes the pyJianYingDraft library to manage CapCut/JianYing drafts.
    4. CapCut/JianYing: The target video editing application where the generated drafts are used.
    ┌─────────────────────────────────────────────────────────────────┐
│                         Claude Code                              │
│                    (Anthropic CLI Tool)                          │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Skill System                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  vectcut-api Skill                                        │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │  │
│  │  │   SKILL.md   │  │ scripts/    │  │ references/  │   │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘   │  │
│  └──────────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      VectCutAPI                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ HTTP API Server (capcut_server.py)                      │  │
│  │ Port: 9001                                              │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ pyJianYingDraft (剪映草稿核心库)                         │  │
│  │ - 草稿管理                                              │  │
│  │ - 轨道操作                                              │  │
│  │ - 片段处理                                              │  │
│  └──────────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    剪映 / CapCut                                 │
│                    (视频编辑应用)                                │
└─────────────────────────────────────────────────────────────────┘

  7. Start VectCutAPI Services

    main

    You can run the project in two modes depending on your needs:

    1. HTTP API Server: Starts a server on port 9001 for standard RESTful requests.
    2. MCP Server: Starts a service supporting stdio communication for AI agents (like Claude Code or Trae).

    Run the following commands from the project root:

  8. Use VectCutAPI with Claude Code

    main

    The skill can be used within Claude Code via automatic trigger or manual specification.

    Automatic Trigger: Claude Code will automatically load the vectcut-api skill when you use keywords such as:

    • "创建视频草稿" (Create video draft)
    • "视频剪辑" (Video editing)
    • "添加视频轨道" (Add video track)
    • "添加文字到视频" (Add text to video)
    • "VectCutAPI"
    • "剪映草稿" (Jianying draft)

    Manual Trigger: If the skill is not automatically detected, explicitly mention it: "使用 vectcut-api skill 创建一个视频草稿" (Use vectcut-api skill to create a video draft)

  9. Install the VectCutAPI Core Service

    main

    VectCutAPI is the core service required for the skill to function. Follow these steps to set up the server:

    Windows Installation

    1. Install Python: Download from python.org. Crucial: Check "Add Python to PATH" during installation.
    2. Clone Project:
      git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI
    3. Create Virtual Environment:
      python -m venv venv-vectcut
venv-vectcut\Scripts\activate
    4. Install Dependencies:
      python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-mcp.txt
    5. Configure:
      copy config.json.example config.json
notepad config.json
    6. Start Service:
      python capcut_server.py
      The service starts at http://localhost:9001.

    macOS/Linux Installation

    1. Install Python:
      • macOS: brew install python@3.11
      • Ubuntu/Debian: sudo apt update && sudo apt install python3.11 python3.11-venv python3-pip
      • CentOS/RHEL: sudo yum install python311 python311-pip
    2. Clone Project:
      git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI
    3. Create Virtual Environment:
      python3 -m venv venv-vectcut
source venv-vectcut/bin/activate
    4. Install Dependencies:
      python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-mcp.txt
    5. Configure:
      cp config.json.example config.json
nano config.json
    6. Start Service:
      python capcut_server.py
    python capcut_server.py

  10. Basic video editing workflow with MCP tools

    main

    A standard editing workflow involves three main steps: creating a draft, adding content (text or video), and saving the project. All content addition tools require a draft_id obtained from the create_draft call.

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

# 2. 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"
})

# 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
})

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

  11. Start the VectCutAPI services

    main

    VectCutAPI provides two types of services:

    • HTTP API Server: Runs on port 9001 by default.
    • MCP Protocol Service: Supports stdio communication for integration with AI agents like Claude Code or Trae.
    python capcut_server.py # Start the HTTP API server, default port: 9001

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

  12. Install and set up the CapCut API MCP Server

    main

    To use the CapCut API as an MCP server, ensure you have Python 3.10+ and the CapCut application installed on your macOS or Windows machine. Follow these steps to set up a dedicated virtual environment and install dependencies:

    1. Create a virtual environment:
      python3.10 -m venv venv-mcp
source venv-mcp/bin/activate  # macOS/Linux
# or venv-mcp\Scripts\activate  # Windows
    2. Install dependencies:
      pip install -r requirements-mcp.txt
    3. Configure the MCP Client: Update your mcp_config.json to include the capcut-api server. Ensure cwd and PYTHONPATH point to the absolute path of the CapCutAPI-dev directory.
    {
  "mcpServers": {
    "capcut-api": {
      "command": "python3.10",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/CapCutAPI-dev",
      "env": {
        "PYTHONPATH": "/path/to/CapCutAPI-dev"
      }
    }
  }
}