sun-guannan/vectcut-skill/skill

VectCutAPI 视频剪辑 API

概述

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

核心优势

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

系统要求

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

快速启动

# 安装依赖
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 | 获取场景特效类型 |

使用示例

创建竖屏视频草稿

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

添加转场效果

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 秒处开始
})

添加关键帧动画

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 字幕

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:

{
  "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)

"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 结构

{
  "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 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+