### Install and Deploy VectCutAPI

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

This snippet outlines the steps to clone the VectCutAPI project, set up a virtual environment, install dependencies, configure the service, and start the HTTP API and MCP protocol servers. It requires Python 3.10+, Jianying or CapCut International, and FFmpeg.

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

# 3. Start the service
python capcut_server.py # Start the HTTP API server, default port: 9001

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

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

### Complete Workflow Example: Video Project Creation

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Demonstrates a full video project workflow, including creating a draft, adding various media elements (video, image, text, subtitles, audio), applying animations and keyframes, and finally saving and exporting the project. This example uses the `requests` library to interact with the API.

```python
import requests
import time

BASE_URL = "http://localhost:9001"

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

# 2. Add background video
requests.post(f"{BASE_URL}/add_video", json={
    "video_url": "https://example.com/background.mp4",
    "draft_id": draft_id,
    "start": 0, "end": 15,
    "volume": 0.5,
    "background_blur": 2
})

# 3. Add logo image
requests.post(f"{BASE_URL}/add_image", json={
    "image_url": "https://example.com/logo.png",
    "draft_id": draft_id,
    "start": 0, "end": 15,
    "transform_y": 0.7,
    "scale_x": 0.3, "scale_y": 0.3,
    "intro_animation": "fade_in"
})

# 4. Add title text with shadow
requests.post(f"{BASE_URL}/add_text", json={
    "text": "Product Launch 2024",
    "draft_id": draft_id,
    "start": 2, "end": 8,
    "font_size": 64,
    "font_color": "#FFD700",
    "shadow_enabled": True,
    "shadow_color": "#000000",
    "background_color": "#1E1E1E",
    "background_alpha": 0.8,
    "intro_animation": "zoom_in"
})

# 5. Add subtitles
requests.post(f"{BASE_URL}/add_subtitle", json={
    "srt": "./subtitles.srt",
    "draft_id": draft_id,
    "font_size": 6.0,
    "border_width": 2.0,
    "background_alpha": 0.7
})

# 6. Add background music
requests.post(f"{BASE_URL}/add_audio", json={
    "audio_url": "https://example.com/music.mp3",
    "draft_id": draft_id,
    "start": 0, "end": 15,
    "volume": 0.6
})

# 7. Add zoom animation with keyframes
requests.post(f"{BASE_URL}/add_video_keyframe", json={
    "draft_id": draft_id,
    "track_name": "main",
    "property_types": ["scale_x", "scale_y"],
    "times": [0, 5, 10, 15],
    "values": ["1.0", "1.3", "1.3", "1.0",
               "1.0", "1.3", "1.3", "1.0"]
})

# 8. Save and export
response = requests.post(f"{BASE_URL}/save_draft", json={
    "draft_id": draft_id
})
draft_url = response.json()["output"]["draft_url"]
print(f"Video project completed: {draft_url}")
```

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

### Install Dependencies for MCP Server

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

Installs necessary Python dependencies for the MCP server using pip. It assumes a virtual environment has already been created and activated.

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

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

### API Response Format Example (JSON)

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

Illustrates the expected JSON structure for API responses. It includes a success status, result data such as draft ID and URL, and information about features utilized in the request.

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

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

### Add Video Track using MCP Client

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

Demonstrates adding a video track to a draft project. This involves providing the video URL, its start and end times within the project, volume, and transformation settings.

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

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

### Test MCP Connection to VectCutAPI

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

This Python script verifies the connection to the VectCutAPI's MCP server. It checks if the server starts successfully, retrieves the available tools, and confirms that draft creation works as expected. Successful execution indicates proper MCP integration.

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

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

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

### Add Audio with Voice Effect (Python)

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an audio track to a draft with specified start and end times, volume, and voice effect. Dependencies include the 'requests' library. It takes audio URL, draft ID, timing, volume, effect type, and effect parameters as input.

```python
import requests

draft_id = "your_draft_id"
response = requests.post("http://localhost:9001/add_audio", json={
    "audio_url": "https://example.com/voice.mp3",
    "draft_id": draft_id,
    "start": 0,
    "end": 15,
    "volume": 1.0,
    "effect_type": "robot",  # Apply robot voice effect
    "effect_params": [80]     # Effect intensity parameter
})

if response.json()["success"]:
    print("Audio track added")
```

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

### Save Draft and Get Download URL

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Saves a project draft and generates a downloadable URL or cloud preview. This function requires a `draft_id` and uses a POST request to the `/save_draft` endpoint. It returns a success status and a `draft_url` upon successful saving.

```python
# Save draft and get download URL
response = requests.post("http://localhost:9001/save_draft", json={
    "draft_id": draft_id
})

result = response.json()
if result["success"]:
    draft_url = result["output"]["draft_url"]
    print(f"Draft saved successfully")
    print(f"Download draft: {draft_url}")
    print("Import this draft into CapCut/JianYing desktop app")
else:
    print(f"Error saving: {result['error']}")
```

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

### Create Draft API

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Initializes a new video project with specified dimensions.

```APIDOC
## POST /create_draft

### Description
Initializes a new video project with specified dimensions (width and height).

### Method
POST

### Endpoint
`/create_draft`

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

### Request Example
```json
{
  "width": 1080,
  "height": 1920
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the draft creation was successful.
- **output** (object) - Contains details of the created draft.
  - **draft_id** (string) - The unique identifier for the created draft.
  - **draft_url** (string) - A URL to preview the draft.

#### Response Example
```json
{
  "success": true,
  "output": {
    "draft_id": "draft_abc123",
    "draft_url": "http://localhost:9001/previews/draft_abc123.mp4"
  }
}
```

#### Error Response (400/500)
- **success** (boolean) - Always false.
- **error** (string) - A message describing the error.

#### Error Response Example
```json
{
  "success": false,
  "error": "Invalid dimensions provided."
}
```
```

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

### Get Video Duration

Source: https://github.com/sun-guannan/vectcutapi/blob/main/pattern/001-words-coze.md

Retrieves the duration of a video given its URL. This endpoint is part of the video editing capabilities.

```APIDOC
## POST /api/get_duration

### Description
Retrieves the duration of a video from a provided URL.

### Method
POST

### Endpoint
/api/get_duration

### Parameters
#### Query Parameters
- **apiID** (string) - Required - The API ID for authentication.
- **apiName** (string) - Required - The name of the API to call, expected to be 'get_duration'.
- **pluginID** (string) - Required - The ID of the plugin to use.
- **pluginName** (string) - Required - The name of the plugin, e.g., '视频剪辑_剪映草稿助手'.
- **pluginVersion** (string) - Optional - The version of the plugin.
- **tips** (string) - Optional - Additional tips or parameters.
- **outDocLink** (string) - Optional - A link to documentation.

#### Request Body
- **url** (string) - Required - The URL of the video for which to get the duration.

### Request Example
```json
{
  "url": "your_video_url_here"
}
```

### Response
#### Success Response (200)
- **duration** (float) - The duration of the video in seconds.
- **video_url** (string) - The processed video URL (if applicable).
- **success** (boolean) - Indicates if the operation was successful.
- **error** (string) - Error message if the operation failed.

#### Response Example
```json
{
  "output": {
    "duration": 120.5,
    "video_url": "processed_video_url"
  },
  "purchase_link": "purchase_link_if_any",
  "success": true,
  "error": null
}
```
```

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

### Complete Workflow using MCP Protocol

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

This Python code illustrates a comprehensive video editing workflow using the MCP Protocol client. It covers creating a new project, adding a background video, adding title text with styling, applying keyframe animations to video properties, and saving the final project. It requires an initialized 'mcp_client'.

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

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Retrieves the duration of a video file, useful for timeline planning and synchronization.

```APIDOC
## GET /get_video_duration

### Description
Retrieves the duration of a video file, typically used for planning and synchronization purposes within the editing process.

### Method
GET

### Endpoint
/get_video_duration

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

### Request Example
```
GET /get_video_duration?video_url=https://example.com/my_video.mp4
```

### Response
#### Success Response (200)
- **duration** (number) - The duration of the video in seconds.

#### Response Example
```json
{
    "duration": 60.5
}
```
```

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

### Create Draft API

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Initializes a new video project draft with specified dimensions.

```APIDOC
## Create Draft

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

### Method
POST

### Endpoint
`/create_draft`

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

### Request Example
```json
{
  "width": 1080,
  "height": 1920
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the draft was created successfully.
- **output** (object) - Contains the draft ID.
  - **draft_id** (string) - The unique identifier for the newly created draft.

#### Response Example
```json
{
  "success": true,
  "output": {
    "draft_id": "draft_xyz789"
  }
}
```
```

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

### Get Video Duration

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Retrieves the duration of a video from a given URL using the MCP client.

```APIDOC
## Get Video Duration

### Description
Retrieves the duration of a video from a given URL using the MCP client.

### Method
MCP Client Tool Call

### Endpoint
`mcp_client.call_tool("get_video_duration", { ... })

### Parameters
#### Request Body
- **video_url** (string) - Required - The URL of the video.

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

### Response
#### Success Response (200)
- **duration** (number) - The duration of the video in seconds.

#### Response Example
```json
{
  "result": {
    "duration": 120.5
  }
}
```
```

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

### Create Video Draft with Python

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Initializes a new video project with specified dimensions using the VectCutAPI. Supports both HTTP POST requests and MCP protocol calls. Requires `requests` library for HTTP. Outputs a unique draft ID and a preview URL upon success.

```python
import requests

# HTTP API: Create a 1080x1920 portrait video project
response = requests.post("http://localhost:9001/create_draft", json={
    "width": 1080,
    "height": 1920
})

result = response.json()
if result["success"]:
    draft_id = result["output"]["draft_id"]
    draft_url = result["output"]["draft_url"]
    print(f"Created draft {draft_id}")
    print(f"Preview at: {draft_url}")
else:
    print(f"Error: {result['error']}")

# MCP Protocol: Create draft via Model Context Protocol
mcp_result = mcp_client.call_tool("create_draft", {
    "width": 1920,
    "height": 1080  # Landscape format
})
draft_id = mcp_result["result"]["draft_id"]
```

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

### Add Audio with Voice Effect

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an audio track to a draft, with options to specify start and end times, volume, and apply voice effects.

```APIDOC
## POST /add_audio

### Description
Adds an audio track to a draft with specified URL, timing, volume, and voice effects.

### Method
POST

### Endpoint
/add_audio

### Parameters
#### Request Body
- **audio_url** (string) - Required - URL of the audio file.
- **draft_id** (string) - Required - Identifier for the draft.
- **start** (number) - Required - Start time in seconds.
- **end** (number) - Required - End time in seconds.
- **volume** (number) - Optional - Volume level (0.0 to 1.0).
- **effect_type** (string) - Optional - Type of voice effect (e.g., "robot").
- **effect_params** (array) - Optional - Parameters for the voice effect.

### Request Example
```json
{
    "audio_url": "https://example.com/voice.mp3",
    "draft_id": "your_draft_id",
    "start": 0,
    "end": 15,
    "volume": 1.0,
    "effect_type": "robot",
    "effect_params": [80]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
    "success": true
}
```
```

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

### Add Video Material using VectCutAPI (Python)

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

This Python script demonstrates how to add background video material to a project using the VectCutAPI's HTTP interface. It sends a POST request to the '/add_video' endpoint with parameters like video URL, start/end times, volume, and transition effect. The response contains the result of the video addition operation.

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

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

### Create Video Draft using MCP Client

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

Demonstrates how to initiate a new video editing project (draft) using the MCP client. It specifies the dimensions for the draft.

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

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

### POST /add_text

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

Adds text to a video project with specified styling and timing.

```APIDOC
## POST /add_text

### Description
Adds text to a video project with specified styling and timing.

### Method
POST

### Endpoint
/add_text

### Parameters
#### Request Body
- **text** (string) - Required - The content of the text to add.
- **start** (integer) - Required - The start time (in seconds) for the text display.
- **end** (integer) - Required - The end time (in seconds) for the text display.
- **font** (string) - Optional - The font family for the text.
- **font_color** (string) - Optional - The color of the font (e.g., "#FFD700").
- **font_size** (integer) - Optional - The size of the font.
- **shadow_enabled** (boolean) - Optional - Whether to enable text shadow.
- **background_color** (string) - Optional - The background color for the text (e.g., "#000000").

### Request Example
```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"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the result of the text addition operation.

#### Response Example
```json
{
    "result": "Text added successfully"
}
```
```

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

### Get Video Duration using MCP Protocol

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Retrieves the duration of a video using the MCP client. It takes a video URL as input and returns the duration in seconds. Ensure the MCP client is properly initialized.

```python
result = mcp_client.call_tool("get_video_duration", {
    "video_url": "https://example.com/video.mp4"
})
duration = result["result"]["duration"]
print(f"Video duration: {duration} seconds")
```

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

### Add Audio Endpoint

Source: https://github.com/sun-guannan/vectcutapi/blob/main/pattern/001-words-coze.md

This endpoint allows you to add audio to a video project. You can specify various parameters to control the audio's source, playback, and integration into the project's timeline.

```APIDOC
## POST /add_audio

### Description
Adds an audio track to the video project. This endpoint supports detailed customization of audio parameters.

### Method
POST

### Endpoint
/add_audio

### Parameters
#### Query Parameters
- **audio_url** (string) - Required - The URL or path to the audio file.
- **speed** (float) - Optional - Speed multiplier for audio playback. Default is 1.
- **track_name** (string) - Optional - Name for the audio track.
- **volume** (float) - Optional - Volume level, between 0 and 1. Default is 1.
- **end** (float) - Optional - End time for trimming the audio source.
- **start** (float) - Optional - Start time for trimming the audio source. Default is 0.
- **target_start** (float) - Optional - The desired start time for the audio in the project timeline.
- **draft_folder** (string) - Optional - Path to the draft folder. Default is `C:\Users\Administrator\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft`.
- **draft_id** (string) - Optional - If continuing an existing draft, provide its ID.
- **duration** (float) - Optional - Duration of the source material in seconds. Specifying this can improve performance.
- **effect_params** (list of float) - Optional - Parameters for audio effects.
- **effect_type** (string) - Optional - Name of the audio effect to apply.

### Request Example
```json
{
  "audio_url": "http://example.com/audio.mp3",
  "speed": 1.2,
  "volume": 0.8,
  "start": 10.5,
  "end": 30.0,
  "target_start": 5.0,
  "draft_folder": "/path/to/drafts",
  "draft_id": "draft_12345",
  "duration": 60.0,
  "effect_type": "reverb",
  "effect_params": [0.5, 0.7]
}
```

### Response
#### Success Response (200)
- **purchase_link** (string) - Link to purchase if applicable.
- **success** (boolean) - Indicates if the operation was successful.
- **error** (string) - Error message if `success` is false.
- **output** (object) - Contains details about the updated draft.
  - **draft_id** (string) - The ID of the draft.
  - **draft_url** (string) - URL to the updated draft.

#### Response Example
```json
{
  "purchase_link": null,
  "success": true,
  "error": null,
  "output": {
    "draft_id": "draft_abcde",
    "draft_url": "http://example.com/drafts/draft_abcde"
  }
}
```
```

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

### Configure MCP Client for VectCutAPI

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

This JSON configuration is used for setting up the MCP client to connect to VectCutAPI. It specifies the command to run the MCP server, its arguments, working directory, and environment variables. This allows for seamless integration with the VectCutAPI's MCP protocol.

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

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

### Configure MCP Server

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

Sets up the MCP server configuration by defining connection details and execution parameters in a JSON file. This includes the command to run the server and its working directory.

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

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

### Add Video Keyframes

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Creates property animations using keyframes to define smooth transitions for properties like opacity, scale, and position.

```APIDOC
## POST /add_video_keyframe

### Description
Adds keyframes to define animations for video properties over time, supporting single property changes or batch updates.

### Method
POST

### Endpoint
/add_video_keyframe

### Parameters
#### Request Body
- **draft_id** (string) - Required - Identifier for the draft.
- **track_name** (string) - Required - Name of the track to animate.
- **property_type** (string) - Required (for single keyframe) - Type of property to animate (e.g., "alpha", "scale_x").
- **property_types** (array) - Required (for batch keyframes) - Array of property types to animate.
- **time** (number) - Required (for single keyframe) - Time in seconds for the keyframe.
- **times** (array) - Required (for batch keyframes) - Array of times in seconds for the keyframes.
- **value** (string) - Required (for single keyframe) - Value for the property at the specified time.
- **values** (array) - Required (for batch keyframes) - Array of values for the properties at the specified times.

### Request Example (Single Keyframe)
```json
{
    "draft_id": "your_draft_id",
    "track_name": "main",
    "property_type": "alpha",
    "time": 2.0,
    "value": "0.5"
}
```

### Request Example (Batch Keyframes - Zoom and Fade)
```json
{
    "draft_id": "your_draft_id",
    "track_name": "main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4, 6],
    "values": [
        "1.0", "1.5", "1.2", "1.0",  // scale_x values
        "1.0", "1.5", "1.2", "1.0",  // scale_y values
        "0.0", "1.0", "1.0", "0.0"   // alpha values (fade in/out)
    ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
    "success": true
}
```
```

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

### Add Video Keyframes for Animation (Python)

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Creates property animations for video elements using keyframes. Requires the 'requests' library. Supports single keyframes or batch keyframes for properties like alpha, scale, and position, specifying property types, times, and values.

```python
import requests

draft_id = "your_draft_id"
# Single keyframe: Set opacity at 2 seconds
response = requests.post("http://localhost:9001/add_video_keyframe", json={
    "draft_id": draft_id,
    "track_name": "main",
    "property_type": "alpha",
    "time": 2.0,
    "value": "0.5"  # 50% opacity
})

# Batch keyframes: Create zoom and fade animation
response = requests.post("http://localhost:9001/add_video_keyframe", json={
    "draft_id": draft_id,
    "track_name": "main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4, 6],
    "values": [
        "1.0", "1.5", "1.2", "1.0",  # scale_x values
        "1.0", "1.5", "1.2", "1.0",  # scale_y values
        "0.0", "1.0", "1.0", "0.0"   # alpha values (fade in/out)
    ]
})

# Position animation: Pan across screen
response = requests.post("http://localhost:9001/add_video_keyframe", json={
    "draft_id": draft_id,
    "track_name": "main",
    "property_types": ["position_x", "position_y"],
    "times": [0, 3, 6],
    "values": [
        "-0.5", "0.0", "0.5",  # position_x: left to center to right
        "0.0", "0.0", "0.0"     # position_y: stays centered
    ]
})

if response.json()["success"]:
    print("Keyframe animation created")
```

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

### MCP Protocol - Create Draft

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

Creates a new video draft with specified dimensions.

```APIDOC
## MCP Protocol - Create Draft

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

### Method
POST (via mcp_client.call_tool)

### Endpoint
create_draft

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

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

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

#### Response Example
```json
{
    "result": {
        "draft_id": "some_draft_id"
    }
}
```
```

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

### Add Animated Stickers (Python)

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Places animated stickers onto the video with control over position, scale, rotation, and alpha. Requires the 'requests' library. Inputs include sticker ID, draft ID, timing, transform/scale/rotation parameters, alpha, flip options, and track name.

```python
import requests

draft_id = "your_draft_id"
response = requests.post("http://localhost:9001/add_sticker", json={
    "sticker_id": "resource_123456",  # Sticker resource ID
    "draft_id": draft_id,
    "start": 2,
    "end": 8,
    "transform_x": 0.3,   # Right side
    "transform_y": 0.4,   # Upper area
    "scale_x": 1.2,
    "scale_y": 1.2,
    "rotation": 15.0,     # Rotate 15 degrees
    "alpha": 0.9,         # 90% opacity
    "flip_horizontal": False,
    "flip_vertical": False,
    "track_name": "sticker_main"
})

if response.json()["success"]:
    print("Sticker added")
```

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

### Add Text with Styling using MCP Client

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

Adds text to a video draft with advanced styling options, including shadow effects and background colors with transparency. This allows for more sophisticated text presentations.

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

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

### MCP Protocol - Add Video

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

Adds a video to a draft with specified timing and volume.

```APIDOC
## MCP Protocol - Add Video

### Description
Adds a video to a draft with specified timing and volume.

### Method
POST (via mcp_client.call_tool)

### Endpoint
add_video

### Parameters
#### Request Body
- **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 (0.0 to 1.0).

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

### Response
#### Success Response (200)
- **result** (object) - Indicates the success of the operation.

#### Response Example
```json
{
    "result": "Video added successfully"
}
```
```

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

### MCP Protocol - Save Draft

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

Saves the current video draft.

```APIDOC
## MCP Protocol - Save Draft

### Description
Saves the current video draft. A folder starting with `dfd_` will be generated, which can be copied to the CapCut drafts directory.

### Method
POST (via mcp_client.call_tool)

### Endpoint
save_draft

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

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

### Response
#### Success Response (200)
- **result.draft_url** (string) - The URL or path to the saved draft.

#### Response Example
```json
{
    "result": {
        "draft_url": "path/to/saved/draft"
    }
}
```
```

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

### Add Text using VectCutAPI

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

This snippet demonstrates how to add text to a project using the VectCutAPI. It sends a POST request to the 'add_text' endpoint with various parameters specifying the text content, its position, font, and colors. Dependencies include the 'requests' library.

```python
import requests

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

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

### Advanced Text Effects using MCP Protocol

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

This Python snippet demonstrates applying advanced text styling, specifically multi-style colored text, within a video project using the MCP Protocol. It utilizes the 'add_text' tool with an array of 'text_styles' to define different colors for segments of the text. Assumes 'draft_id' is already defined.

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

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an image to the project draft, allowing for positioning, scaling, and animations.

```APIDOC
## Add Image

### Description
Adds an image to the project draft, allowing for positioning, scaling, and animations.

### Method
POST

### Endpoint
`/add_image`

### Parameters
#### Request Body
- **draft_id** (string) - Required - The ID of the draft to add the image to.
- **image_url** (string) - Required - The URL of the image to add.
- **start** (number) - Required - The start time of the image display in seconds.
- **end** (number) - Required - The end time of the image display in seconds.
- **transform_y** (number) - Optional - Vertical position adjustment.
- **scale_x** (number) - Optional - Horizontal scaling factor.
- **scale_y** (number) - Optional - Vertical scaling factor.
- **intro_animation** (string) - Optional - Type of intro animation (e.g., "fade_in").

### Request Example
```json
{
  "draft_id": "draft_xyz789",
  "image_url": "https://example.com/logo.png",
  "start": 0,
  "end": 15,
  "transform_y": 0.7,
  "scale_x": 0.3,
  "scale_y": 0.3,
  "intro_animation": "fade_in"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the image was added successfully.

#### Response Example
```json
{
  "success": true
}
```
```

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

### Add Image with Animations and Mask (Python)

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an image to a draft with timing, transformations, entrance/exit animations, transitions, and masking. Requires the 'requests' library. Inputs include image URL, draft ID, timing, transformation parameters, animation details, transition type, mask type, and background blur.

```python
import requests

draft_id = "your_draft_id"
response = requests.post("http://localhost:9001/add_image", json={
    "image_url": "https://example.com/photo.jpg",
    "draft_id": draft_id,
    "start": 5,
    "end": 10,
    "transform_x": 0,
    "transform_y": 0,
    "scale_x": 1.5,
    "scale_y": 1.5,
    "intro_animation": "zoom_in",
    "intro_animation_duration": 0.8,
    "outro_animation": "fade_out",
    "outro_animation_duration": 0.5,
    "transition": "dissolve",
    "transition_duration": 1.0,
    "mask_type": "heart",
    "mask_size": 0.9,
    "background_blur": 2  # Medium blur
})

if response.json()["success"]:
    print("Image added with animations")
```

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

### Add Audio API

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an audio track to the project draft, with options for duration and volume.

```APIDOC
## Add Audio

### Description
Adds an audio track to the project draft, with options for duration and volume.

### Method
POST

### Endpoint
`/add_audio`

### Parameters
#### Request Body
- **draft_id** (string) - Required - The ID of the draft to add the audio to.
- **audio_url** (string) - Required - The URL of the audio file.
- **start** (number) - Required - The start time of the audio track in seconds.
- **end** (number) - Required - The end time of the audio track in seconds.
- **volume** (number) - Optional - The volume of the audio track (0.0 to 1.0).

### Request Example
```json
{
  "draft_id": "draft_xyz789",
  "audio_url": "https://example.com/music.mp3",
  "start": 0,
  "end": 15,
  "volume": 0.6
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the audio was added successfully.

#### Response Example
```json
{
  "success": true
}
```
```

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

### Run MCP Test Client

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

Executes the test client script for the MCP server. This is used for validating the functionality and integration of the MCP server and its tools.

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

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

### Add Audio Track with Python

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds an audio track to a video draft, supporting volume control, speed adjustment, and fade effects. Requires the `requests` library and accepts an audio URL, draft ID, timing, and track name. Outputs success or error messages.

```python
# Add background music with fade effect
response = requests.post("http://localhost:9001/add_audio", json={
    "audio_url": "https://example.com/music.mp3",
    "draft_id": draft_id,
    "start": 0,
    "end": 30,
    "target_start": 0,
    "volume": 0.7,
    "speed": 1.0,
    "track_name": "background_music"
})
```

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

### Save Draft API

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Saves the current project draft and generates a downloadable URL or cloud preview.

```APIDOC
## Save Draft

### Description
Saves the project and generates a downloadable draft file or cloud preview.

### Method
POST

### Endpoint
`/save_draft`

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

### Request Example
```json
{
  "draft_id": "draft_abc123"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the draft was saved successfully.
- **output** (object) - Contains the draft URL if successful.
  - **draft_url** (string) - The URL to download the draft.

#### Response Example
```json
{
  "success": true,
  "output": {
    "draft_url": "https://example.com/drafts/draft_abc123.zip"
  }
}
```
```

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

### Add Text to Video Draft using MCP Client

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

Shows how to add text elements to a video draft using the MCP client. This includes specifying the text content, its duration on the timeline, and styling options like font size and color.

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

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

### Add Text with Styling in Python

Source: https://context7.com/sun-guannan/vectcutapi/llms.txt

Adds text elements to a video draft with extensive styling options including multi-style coloring, shadows, backgrounds, and animations. Accepts text content, draft ID, timing, font details, and style configurations. Uses HTTP POST requests and requires the `requests` library.

```python
# Add text with shadow and rounded background
response = requests.post("http://localhost:9001/add_text", json={
    "text": "Welcome to AI Video",
    "draft_id": draft_id,
    "start": 1,
    "end": 6,
    "font": "思源黑体",
    "font_size": 48,
    "font_color": "#FFFFFF",
    "transform_x": 0,
    "transform_y": -0.5,  # Upper half of screen
    # Shadow configuration
    "shadow_enabled": True,
    "shadow_color": "#000000",
    "shadow_alpha": 0.8,
    "shadow_angle": -45,
    "shadow_distance": 8,
    "shadow_smoothing": 0.2,
    # Background configuration
    "background_color": "#FF6B6B",
    "background_alpha": 0.9,
    "background_round_radius": 25,
    "background_height": 0.15,
    "background_width": 0.15,
    # Animation
    "intro_animation": "fade_in",
    "outro_animation": "fade_out"
})

# Multi-style colored text
response = requests.post("http://localhost:9001/add_text", json={
    "text": "Colorful Video Title",
    "draft_id": draft_id,
    "start": 0,
    "end": 5,
    "font_size": 56,
    "text_styles": [
        {
            "start": 0, "end": 8,
            "style": {"color": "#FF0000", "size": 56, "bold": True}
        },
        {
            "start": 8, "end": 13,
            "style": {"color": "#00FF00", "size": 60, "italic": True}
        },
        {
            "start": 13, "end": 19,
            "style": {"color": "#0000FF", "size": 56}
        }
    ]
})
```