cut_cli 文档

CapCut 草稿 API + CLI 工具，提供 Node.js SDK 和命令行两种使用方式，用于创建和操作剪映草稿。

草稿以剪映标准文件夹格式存储，可直接被剪映桌面端打开。添加图片/视频/音频时，媒体文件自动从 URL 下载到本地。

安装

npm install cut_cli

全局安装（使用 CLI）：

curl -s https://cutcli.com/cli | bash

使用方式

作为 Node.js SDK

import { createDraft, addCaptions, addImages } from 'cut_cli';

const draft = await createDraft({ width: 1080, height: 1920 });
console.log(draft.draftId);   // UUID
console.log(draft.filePath);  // ~/Movies/JianyingPro Drafts/{draftId}/

作为 CLI 工具

cutcli draft create --width 1080 --height 1920
cutcli captions add <draftId> --captions '[{"text":"你好","start":0,"end":3000000}]'

全局选项

选项	说明
--env-file <path>	指定 .env 文件路径，在执行子命令前加载环境变量
--pretty	美化 JSON 输出
-V, --version	显示版本号
-h, --help	显示帮助信息

草稿存储

每个草稿是一个剪映标准格式的文件夹，包含工程 JSON、元信息和已下载的媒体文件，可直接被剪映桌面端识别和打开。

• 默认路径：~/Movies/JianyingPro Drafts/{draftId}/（macOS，与剪映默认草稿目录一致）
• 自定义路径：设置环境变量 CUT_DRAFTS_DIR 或在 .env 中配置

# .env
CUT_DRAFTS_DIR=/path/to/my/drafts

草稿文件夹结构

{draftId}/
  ├── draft_content.json          # 核心工程 JSON（始终保持最新）
  ├── draft_info.json             # 同上
  ├── draft_meta_info.json        # 元信息（id, name, root_path）
  ├── draft_agency_config.json    # 剪映配置（模板）
  ├── attachment_pc_common.json   # 剪映配置（模板）
  ├── template.tmp                # 剪映模板
  └── resources/                  # 已下载的媒体文件
      ├── {uuid}.mp3              # 音频
      ├── {uuid}.mp4              # 视频
      └── {uuid}.png              # 图片

媒体自动下载

调用 addImages、addVideos、addAudios、easyCreateMaterial 时，传入的 URL 会自动下载到草稿的 resources/ 子目录，工程 JSON 中使用剪映占位符路径引用本地文件。用户只需像以前一样传 URL，无需手动处理文件下载。

时间单位

所有时间参数均使用微秒（μs），即 1秒 = 1,000,000。

例如：3 秒 → 3000000，0.5 秒 → 500000。

JSON 参数传递

CLI 中接受 JSON 参数的选项支持两种写法：

• 内联 JSON：--captions '[{"text":"hello","start":0,"end":3000000}]'
• 文件引用：--captions @captions.json（读取文件内容）

文档索引

文档	说明
CLI 命令参考	所有命令行命令的完整用法
API 参考	Node.js SDK 所有方法的接口文档