cut_sdk

CapCut / 剪映草稿 SDK + CLI 工具。用代码创建剪映标准草稿，可直接被剪映桌面端打开。

• Node.js SDK + CLI 双模式
• 支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩
• 媒体 URL 自动下载到草稿目录
• 出入场动画、转场效果、关键词高亮
• 提供项目级 AI Agent 接入文档与示例模板

安装

npm install -g @strmoon/cut_sdk

或直接通过 npx 运行（无需安装）：

npx @strmoon/cut_sdk draft create

快速上手

CLI

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

# 添加字幕
cut captions add <draftId> --captions '[
  {"text":"你好世界","start":0,"end":3000000}
]' --font-size 8 --bold

# 添加图片
cut images add <draftId> --image-infos '[
  {"imageUrl":"https://example.com/bg.jpg","width":1920,"height":1080,"start":0,"end":5000000}
]'

# 添加背景音乐
cut audios add <draftId> --audio-infos '[
  {"audioUrl":"https://example.com/bgm.mp3","duration":5000000,"start":0,"end":5000000}
]'

Node.js SDK

import { createDraft, addCaptions, addImages, addAudios } from '@strmoon/cut_sdk';

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：

import { createDraftFromSpec } from '@strmoon/cut_sdk';

await createDraftFromSpec({
  version: '1.0',
  canvas: { width: 1080, height: 1920 },
  duration: '3s',
  tracks: [
    {
      type: 'text',
      clips: [{ type: 'caption', text: '你好世界', start: '0s', duration: '3s' }],
    },
  ],
});

Spec 只是编排层，底层仍复用现有草稿创建和素材添加方法，保证导出的草稿格式不变。 顶层 duration 可选；不传时会按时间线 clips 自动计算草稿总时长。

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

import { createAndRenderDraft } from '@strmoon/cut_sdk';

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 },
});

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

AI Agent 接入

项目级接入模板位于 src/api/setup/templates/project/，包含 .agents/skills/cut-draft/SKILL.md、SDK 快速开始、API 速查和示例代码。后续可接入 cut init 命令，将这些文件复制到业务项目中。

文档

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

时间单位

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

License

MIT