VectCutAPI

https://github.com/sun-guannan/vectcutapi
Admin
VectCutAPI is a powerful editing API designed to provide precise control over AI-generated assets...
Tokens:163,097
Snippets:1,025
Trust Score:6.6
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install VectCutAPI

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

Clone the VectCutAPI repository, install dependencies, configure, and start the HTTP API server on port 9001.

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

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

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

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

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

### API Example: Add Video Material

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

Add a background video via the /add_video endpoint. The request includes video_url, start, end, volume, and transition parameters. Note: the source code has a missing comma after the 'end' field.

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

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

### Installation and Deployment Commands

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

Commands to clone the VectCutAPI project, set up a Python virtual environment, install dependencies for HTTP API and optional MCP support, and copy the configuration file. Requires Python 3.10+, Jianying or CapCut International, and FFmpeg. The config.json.example file is copied to config.json for editing.

```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

```

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

### Install dependencies in virtual environment

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

Creates a Python 3.10 virtual environment and installs dependencies from requirements-mcp.txt. Use the activation command matching your OS (macOS/Linux vs Windows).

```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
```

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

### Build from Source

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Clone the repository, install dependencies, build, and test the server.

```bash
# Clone this repository
git clone <your-repo-url>
cd capcut-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm start
```

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

### Verify Installation

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

Enter a command in Claude Code to trigger the vectcut-api skill and invoke relevant functions.

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

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

### Start MCP Protocol Service

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

Starts the MCP protocol service using mcp_server.py, which supports stdio communication.

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

```

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

### Install from npm

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Globally install the capcut-mcp-server package via npm.

```bash
npm install -g capcut-mcp-server
```

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

### Start HTTP API Server

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

Starts the HTTP API server using capcut_server.py. The server runs on default port 9001.

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

```

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

### Install VectCutAPI

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Clone the VectCutAPI repository and install its Python dependencies.

```bash
git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI
pip install -r requirements.txt
```

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

### Install Skill

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

Clone the vectcut-skill repository and copy skill files to the Claude Code skills directory for Windows or Linux/macOS.

```bash
# Clone this project
git clone https://github.com/HUNSETO1413/vectcut-skill.git
cd vectcut-skill

# Copy skill files to Claude Code skills directory
# Windows:
copy skill\* %USERPROFILE%\.claude\skills\public\vectcut-api\ /E

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

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

### Enable debug mode

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

Sets DEBUG environment variable and starts the MCP server with verbose logging.

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

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

### GET /preview

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Renders the HTML preview page.

```APIDOC
## GET /preview

### Description
Renders the HTML preview page.

### Method
GET

### Endpoint
/preview

### Response
#### Success Response (200)
- HTML page (rendered `HTML_PREVIEW_TEMPLATE`)
```

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

### Building segments with ranges

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/time_util.md

Shows how to create a Video_segment using trange() and Timerange for target and source timeranges. The example prints start, duration, and end (all in µs) and asserts duration equals 10 * SEC.

```python
import pyJianYingDraft as draft
from pyJianYingDraft import trange, Timerange, tim, SEC

seg = draft.Video_segment(mat, target_timerange=trange("0s", "10s"),
                          source_timerange=Timerange(0, tim("8s")))

print(seg.start, seg.duration, seg.end)   # 0, 10000000, 10000000 (µs)
assert seg.duration == 10 * SEC
```

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

### capcut_get_duration example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Gets duration and metadata of media files.

```typescript
{
  "url": "https://example.com/video.mp4"
}
```

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

### API Example: Create Stylized Text

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

Add title text via the /add_text endpoint. The request includes text, start, end, font, font_color, font_size, shadow_enabled, and background_color. Note: the source code has a stray 'read' after the font value.

```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",read
    "font_color": "#FFD700",
    "font_size": 48,
    "shadow_enabled": True,
    "background_color": "#000000"
})

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

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

### Usage examples: utility functions for color, URL, path, and URL generation

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/utilities-and-infrastructure.md

Shows how to use hex_to_rgb, url_to_hash, build_draft_asset_path, and generate_draft_url. hex_to_rgb returns a tuple of floats; url_to_hash is used in a filename; build_draft_asset_path constructs a path; generate_draft_url creates a URL.

```python
from util import hex_to_rgb, url_to_hash, build_draft_asset_path, generate_draft_url

color = hex_to_rgb("#FF0000")          # (1.0, 0.0, 0.0)
name = f"video_{url_to_hash(video_url)}.mp4"
path = build_draft_asset_path("/drafts", draft_id, "video", name)
url  = generate_draft_url(draft_id)
```

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

### GET /preview

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Renders the full HTML preview application. This endpoint serves the main preview interface for the web player.

```APIDOC
## [GET] /preview

### Description
Renders the full HTML preview application. This endpoint serves the main preview interface for the web player.

### Method
GET

### Endpoint
/preview

### Response
#### Success Response (200)
- HTML content of the preview app

#### Response Example
(HTML content)
```

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

### Start the API Server

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Run the CapCut API server, which defaults to http://localhost:9001.

```bash
python capcut_server.py
```

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

### capcut_create_draft example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Creates a new video editing project with custom dimensions and frame rate.

```typescript
{
  "width": 1920,
  "height": 1080,
  "fps": 30
}
```

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

### capcut_add_video example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Adds video clips with transitions, speed control, and volume adjustments.

```typescript
{
  "draft_id": "abc123",
  "video_url": "https://example.com/video.mp4",
  "start": 0,
  "end": 10,
  "volume": 0.8,
  "transition": "fade_in",
  "speed": 1.0
}
```

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

### Response format example

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

Shows the JSON structure returned by the API, including success flag, result object, and features_used object.

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

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

### GET /preview/media

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Streams a local media file for the canvas player. The file path is provided via the `path` query parameter.

```APIDOC
## [GET] /preview/media

### Description
Streams a local media file for the canvas player. The file path is provided via the `path` query parameter.

### Method
GET

### Endpoint
/preview/media

### Parameters
#### Query Parameters
- **path** (string) - Required - Path to the local media file to stream.

### Response
#### Success Response (200)
- Media file content (streamed)

#### Response Example
(Media file stream)
```

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

### GET /preview/media

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Serves a local media file specified by the `path` query parameter.

```APIDOC
## GET /preview/media

### Description
Serves a local media file specified by the `path` query parameter.

### Method
GET

### Endpoint
/preview/media

### Parameters
#### Query Parameters
- **path** (string) - Required - URL-encoded absolute path to the media file

### Response
#### Success Response (200)
- The local media file

#### Error Responses
- **400** - text if `path` is missing
- **404** - text if file not found
```

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

### capcut_add_text example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Adds styled text overlays with animations, shadows, and backgrounds.

```typescript
{
  "draft_id": "abc123",
  "text": "Welcome!",
  "start": 0,
  "end": 3,
  "font_size": 72,
  "font_color": "#FFFFFF",
  "background_color": "#000000",
  "shadow_enabled": true,
  "animation": "fade_in"
}
```

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

### capcut_add_image example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Adds image overlays with positioning, scaling, and rotation.

```typescript
{
  "draft_id": "abc123",
  "image_url": "https://example.com/logo.png",
  "start": 0,
  "end": 5,
  "position_x": 0.9,
  "position_y": 0.1,
  "scale": 0.3
}
```

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

### capcut_add_keyframe example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Creates smooth animations using keyframe interpolation.

```typescript
{
  "draft_id": "abc123",
  "track_name": "main",
  "property_types": ["scale_x", "scale_y"],
  "times": [0, 2, 4],
  "values": ["1.0", "1.5", "1.0"]
}
```

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

### GET /api/preview_events

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Streams preview update events via Server-Sent Events.

```APIDOC
## GET /api/preview_events

### Description
Streams preview update events via Server-Sent Events.

### Method
GET

### Endpoint
/api/preview_events

### Response
#### Success Response (200)
- Content-Type: `text/event-stream`
- Sends `{"type":"connected"}` initially, then `draft_updated` events with heartbeat keep-alives
```

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

### Animation.__init__

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/keyframes-and-animation.md

Creates an animation with metadata, start time, and duration. Used for segment animations.

```APIDOC
## Animation.__init__

### Description
Creates an animation with metadata, start time, and duration. Used for segment animations.

### Method
Constructor

### Signature
```python
def __init__(self, animation_meta: Animation_meta, start: int, duration: int):
```

### Parameters
- **animation_meta** (Animation_meta) - Required - The animation metadata
- **start** (int) - Required - µs from segment start
- **duration** (int) - Required - µs

### Fields
- `name` (from meta title)
- `effect_id`
- `resource_id` (meta)
- `start` (µs from segment start)
- `duration` (µs)
- `is_video_animation` (set by subclasses)

### Methods
- `export_json()` → `{anim_adjust_params: None, platform: "all", panel, material_type, name, id: effect_id, type: animation_type, resource_id, start, duration}`
```

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

### GET /get_text_intro_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of text intro types. The enum source depends on the environment (CapCut or Jianying).

```APIDOC
## GET /get_text_intro_types

### Description
Retrieves the list of text intro types. The enum source depends on the environment (CapCut or Jianying).

### Method
GET

### Endpoint
/get_text_intro_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### GET /api/preview_events

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Server-Sent Events stream for live preview updates. Sends an initial 'connected' event, then 'draft_updated' messages, with a heartbeat every 20 seconds.

```APIDOC
## [GET] /api/preview_events

### Description
Server-Sent Events stream for live preview updates. Sends an initial 'connected' event, then 'draft_updated' messages, with a heartbeat every 20 seconds.

### Method
GET

### Endpoint
/api/preview_events

### Response
#### Success Response (200)
- `text/event-stream` stream with events

#### Response Example
(SSE stream)
```

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

### add_video_keyframe_impl usage examples

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/add_sticker_impl.md

Shows single keyframe fade-out, batch move+rotate, and error handling for unequal batch arrays.

```python
from add_video_keyframe_impl import add_video_keyframe_impl

# single keyframe: fade out
add_video_keyframe_impl(draft_id=draft_id, property_type="alpha",
                        time=2.0, value="0%")

# batch: move + rotate
add_video_keyframe_impl(
    draft_id=draft_id,
    property_types=["position_x", "rotation"],
    times=[0.0, 1.0],
    values=["-1", "45deg"],
)

try:
    add_video_keyframe_impl(draft_id=draft_id,
                            property_types=["alpha"], times=[0],
                            values=["50%", "60%"])  # unequal length
except Exception as e:
    print(e)
```

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

### capcut_add_effect example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Applies visual effects like blur, brightness, saturation, etc.

```typescript
{
  "draft_id": "abc123",
  "effect_name": "blur",
  "start": 0,
  "end": 2,
  "intensity": 0.7
}
```

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

### GET /api/active_draft

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Returns the parsed timeline JSON for a specified project or draft folder. If no project is specified, returns the latest project.

```APIDOC
## [GET] /api/active_draft

### Description
Returns the parsed timeline JSON for a specified project or draft folder. If no project is specified, returns the latest project.

### Method
GET

### Endpoint
/api/active_draft

### Parameters
#### Query Parameters
- **project_name** (string) - Optional - Name of the project to retrieve.
- **draft_folder** (string) - Optional - Path to the draft folder to retrieve.

### Response
#### Success Response (200)
- Parsed timeline JSON object

#### Response Example
{
  "canvas": {},
  "total_duration_sec": 0,
  "video_clips": [],
  "text_clips": [],
  "audio_clips": []
}
```

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

### Basic usage of get_or_create_draft

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/create_draft.md

Shows the basic sequence used by all impl modules: call get_or_create_draft with explicit width and height, then print the returned draft_id. The printed id is an example of the dfd_cat_<unix_timestamp>_<8-hex-uuid> format.

```python
from create_draft import get_or_create_draft

draft_id, script = get_or_create_draft(draft_id=None, width=1080, height=1920)
print(draft_id)  # dfd_cat_1752912902_0cae2e04
```

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

### Error handling example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/add_subtitle_impl.md

Catches ValueError for unsupported font or invalid SRT, and generic Exception for fetch/read failures. Demonstrates handling of both error types.

```python
try:
    add_subtitle_impl(srt_path="https://example.com/missing.srt", font="NotAFont")
except ValueError as e:
    print(e)
except Exception as e:
    print(f"fetch/read failed: {e}")
```

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

### Run CapCut MCP server in stdio mode

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Starts the server in default stdio mode for local integration. Run from the project directory.

```bash
node dist/index.js
```

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

### MCP Protocol Example: Complete Workflow

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

A complete MCP workflow: create a draft, add a background video, add title text, add a keyframe animation, and save the draft. The draft_id is used across calls. The final save returns a draft_url.

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

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

### GET /get_intro_animation_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of intro animation types. The enum source depends on the environment (CapCut or Jianying).

```APIDOC
## GET /get_intro_animation_types

### Description
Retrieves the list of intro animation types. The enum source depends on the environment (CapCut or Jianying).

### Method
GET

### Endpoint
/get_intro_animation_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### Basic Video Production with VectCutClient

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

Creates a draft, adds a background video and title text, then saves the draft using the VectCutClient. Requires a running server at http://localhost:9001.

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

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

### Run test client

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

Executes the test client to verify server functionality.

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

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

### trange() convenience constructor

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/time_util.md

Creates a Timerange from start and duration strings. The second argument is duration, not end time. Example: trange("0s", "5s") yields Timerange(start=0, duration=5000000).

```python
trange("0s", "5s")    # Timerange(start=0, duration=5000000)
```

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

### focus_window(hwnd)

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Brings the specified window to the foreground.

```APIDOC
## focus_window(hwnd)

### Description
Brings the specified window to the foreground.

### Parameters
- **hwnd** (int) - Required - Window handle.

### Returns
- None
```

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

### MCP Protocol Example: Advanced Text Effects

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

Add multi-style colored text using the add_text tool. The text_styles array defines per-segment font colors. Additional parameters include shadow_color, background_alpha, and background_round_radius.

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

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

### Basic add_video_track usage

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/add_video_track.md

Creates a new draft by passing video_url and draft_id=None, with width, height, start, and end parameters. Returns a result containing draft_id and draft_url.

```python
from add_video_track import add_video_track

result = add_video_track(
    video_url="https://example.com/clip.mp4",
    draft_id=None,          # creates a new draft
    width=1080, height=1920,
    start=0, end=10,
)
print(result["draft_id"], result["draft_url"])
```

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

### MCP Connection Test (test_mcp_client.py)

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

Run the MCP connection test script. Expected output includes a success message, 11 available tools, and a passed draft creation test.

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

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

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

### Timerange class definition

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/time_util.md

Defines the Timerange class with start and duration fields in microseconds. Constructor takes start and duration integers.

```python
class Timerange:
    start: int   # µs
    duration: int  # µs

    def __init__(self, start: int, duration: int):
```

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

### create_quick_video

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/vectcut_client.md

Convenience helper that creates a draft and adds media. Returns the completed DraftInfo.

```APIDOC
## create_quick_video

### Description
Convenience helper that creates a draft and adds media. Returns the completed DraftInfo.

### Method
`create_quick_video(base_url: str = "http://localhost:9001", ...) -> DraftInfo`

### Parameters
- **base_url** (str) - Optional - Base URL of the VectCut server. Defaults to "http://localhost:9001".
- Additional parameters mirror `VectCutClient` adders (see source around line 450).

### Returns
- **DraftInfo** - Object containing `draft_id`, `draft_folder`, and `draft_url`.

### Example
```python
from vectcut_client import create_quick_video
draft = create_quick_video(base_url="http://localhost:9001", width=1080, height=1920)
```
```

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

### srt_tstamp() parsing example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/time_util.md

Parses an SRT timestamp "HH:MM:SS,mmm" into microseconds. Example: "00:00:02,500" becomes 2500000 µs.

```python
srt_tstamp("00:00:02,500")   # 2500000
```

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

### POST /api/preview_update

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Live-edits the draft content file and broadcasts an SSE 'edit' event. This endpoint allows real-time updates to text, font size, color, and transform properties.

```APIDOC
## [POST] /api/preview_update

### Description
Live-edits the draft content file and broadcasts an SSE 'edit' event. This endpoint allows real-time updates to text, font size, color, and transform properties.

### Method
POST

### Endpoint
/api/preview_update

### Parameters
#### Request Body
- (JSON body) - Required - Contains the edit details (e.g., text, font size, color, transform).

### Response
#### Success Response (200)
- Success message or status

#### Response Example
{
  "status": "ok"
}
```

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

### Basic usage flow

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/vectcut_client.md

Shows the basic client workflow: create client, create draft, add video and text, save draft, print URL, and close.

```python
from vectcut_client import VectCutClient

client = VectCutClient("http://localhost:9001")
draft = client.create_draft(width=1080, height=1920)   # DraftInfo
client.add_video(draft.draft_id, "https://example.com/video.mp4")
client.add_text(draft.draft_id, "Hello World", start=0, end=5)
result = client.save_draft(draft.draft_id)
print(result.draft_url)
client.close()
```

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

### capcut_add_sticker example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Adds decorative stickers or emojis.

```typescript
{
  "draft_id": "abc123",
  "sticker_url": "https://example.com/emoji.png",
  "start": 1,
  "end": 5,
  "position_x": 0.9,
  "position_y": 0.1,
  "scale": 0.2
}
```

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

### capcut_get_duration

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Gets duration and metadata of media files.

```APIDOC
## capcut_get_duration

### Description
Gets duration and metadata of media files.

### Parameters
- **url** (string) - Required - URL of the media file

### Request Example
```json
{
  "url": "https://example.com/video.mp4"
}
```
```

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

### get_capcut_windows()

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Finds CapCut/Jianying main windows via win32gui.EnumWindows. Returns a list of window information dictionaries.

```APIDOC
## get_capcut_windows()

### Description
Finds CapCut/Jianying main windows via win32gui.EnumWindows. Returns a list of window information dictionaries.

### Parameters
- None

### Returns
- (list) - List of dicts with keys: `hwnd`, `title`, `width`, `height`.
```

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

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

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

Uses the requests library to create a draft, add a background video, add segmented text with different colors, and save the draft. Demonstrates the API endpoints and JSON payloads.

```python
import requests

BASE_URL = "http://localhost:9001"

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

# 2. Add background video
requests.post(f"{BASE_URL}/add_video", json={
    "draft_id": draft_id,
    "video_url": "https://example.com/bg.mp4",
    "volume": 0.4
})

# 3. Add segmented text
segments = ["First text", "Second text", "Third text"]
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. Save draft
result = requests.post(f"{BASE_URL}/save_draft", json={
    "draft_id": draft_id
}).json()

print(f"Video generated: {result['output']['draft_url']}")
```

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

### VectCutClient.add_text

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/vectcut_client.md

Adds text to the draft with specified start and end times.

```APIDOC
## add_text

### Description
Adds text to the draft with specified start and end times.

### Method
`add_text(draft_id: str, text: str, start: float, end: float) -> bool`

### Parameters
- **draft_id** (str) - Required - The ID of the draft.
- **text** (str) - Required - The text content to add.
- **start** (float) - Required - Start time in seconds.
- **end** (float) - Required - End time in seconds.

### Returns
- **bool** - True if successful, False otherwise.

### Example
```python
client.add_text(draft.draft_id, "Hello World", start=0, end=5)
```
```

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

### capcut_save_draft example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Saves the draft to import into CapCut application.

```typescript
{
  "draft_id": "abc123"
}
```

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

### GET /api/active_draft

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the active draft information for a given project.

```APIDOC
## GET /api/active_draft

### Description
Retrieves the active draft information for a given project.

### Method
GET

### Endpoint
/api/active_draft

### Parameters
#### Query Parameters
- **project_name** (string) - Required - The project name
- **draft_folder** (string) - Required - The draft folder path

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **data** (object) - Contains `canvas`, `total_duration_sec`, `video_clips`, `text_clips`, `audio_clips`, `project_name`, `project_path`

#### Error Response
- **success** (boolean) - false
- **error** (string) - Error message

#### Response Example
{
  "success": true,
  "data": {
    "canvas": {},
    "total_duration_sec": 0,
    "video_clips": [],
    "text_clips": [],
    "audio_clips": [],
    "project_name": "example",
    "project_path": "example"
  }
}
```

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

### reload_capcut_desktop(project_name=None, delay=0.35)

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Hot-reloads CapCut Desktop: launches it if not running, navigates home, and clicks the project card. Returns a result dictionary.

```APIDOC
## reload_capcut_desktop(project_name=None, delay=0.35)

### Description
Hot-reloads CapCut Desktop: launches it if not running, navigates home, and clicks the project card. Returns a result dictionary.

### Parameters
- **project_name** (string) - Optional - Name of the project to reload.
- **delay** (float) - Optional - Delay in seconds before reload (default 0.35).

### Returns
- (dict) - Dictionary with keys: `success` (bool), `action` (string: "launched"|"reloaded"|"not_found"|"unsupported_platform"), `message` (string), `elapsed_seconds` (float).
```

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

### send_key_combo(key1, key2=None)

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Sends key presses, optionally with a modifier key.

```APIDOC
## send_key_combo(key1, key2=None)

### Description
Sends key presses, optionally with a modifier key.

### Parameters
- **key1** (string) - Required - First key.
- **key2** (string) - Optional - Second key (modifier).

### Returns
- None
```

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

### capcut_add_subtitle example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Imports subtitles from SRT format with custom styling.

```typescript
{
  "draft_id": "abc123",
  "srt_content": "1\n00:00:01,000 --> 00:00:03,000\nWelcome to my video",
  "font_size": 36,
  "font_color": "#FFFFFF",
  "background_enabled": true
}
```

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

### Create draft

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

Creates a 1080x1920 portrait project and returns a draft_id used in subsequent operations.

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

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

### capcut_add_audio example

Source: https://github.com/sun-guannan/vectcutapi/blob/main/mcp-server/README.md

Adds background music or sound effects with fade in/out.

```typescript
{
  "draft_id": "abc123",
  "audio_url": "https://example.com/music.mp3",
  "start": 0,
  "end": 30,
  "volume": 0.5,
  "fade_in": 2,
  "fade_out": 2
}
```

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

### click_client_coords(hwnd, x, y)

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Synthesizes a client-area click at the given coordinates.

```APIDOC
## click_client_coords(hwnd, x, y)

### Description
Synthesizes a client-area click at the given coordinates.

### Parameters
- **hwnd** (int) - Required - Window handle.
- **x** (int) - Required - X coordinate.
- **y** (int) - Required - Y coordinate.

### Returns
- None
```

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

### Audio_material.__init__

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/local_materials.md

Creates an audio material instance. Requires either a local file path or a remote URL. Optionally accepts a duration to skip ffprobe probing.

```APIDOC
## Audio_material.__init__

### Description
Creates an audio material instance. Requires either a local file path or a remote URL. Optionally accepts a duration to skip ffprobe probing.

### Method
Constructor

### Signature
```python
def __init__(self, path: Optional[str] = None, replace_path = None, material_name: Optional[str] = None,
             remote_url: Optional[str] = None, duration: Optional[float] = None):
```

### Parameters
- `path` (str) - Optional - Local file path; must exist if provided. Required if `remote_url` is not provided.
- `replace_path` (str) - Optional - Exported path override.
- `material_name` (str) - Optional - Material name; derived from URL basename when remote (e.g., `<name>.mp3`).
- `remote_url` (str) - Optional - Remote audio URL. Required if `path` is not provided.
- `duration` (float) - Optional - Duration in seconds; skips ffprobe when provided.

### Behavior
- Raises `ValueError` if both `path` and `remote_url` are missing.
- ffprobe audio path: rejects files containing a video stream (`ValueError("音频素材不应包含视频轨道")`), rejects files without an audio stream, reads stream/format duration. ffprobe failures raise `ValueError`.
- `has_audio_effect: bool = False` class attribute — set True by `Audio_segment.add_effect`; changes `check_flag` (3 vs 1) on export.
- `from_dict(data)` / `export_json()` — round-trip forms; exported JSON uses `name` (not `material_name`) and `type: "extract_music"`.

### Usage Example
```python
import pyJianYingDraft as draft

# Create a remote audio material without probing
mat = draft.Audio_material(
    remote_url="https://example.com/audio.mp3",
    material_name="audio.mp3",
    duration=10.0,  # skips ffprobe
)
```
```

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

### ImportedMediaTrack.__init__

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/pyJianYingDraft/template_mode.md

Initializes an ImportedMediaTrack from raw JSON data. Segments are ImportedMediaSegment objects.

```APIDOC
## `ImportedMediaTrack.__init__`

### Description
Initializes an ImportedMediaTrack from raw JSON data. Segments are ImportedMediaSegment objects.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **json_data** (Dict[str, Any]) - Required - Raw JSON data for the track.

### Request Example
```python
ImportedMediaTrack(json_data)
```

```

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

### GET /get_font_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of font types. Always uses the Jianying enum source.

```APIDOC
## GET /get_font_types

### Description
Retrieves the list of font types. Always uses the Jianying enum source.

### Method
GET

### Endpoint
/get_font_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### VectCutClient.__init__

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/vectcut_client.md

Initializes a VectCutClient instance with a base URL and timeout. The base URL points to a running capcut_server.py instance.

```APIDOC
## VectCutClient.__init__

### Description
Initializes a VectCutClient instance with a base URL and timeout. The base URL points to a running capcut_server.py instance.

### Method
Constructor

### Parameters
- `base_url` (str) - Optional - Default: `"http://localhost:9001"` - Server root (trailing `/` stripped)
- `timeout` (int) - Optional - Default: 120 - Request timeout in seconds

### Request Example
```python
client = VectCutClient(base_url="http://localhost:9001", timeout=120)
```

### Response
No return value.
```

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

### initialize

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Initializes the MCP connection, returning protocol version, capabilities, and server information.

```APIDOC
## initialize

### Description
Initializes the MCP connection, returning protocol version, capabilities, and server information.

### Method
initialize

### Response
#### Success Response
- **protocolVersion** (string) - `2024-11-05`
- **capabilities** (object) - Contains `tools` capability
- **serverInfo** (object) - `capcut-api` / `1.12.3`
```

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

### GET /get_mask_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of mask types. The enum source depends on the environment (CapCut or Jianying).

```APIDOC
## GET /get_mask_types

### Description
Retrieves the list of mask types. The enum source depends on the environment (CapCut or Jianying).

### Method
GET

### Endpoint
/get_mask_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### create_quick_video function signature

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/vectcut_client.md

Convenience helper that creates a draft and adds media. Parameters mirror client methods; returns completed DraftInfo or similar result. Exact optional parameters are in vectcut_client.py around line 450.

```python
def create_quick_video(base_url: str = "http://localhost:9001", ...):
```

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

### GET /get_transition_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of transition types. The enum source depends on the environment (CapCut or Jianying).

```APIDOC
## GET /get_transition_types

### Description
Retrieves the list of transition types. The enum source depends on the environment (CapCut or Jianying).

### Method
GET

### Endpoint
/get_transition_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### main() function

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/mcp_server.md

Reads stdin line by line, calls handle_request, prints non-None responses, and flushes. Logs startup info to stderr and terminates on EOF, EOFError, or KeyboardInterrupt.

```python
def main():
```

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

### Basic add_sticker_impl usage

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/add_sticker_impl.md

Adds a sticker to a resource by ID with start and end times. Requires the add_sticker_impl module.

```python
from add_sticker_impl import add_sticker_impl

res = add_sticker_impl(
    resource_id="7161529073773826048",
    start=0, end=5.0,
)
```

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

### GET|POST /list_projects

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Lists CapCut desktop projects from the default projects directory. Returns an empty list if the directory is missing.

```APIDOC
## GET|POST /list_projects

### Description
Lists CapCut desktop projects from the default projects directory. Returns an empty list if the directory is missing.

### Method
GET, POST

### Endpoint
/list_projects

### Response
#### Success Response (200)
- `count` (number) - Number of projects.
- `projects` (array) - List of projects.
  - `name` (string) - Project name.
  - `path` (string) - Project path.
  - `is_locked` (boolean) - Whether the project is locked.
  - `has_draft_content` (boolean) - Whether the project has draft content.
  - `modified_time` (string) - Last modified time.

#### Response Example
{
  "count": 2,
  "projects": [
    {
      "name": "Project1",
      "path": "C:\\...",
      "is_locked": false,
      "has_draft_content": true,
      "modified_time": "2023-01-01T00:00:00Z"
    }
  ]
}
```

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

### GET /get_text_outro_types

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/endpoints.md

Retrieves the list of text outro types. The enum source depends on the environment (CapCut or Jianying).

```APIDOC
## GET /get_text_outro_types

### Description
Retrieves the list of text outro types. The enum source depends on the environment (CapCut or Jianying).

### Method
GET

### Endpoint
/get_text_outro_types

### Response
#### Success Response (200)
- **success** (boolean) - Always true
- **output** (array) - List of objects with a `name` field

#### Response Example
{
  "success": true,
  "output": [
    {
      "name": "example"
    }
  ]
}
```

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

### Streaming preview events with requests

Source: https://github.com/sun-guannan/vectcutapi/blob/main/_autodocs/api-reference/web_preview.md

Streams Server-Sent Events from the /api/preview_events endpoint. Each data line is decoded and printed. Requires the server running at 127.0.0.1:9001.

```python
import requests

with requests.get("http://127.0.0.1:9001/api/preview_events", stream=True) as r:
    for line in r.iter_lines():
        if line.startswith(b"data:"):
            print(line[5:].decode())
```
Tokens:
Raw