# Skill

> VectCutAPI 视频剪辑 API

- Skill: `sun-guannan/skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add sun-guannan/skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sun-guannan/skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: sun-guannan (https://skillmd.com/u/sun-guannan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sun-guannan/skill

---


# 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+