JianYingApi 完整教程：用 Python 调用剪映API批量生成视频草稿
项目地址: https://gitcode.com/gh_mirrors/ji/JianYingApi JianYingApi 是一个第三方剪映API，让你用 Python 代码完成建草稿、加轨道、导入素材、加特效，最后自动打开剪映导出成片。它靠两样东西干活：读写剪映的草稿 JSON 文件，加上 uiautomation 界面自动化。适合需要批量生成视频、想把剪辑流程脚本化的个人开发者和内容团队。
快速安装 JianYingApi：环境要求与第一条可运行示例
环境要求先说清楚：Windows 系统 + 剪映（JianyingPro）桌面版 + Python 3。依赖里的 uiautomation、pyautogui、keyboard 全是 Windows 下的界面自动化库，Mac 和剪映网页版跑不起来。
安装只有两步，克隆仓库后装依赖：
git clone https://gitcode.com/gh_mirrors/ji/JianYingApi
cd JianYingApi && pip install -r requirements.txt
最小可运行示例如下，它演示了完整的调用链：建草稿、建轨道、导入媒体、上轨道、保存：
import JianYingApi, uuid
# 新建草稿：往指定文件夹写入两个空白 JSON 模板
d = JianYingApi.Drafts.Create_New_Drafts(r"E:\JianyingPro Drafts\Demo")
video_track = d.Content.NewTrack(TrackType="video") # 建一条视频轨道
video_path = r"E:/videos/demo.mp4"
video_id = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name="demo_material"))
d.Meta.Import2Lib(path=video_path, metetype="video") # 把素材登记进媒体库
d.Content.AddMaterial(Mtype="videos", Content={
"id": video_id, "material_name": "demo",
"path": video_path, "type": "video"}) # 素材定义写入时间线
d.Content.Add2Track(Track_id=video_track["id"], Content={
"id": str(uuid.uuid1()), "material_id": video_id,
"source_timerange": {"start": 0, "duration": 600000000}, # 单位是纳秒
"target_timerange": {"start": 0, "duration": 600000000}})
d.Save() # 回写两个 JSON，剪映里直接打开就能看到这个工程
仓库根目录的 example.py 在此基础上还加了特效轨道和自动拉起剪映的步骤，对着它改就能出活。
原理拆解：剪映草稿文件 + 界面自动化如何驱动剪映API
JianYingApi 的底层逻辑一句话能讲完：剪映的工程就是文件夹里的 JSON，改文件等于做剪辑。
每个草稿文件夹里有两个核心文件：draft_content.json 存时间线（素材表 materials、轨道 tracks），draft_meta_info.json 存媒体库和项目概览。建草稿时，库把两个空白模板拷贝到新文件夹；之后 NewTrack、AddMaterial、Add2Track 本质上都是往 JSON 里 append 数据，Save() 回写磁盘，剪映再打开时自然读到了新工程。
素材进媒体库的过程也有据可查：Import2Lib 会在 draft_materials 下追加一条记录，记下文件路径、媒体类型（video/photo/music）和一个 UUID：
文件之外的另一半是界面自动化：Jy_Warp.Instance 会先杀掉已开的剪映进程，再用 uiautomation 按控件名（比如首页的 HomePageStartProjectName）定位界面元素、模拟点击，完成"打开草稿 → 导出"这类必须走 GUI 的步骤。所以整条链路是：代码写文件 → 剪映读文件 → 自动化替人点鼠标。
场景一：如何用循环批量生成商品视频草稿
痛点：几十个商品要做几十条结构相同的视频，手动在时间线上一个个拖素材，慢还容易出错。思路：把商品列表扔进 for 循环，每个商品走一遍上面那条草稿调用链。
products = [
{"name": "Tee", "video": r"E:/media/t1.mp4"},
{"name": "Cap", "video": r"E:/media/t2.mp4"},
]
for p in products:
d = JianYingApi.Drafts.Create_New_Drafts(f"Drafts/{p['name']}")
track = d.Content.NewTrack(TrackType="video")
mid = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name=p["name"]))
d.Meta.Import2Lib(path=p["video"], metetype="video")
d.Content.AddMaterial(Mtype="videos",
Content={"id": mid, "material_name": p["name"],
"path": p["video"], "type": "video"})
d.Content.Add2Track(Track_id=track["id"], Content={
"id": str(uuid.uuid1()), "material_id": mid,
"source_timerange": {"start": 0, "duration": 300000000},
"target_timerange": {"start": 0, "duration": 300000000}})
d.Save() # 循环结束，草稿目录下多出一批可直接打开的工程
纯写文件没有渲染开销，批量跑几十上百条草稿本身很快，瓶颈在后面的导出环节。
场景二：如何自动打开剪映并配置导出参数
痛点：草稿批量生成了，导出还是得手动点，最后一公里没自动化。思路：用 Jy_Warp.Instance 拉起剪映，导出参数交给 Export_Options 配置。
# 自动拉起剪映（参数为剪映安装目录）
ins = JianYingApi.Jy_Warp.Instance(JianYing_Exe_Path=r"E:\SB\JianyingPro")
Export_Options 把导出面板的选项收成了参数：画质（480/720/1080/1440/2160）、码率（recommend/lower/higher/option）、编码（H.264/HEVC）、格式（mp4/mov）、帧率（24~60），也支持导出 srt 字幕。库会驱动界面把表单填好并点下导出按钮，轮询到成功弹窗后返回导出路径。
避坑与 FAQ：版本漂移、时间单位与草稿路径
剪映版本一更新，自动化就断？ 是的，这是最大的坑。代码是在剪映 V3.3.5 上测的，它靠控件名定位界面，剪映大版本升级后控件名会变，表现就是卡在断言上（比如 Not In Certificated Page）。README 作者自己也承认"有时候一个版本没跟上就 G"。对策：固定在你适配过的剪映版本上跑，或者以项目为底座自己改 Ui_warp.py 里的控件名。
时间长度怎么算？ source_timerange / target_timerange 里的 start 和 duration 单位是纳秒，1 秒 = 1000000000。按毫秒填，时间线直接长到离谱。
草稿建了剪映首页看不到？ 草稿目录要放在剪映登记的草稿根目录下（一般是 JianyingPro Drafts）。另外 Create_New_Drafts 拷贝空白模板用的是相对路径 ./blanks/，所以脚本的工作目录必须停在项目根目录，否则一建草稿就报文件不存在。
JSON 字段要像官方一样填全吗？ 不用。文档里讲得很直白：只要必要字段（id、material_id、timerange 这些）补全且 ID 对应关系正确，剩下的剪映自己会补齐。ID 建议用 uuid.uuid1()（按时间）和 uuid.uuid3()（按文件）生成。
批量导出会不会卡？ 写草稿阶段是纯文件 I/O，很快；真正耗时的是逐个打开剪映、走 UI 导出。建议先批量把所有草稿生成完，再集中做导出；另外注意 Instance 启动前会 taskkill 强杀剪映，别在有未保存工作的机器上随手跑。
JianYingApi 目前只支持 Windows 版剪映桌面端，已实现的核心功能是媒体导入与特效添加，更适合当作二次开发的底座而不是开箱即用的成品。仓库克隆地址为 https://gitcode.com/gh_mirrors/ji/JianYingApi，完整调用链参考根目录的 example.py。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
