cutsdk

CapCut / 剪映草稿 Node.js SDK。用于代码化、批量化创建剪映标准草稿，可直接被剪映桌面端打开，也可提交云渲染。

• npm 包名：cutsdk

• 当前发布版本：1.1.5（SDK 和 CLI 统一版本）

• 版本迭代记录：CHANGELOG.md

• Node.js SDK，用于服务端、脚本和批量生成视频

• 支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩

• 媒体 URL 自动下载到草稿目录

• 出入场动画、转场效果、关键词高亮

• CLI 已拆到 @cutcli/cutcli，命令名是 cutcli，版本号跟随 cutsdk

安装

npm install cutsdk

AI / 命令行实时调用请安装 CLI：

npm install -g @cutcli/cutcli
cutcli draft create

快速上手

CLI

# 创建草稿
cutcli draft create --width 1080 --height 1920

# 本地拼接优先使用单素材命令，--src 支持本地路径或 URL
cutcli query text-effects --keyword 火焰 --limit 5
cutcli text add <draftId> --text "你好世界" --start 0s --duration 3s --font-size 8 --text-effect "红黄火焰综艺花字" --shadow
cutcli image add <draftId> --src ./素材/bg.png --start 0s --duration 5s --width 1080 --height 1920
cutcli audio add <draftId> --src ./素材/bgm.mp3 --start 0s --duration 5s
cutcli video add <draftId> --src ./素材/clip.mp4 --start 5s --duration 3s --width 1080 --height 1920 --mask 圆形

Node.js SDK

import { createDraft, addCaptions, addImages, addAudios } from 'cutsdk';

const draft = await createDraft({ width: 1080, height: 1920 });

await addCaptions({
  draftId: draft.draftId,
  captions: [{ text: '第一句话', start: 0, end: 3000000 }],
  fontSize: 8,
  bold: true,
});

AI Draft Spec

面向 AI 自动生成草稿、本地素材拼接和批量混剪时，推荐使用单一 JSON Spec，并用 createAndRenderDraft 统一处理输出目录、草稿名和可选云渲染：

import { createAndRenderDraft } from 'cutsdk';

await createAndRenderDraft({
  draft: {
    version: '1.0',
    canvas: { width: 1080, height: 1920 },
    duration: '3s',
    tracks: [
      {
        type: 'text',
        clips: [{ type: 'caption', text: '你好世界', start: '0s', duration: '3s' }],
      },
    ],
  },
  output: {
    draftsDir: '/Users/x013/jy_draft/JianyingPro Drafts',
    name: '测试草稿',
  },
  render: false,
});

Spec 只是编排层，底层仍复用现有草稿创建和素材添加方法，保证导出的草稿格式不变。 顶层 duration 可选；不传时会按时间线 clips 自动计算草稿总时长。 createDraftFromSpec(spec) 也可直接创建草稿，但不能传输出目录和草稿名；需要这些控制时使用 createAndRenderDraft。

需要创建后直接提交云渲染时，可以使用一站式 SDK：

import { createAndRenderDraft } from 'cutsdk';

const result = await createAndRenderDraft({
  draft: {
    version: '1.0',
    canvas: { width: 1080, height: 1920 },
    duration: '5s',
    assets: {
      bg: { type: 'image', src: '/tmp/bg.png', width: 1080, height: 1920 },
    },
    tracks: [
      { type: 'visual', clips: [{ type: 'image', asset: 'bg', start: '0s', duration: '5s' }] },
    ],
  },
  output: { draftsDir: '/Users/x013/jy_draft/JianyingPro Drafts', name: '测试草稿' },
  render: {
    cloud: true,
    apiToken: 'your_api_token_here', // 显式传入云渲染 API Token。也可以不传，SDK 会自动从环境变量中读取
    wait: true,                      // 是否等待渲染完成，默认 false
  },
});

console.log(result.render?.videoUrl);

当前 Draft Spec 有两个批量限制需要提前考虑：同一个 Spec 内图片/视频 transform 会整批应用，不能每段素材独立设置不同 scale/position；字幕 style/position 也会整批应用，不能每条字幕完全不同位置样式。需要逐片段差异化时，先用 Spec 创建主体，再在 afterCreate 或低层 SDK API 里补后处理。

云渲染 API Token 配置

cutsdk 和 cutcli 均支持将生成的草稿打包并提交至云端进行快速渲染。使用云渲染需要配置 API Token，有以下三种方式：

1. 环境变量（推荐）： 设置环境变量 CUT_API_TOKEN（或 CUT_RENDER_API_KEY、CUTCLI_API_KEY）。SDK 和 CLI 会自动读取。

   export CUT_API_TOKEN="your_render_api_token"

2. SDK 参数显式传入： 在调用 createAndRenderDraft 或 renderDraft 时，在 render 对象中显式传入 apiToken 字段：

   render: {
     cloud: true,
     apiToken: 'your_render_api_token'
   }

3. CLI 命令行保存： 在终端运行 cutcli login <apiToken>，Token 会被保存在本地配置文件中（~/.cutcli/config.json），后续 CLI 云渲染命令会自动读取。

   cutcli login your_render_api_token

AI Agent 接入

CLI 可把项目级 AI 使用说明安装到业务项目：

npm install cutsdk && npx cutsdk init

如果项目里已存在 .agents/skills/cut-draft 或 cutcli-docs，npx cutsdk init 会询问是否覆盖更新；输入 y 或 yes 才会覆盖。需要跳过询问时使用 npx cutsdk init --force。

模板位于 src/api/setup/templates/project/，包含 .agents/skills/cut-draft/SKILL.md、SDK 快速开始、API 速查和示例代码。

文档

| 文档 | 说明 | |------|------| | CLI 命令参考 | 所有命令行命令的完整用法 | | API 参考 | Node.js SDK 所有方法的接口文档 | | 完整文档 | 草稿存储、时间单位、JSON 参数等详细说明 |

时间单位

所有时间参数使用 微秒（μs）：1秒 = 1,000,000

License

MIT