用 Python 把剪映变成流水线：CapCutAPI 入门与实战
“剪映还能这样玩？”——如果你刚拿到一段几十分钟的原始素材，却要在一天内剪出 30 条短视频，你会问的第一个问题就是：有没有办法让剪映自己动起来？
CapCutAPI 的回答是：可以，而且只需要几十行 Python 代码。
本文能帮你解决什么？
| 典型场景 | 读完本文你将获得 |
|---|---|
| 手里有一堆横屏素材，想批量转成竖屏并加字幕 | 完整的脚本模板 |
| 想远程调用剪映功能，让后台自动生成草稿 | 可用的 HTTP 接口清单 |
| 公司要求统一片头、水印、转场，不想每次手动点 | 自动化配置样例 |
| 担心踩坑：版本、路径、依赖、中文编码 | 逐一拆解的避坑指南 |
1. CapCutAPI 到底是什么？
一句话：它把剪映（或国际版 CapCut）的草稿文件抽象成 JSON，再用 Python 提供增删改查的 API，最后把改好的草稿扔回剪映即可看到成品。
核心思路拆成三步：
-
解析草稿：剪映每打开一个项目，都会在本地生成一个 draft_content.json；CapCutAPI 帮你读写它。 -
批量操作：用 Python 把“拖素材、调时长、加字幕”翻译成 API 调用。 -
回写草稿：把生成的新草稿文件夹复制回剪映目录，打开 App 就能看到成片。
2. 从零开始：安装与运行
2.1 系统要求
| 项目 | 最低版本 | 备注 |
|---|---|---|
| Python | 3.8.20 | 3.9+ 也可，但建议保持一致 |
| FFmpeg | 任意新稳定版 | 必须能在终端直接执行 ffmpeg -version |
2.2 三步装好环境
步骤 1：克隆仓库
git clone <仓库地址>
cd CapCutAPI
步骤 2：安装依赖
pip install -r requirements.txt
步骤 3：配置 config.json
cp config.json.example config.json
# 用编辑器打开 config.json，按需改路径、端口
完成后，终端执行：
python capcut_server.py
看到 Server started at http://localhost:9000 就说明 OK。
3. 核心概念速览
| 概念 | 对应剪映里的操作 | API 中的关键词 |
|---|---|---|
| 草稿 | 一个 .draft 文件夹 |
draft_id |
| 轨道 | 主轨、画中画轨 | track_id |
| 素材 | 视频/音频/图片/文字 | resource_id |
| 特效 | 滤镜、转场、蒙版 | effect_id |
4. 最常用的 9 个接口
下面这张表把 README 中的接口重新组织成“什么时候用”：
| 目标 | HTTP 端点 | 必传字段示例 | 返回结果 |
|---|---|---|---|
| 新建空白草稿 | POST /create_draft | "draft_name": "vlog_0719" |
{ "draft_id": "abc123" } |
| 把视频放进时间线 | POST /add_video | "video_url": "http://xxx.mp4", "start":0, "end":10 |
{ "resource_id": "r1" } |
| 加背景音乐 | POST /add_audio | "audio_url": "bgm.mp3", "volume":0.3 |
{ "resource_id": "a1" } |
| 插入封面图 | POST /add_image | "image_url":"cover.jpg", "width":1080, "height":1920 |
{ "resource_id": "i1" } |
| 打一行标题 | POST /add_text | "text":"夏日 vlog", "font_size":40 |
{ "resource_id": "t1" } |
| 自动生成字幕 | POST /add_subtitle | 同上文本接口，把 is_ai:true 即可 |
{ "subtitle_track_id": "s1" } |
| 给镜头加转场 | POST /add_effect | "effect_name":"fade", "duration":0.5 |
{ "effect_id": "e1" } |
| 贴一个 emoji | POST /add_sticker | "sticker_url":"emoji.png" |
{ "resource_id": "st1" } |
| 把草稿写回磁盘 | POST /save_draft | "draft_folder":"/Users/xxx/Drafts" |
{ "local_path": "dfd_xxx" } |
5. 实战：30 秒生成一条竖屏短视频
5.1 需求描述
-
素材：横屏 1920×1080 的 MP4 -
输出：竖屏 1080×1920，带字幕、背景音乐、片头文字 -
批量：一次 20 条
5.2 完整脚本拆解
import requests, uuid, shutil, os
BASE = "http://localhost:9000"
draft_name = "auto_vlog_" + uuid.uuid4().hex[:6]
folder_out = "/Users/你的用户名/Movies/CapCut/User Data/Drafts"
# 1. 新建草稿
d = requests.post(f"{BASE}/create_draft", json={"draft_name": draft_name}).json()
draft_id = d["draft_id"]
# 2. 添加主视频（默认占满竖屏）
requests.post(f"{BASE}/add_video", json={
"draft_id": draft_id,
"video_url": "http://mycdn.com/clip.mp4",
"start": 0,
"end": 30,
"width": 1080,
"height": 1920,
"scale": 1.78 # 横屏→竖屏放大系数
})
# 3. 加背景音乐
requests.post(f"{BASE}/add_audio", json={
"draft_id": draft_id,
"audio_url": "http://mycdn.com/bgm.mp3",
"volume": 0.25
})
# 4. 加字幕
requests.post(f"{BASE}/add_subtitle", json={
"draft_id": draft_id,
"text": "生活记录 Day 19",
"start": 0,
"end": 3,
"font_size": 36,
"font_color": "#FFFFFF"
})
# 5. 保存草稿到本地
path = requests.post(f"{BASE}/save_draft", json={
"draft_id": draft_id,
"draft_folder": folder_out
}).json()["local_path"]
# 6. 复制到剪映草稿目录
shutil.copytree(path, os.path.join(folder_out, os.path.basename(path)))
print("完成！请打开剪映查看草稿：", os.path.basename(path))
把这段脚本嵌进 for 循环，即可批量跑完 20 条素材。
6. 常见疑问 FAQ
Q1：剪映和 CapCut 国际版都能用吗？
A：可以。CapCutAPI 解析的是草稿文件格式，国内剪映和国际版数据结构一致，只要路径正确即可。
Q2：为什么运行时报 “ffmpeg not found”？
A：终端执行 which ffmpeg 没结果就会报错。
-
macOS： brew install ffmpeg -
Windows：下载 https://ffmpeg.org 并把 bin目录加到 PATH。
Q3：如何查看生成的草稿？
A：
-
终端日志会打印 dfd_xxx文件夹名。 -
打开剪映 → 草稿 → 找到同名项目 → 点开即见。
Q4：能插入我自己的字体吗？
A：把 .ttf 文件放到剪映字体目录（Win：C:\Users\用户名\AppData\Roaming\JianyingPro\Resources\Font），然后在 /add_text 的 "font" 字段里写文件名即可。
Q5：如何批量加不同字幕？
A：把字幕文本提前写进 CSV，循环读取后调用 /add_subtitle，每行对应一条。
7. 进阶技巧：让流水线更稳
| 问题 | 解决思路 |
|---|---|
| 素材分辨率不统一 | 在 /add_video 里统一传 width + height，API 自动缩放 |
| 需要统一片头片尾 | 预先把片头、片尾做成单独草稿，脚本里用 /add_video 拼接 |
| 多人协作 | 把 capcut_server.py 部署在内网服务器，大家通过 HTTP 调接口 |
| 运行日志太多 | 在 config.json 把 log_level 设为 warning |
8. 故障排查清单
当你卡住时，按顺序检查：
-
Python 版本： python --version必须 ≥3.8.20 -
FFmpeg 路径： ffmpeg -version正常输出 -
端口冲突： lsof -i:9000看看是否被占用 -
剪映草稿目录是否可写：手动新建文件夹测试权限 -
文件路径含中文：尽量改成英文路径，避免转义错误
9. 小结：下一步可以做什么？
-
模板化：把常用片头、字幕样式写成 JSON 模板，一键替换。 -
CI 集成：把脚本挂到 GitHub Actions，每天自动拉素材、出片。 -
前端面板：用 Streamlit 给运营同事做一个“上传 → 选择模板 → 生成”的网页。
CapCutAPI 已经把最复杂的草稿协议封装好，剩下的就是按你的业务场景拼积木。
10. 如何继续深挖？
-
打开项目里的 example.py，复制粘贴改参数即可跑通更多示例。 -
关注官方仓库的 Issues，常见错误几乎都有人问过。 -
如果想读写更底层的字段，直接打开 dfd_xxx/draft_content.json对照字段名即可。
祝你剪片愉快，再也不用熬夜拖素材。