cut_cli 文档

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

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

新版能力

v1.3.9 开始，cut_cli 在本地草稿编辑之外补齐了云端渲染链路：

• 云端认证：通过 cutcli auth set --api-key <key> 保存 cutcli.com API Key，也可使用 CUTCLI_API_KEY 环境变量。
• 草稿上传：cutcli draft zip 可打包本地草稿，cutcli draft upload 可上传草稿 zip 并返回云端下载链接。
• 云渲染提交：cutcli cloud render <draftId> 会自动打包、上传草稿，并创建云渲染任务。
• 任务查询：cutcli cloud jobs、cutcli cloud job <jobId>、cutcli cloud result <jobId> 可查看任务状态、成片地址、失败原因和事件记录。
• 定时渲染：cutcli timer render 可按固定间隔创建草稿、上传并提交云渲染，适合连通性巡检、自动化样片或周期性渲染测试。

安装

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}]'

不同安装方式可能提供 cut 或 cutcli 命令，二者指向同一个 CLI。下方云端示例使用 cutcli。

云渲染快速流程

# 1. 保存云端 API Key
cutcli auth set --api-key cut_live_xxx_yyy

# 2. 创建并编辑本地草稿
cutcli draft create --width 1080 --height 1920 --name "cloud-demo"
cutcli captions add cloud-demo --captions '[{"text":"云渲染测试","start":0,"end":5000000}]'

# 3. 上传草稿并创建云渲染任务
cutcli cloud render cloud-demo --pretty

# 4. 查询队列或单个任务
cutcli cloud jobs --status queued --pretty
cutcli cloud job <renderJobId> --pretty

定时提交云渲染可直接运行：

cutcli timer render --interval 5 --count 1 --pretty

全局选项

选项	说明
--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 所有方法的接口文档