sun-guannan / vectcut-api

Skill Content

---
name: vectcut-api
description: VectCutAPI is a powerful cloud-based video editing API tool that provides programmatic control over CapCut/JianYing (剪映) for professional video editing. Use this skill when users need to: (1) Create video draft projects programmatically, (2) Add video/audio/image materials with precise control, (3) Add text, subtitles, and captions, (4) Apply effects, transitions, and animations, (5) Add keyframe animations, (6) Process videos in batch, (7) Generate AI-powered videos, (8) Integrate with n8n workflows, (9) Build MCP video editing agents. The API supports HTTP REST and MCP protocols, works with both CapCut (international) and JianYing (China), and provides web preview without downloading.
---

# VectCutAPI 视频剪辑 API

## 概述

VectCutAPI 是一款强大的云端视频剪辑 API 工具，通过编程方式控制剪映/CapCut 进行专业视频编辑。它填补了 AI 生成素材与专业视频编辑之间的空白，提供精确的编辑控制能力。

### 核心优势

1. **双协议支持** - HTTP REST API 和 MCP 协议
2. **实时预览** - 网页预览无需下载
3. **可二次编辑** - 导入剪映/CapCut 精修
4. **云端处理** - 全云端操作生成视频

### 系统要求

- Python 3.10+
- 剪映 或 CapCut 国际版
- FFmpeg (可选，用于某些视频处理)

### 快速启动

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

# 配置文件
cp config.json.example config.json

# 启动服务
python capcut_server.py  # HTTP API 服务器 (端口: 9001)
python mcp_server.py     # MCP 协议服务器
```

## 工作流程

### 标准视频制作流程

```
1. 创建草稿 (create_draft)
   - 设置分辨率: 1080x1920 (竖屏) / 1920x1080 (横屏) / 1080x1080 (方形)
   - 获取 draft_id

2. 添加素材轨道
   - add_video: 添加视频轨道
   - add_audio: 添加音频轨道
   - add_image: 添加图片素材

3. 添加文字元素
   - add_text: 添加标题、说明文字
   - add_subtitle: 导入 SRT 字幕文件

4. 应用特效
   - add_effect: 添加视频特效
   - add_sticker: 添加贴纸素材
   - add_video_keyframe: 添加关键帧动画

5. 保存草稿
   - save_draft: 生成可导入剪映的草稿文件
```

### AI 视频生成工作流

```
AI 文案生成
    ↓
TTS 文字转语音 → audio_url
    ↓
图生视频 → video_url
    ↓
VectCutAPI 组合草稿
    ↓
导出或二次编辑
```

### 批量视频处理

使用 `auto_video_editor.py` 处理 Excel 表格驱动的批量视频制作。

## API 接口

### 核心操作

| 接口 | 方法 | 功能 |
|------|------|------|
| `/create_draft` | POST | 创建新草稿项目 |
| `/save_draft` | POST | 保存草稿并生成 URL |
| `/query_draft_status` | POST | 查询草稿状态 |
| `/query_script` | POST | 查询草稿脚本内容 |
| `/generate_draft_url` | POST | 生成草稿预览 URL |

### 素材添加

| 接口 | 方法 | 功能 |
|------|------|------|
| `/add_video` | POST | 添加视频轨道 |
| `/add_audio` | POST | 添加音频轨道 |
| `/add_image` | POST | 添加图片素材 |
| `/add_text` | POST | 添加文字元素 |
| `/add_subtitle` | POST | 添加 SRT 字幕 |
| `/add_sticker` | POST | 添加贴纸 |
| `/add_effect` | POST | 添加视频特效 |
| `/add_video_keyframe` | POST | 添加关键帧动画 |

### 查询接口 (GET)

| 接口 | 功能 |
|------|------|
| `/get_intro_animation_types` | 获取入场动画类型 |
| `/get_outro_animation_types` | 获取出场动画类型 |
| `/get_transition_types` | 获取转场效果类型 |
| `/get_mask_types` | 获取蒙版类型列表 |
| `/get_audio_effect_types` | 获取音频特效类型 |
| `/get_font_types` | 获取字体类型列表 |
| `/get_video_scene_effect_types` | 获取场景特效类型 |

## 使用示例

### 创建竖屏视频草稿

```python
import requests

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

# 2. 添加背景视频
requests.post("http://localhost:9001/add_video", json={
    "draft_id": draft_id,
    "video_url": "https://example.com/background.mp4",
    "start": 0,
    "end": 10,
    "volume": 0.6
})

# 3. 添加标题文字
requests.post("http://localhost:9001/add_text", json={
    "draft_id": draft_id,
    "text": "欢迎使用 VectCutAPI",
    "start": 1,
    "end": 5,
    "font_size": 56,
    "font_color": "#FFD700",
    "shadow_enabled": True,
    "background_color": "#000000"
})

# 4. 保存草稿
response = requests.post("http://localhost:9001/save_draft", json={
    "draft_id": draft_id
})
draft_url = response.json()["output"]["draft_url"]
print(f"草稿已保存: {draft_url}")
```

### 添加转场效果

```python
requests.post("http://localhost:9001/add_video", json={
    "draft_id": draft_id,
    "video_url": "https://example.com/video2.mp4",
    "transition": "fade_in",           # 转场类型
    "transition_duration": 0.5,        # 转场时长(秒)
    "target_start": 10                 # 在时间轴 10 秒处开始
})
```

### 添加关键帧动画

```python
requests.post("http://localhost:9001/add_video_keyframe", json={
    "draft_id": draft_id,
    "track_name": "video_main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],          # 关键帧时间点
    "values": ["1.0", "1.2", "0.8"]  # 对应属性值
})
```

### 添加 SRT 字幕

```python
requests.post("http://localhost:9001/add_subtitle", json={
    "draft_id": draft_id,
    "srt_url": "https://example.com/subtitles.srt",
    "font_size": 32,
    "font_color": "#FFFFFF",
    "background_alpha": 0.7
})
```

## MCP 协议集成

VectCutAPI 支持 MCP (Model Context Protocol) 协议，可直接由 AI Agent 调用。

### MCP 工具列表

| 工具名称 | 功能描述 |
|---------|----------|
| `create_draft` | 创建新的视频草稿项目 |
| `add_video` | 添加视频到草稿 |
| `add_audio` | 添加音频到草稿 |
| `add_image` | 添加图片素材 |
| `add_text` | 添加文字元素 |
| `add_subtitle` | 添加字幕文件 |
| `add_effect` | 添加视觉特效 |
| `add_sticker` | 添加贴纸元素 |
| `add_video_keyframe` | 添加关键帧动画 |
| `get_video_duration` | 获取视频时长 |
| `save_draft` | 保存草稿项目 |

### MCP 客户端配置

创建 `mcp_config.json`:

```json
{
  "mcpServers": {
    "vectcut-api": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "H:/ComfyUI/web/VectCutAPI",
      "env": {
        "PYTHONPATH": "H:/ComfyUI/web/VectCutAPI",
        "DEBUG": "0"
      }
    }
  }
}
```

## 参数说明

### 视频参数 (add_video)

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `draft_id` | string | 必需 | 草稿 ID |
| `video_url` | string | 必需 | 视频 URL |
| `start` | float | 0 | 视频开始时间(秒) |
| `end` | float | 0 | 视频结束时间(秒) |
| `target_start` | float | 0 | 在时间轴上的开始时间 |
| `speed` | float | 1.0 | 播放速度 |
| `volume` | float | 1.0 | 音量 (0-1) |
| `scale_x/scale_y` | float | 1.0 | 缩放比例 |
| `transform_x/transform_y` | float | 0 | 位置偏移 |
| `transition` | string | - | 转场类型 |
| `transition_duration` | float | 0.5 | 转场时长(秒) |
| `mask_type` | string | - | 蒙版类型 |
| `background_blur` | int | - | 背景模糊级别(1-4) |

### 文字参数 (add_text)

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `text` | string | 必需 | 文字内容 |
| `start` | float | 必需 | 开始时间 |
| `end` | float | 必需 | 结束时间 |
| `font` | string | "思源黑体" | 字体名称 |
| `font_size` | int | 32 | 字体大小 |
| `font_color` | string | "#FFFFFF" | 字体颜色 (HEX) |
| `stroke_enabled` | bool | False | 是否启用描边 |
| `stroke_color` | string | "#FFFFFF" | 描边颜色 |
| `stroke_width` | float | 2.0 | 描边宽度 |
| `shadow_enabled` | bool | False | 是否启用阴影 |
| `shadow_color` | string | "#000000" | 阴影颜色 |
| `background_color` | string | - | 背景颜色 |
| `background_alpha` | float | 1.0 | 背景透明度 |
| `text_styles` | array | - | 多样式文字 (见下方) |

### 多样式文字 (text_styles)

```python
"text_styles": [
    {"start": 0, "end": 2, "font_color": "#FF6B6B"},
    {"start": 2, "end": 4, "font_color": "#4ECDC4"},
    {"start": 4, "end": 6, "font_color": "#45B7D1"}
]
```

## 配置文件

### config.json 结构

```json
{
  "is_capcut_env": true,
  "draft_domain": "https://www.capcutapi.top",
  "port": 9001,
  "preview_router": "/draft/downloader",
  "is_upload_draft": false,
  "oss_config": {
    "bucket_name": "your-bucket",
    "access_key_id": "your-key-id",
    "access_key_secret": "your-secret",
    "endpoint": "https://your-endpoint.aliyuncs.com"
  }
}
```

## 高级功能

### 批量视频处理

使用 `auto_video_editor.py` 进行 Excel 驱动的批量处理：

```python
python auto_video_editor.py input.xlsx
```

Excel 表格格式:
| 视频标题 | 二段文案 | 开头素材 | 结尾素材 | 封面素材 |
|---------|---------|---------|---------|---------|
| 产品介绍 | ... | video1.mp4 | video2.mp4 | image.png |

### n8n 工作流集成

项目包含多个预配置的 n8n 工作流：

- `text-to-video-with-animation.json` - 文字转视频工作流
- `auto-video-mixing.json` - 自动视频混剪
- `form-upload-processing.json` - 表单上传处理

## 资源

### scripts/

可执行脚本，用于 VectCutAPI 操作。

- **vectcut_client.py** - Python 客户端封装库

### references/

参考文档和指南。

- **api_reference.md** - 完整 API 接口参考
- **workflows.md** - 工作流示例和最佳实践
- **animation_types.md** - 动画类型参考
- **transition_types.md** - 转场效果类型参考

### assets/examples/

示例代码和模板。

- **basic_video.py** - 基础视频制作示例
- **text_animation.py** - 文字动画示例
- **subtitle_import.py** - 字幕导入示例
- **batch_processing.py** - 批量处理示例

## 常见问题

### 草稿文件位置

调用 `save_draft` 后会在当前目录生成 `dfd_` 开头的文件夹，将其复制到剪映/CapCut 草稿目录即可。

### 支持的视频格式

- MP4 (推荐)
- MOV
- AVI
- MKV

### 支持的图片格式

- PNG (推荐，支持透明)
- JPG/JPEG
- WebP

### 支持的音频格式

- MP3 (推荐)
- AAC
- WAV
- M4A

## 项目信息

- **GitHub**: https://github.com/sun-guannan/VectCutAPI
- **在线体验**: https://www.vectcut.com
- **开源协议**: Apache License 2.0
- **Star 数量**: 800+