vectcut-api

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+