# cutsdk

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

- npm 包名：`cutsdk`
- 当前发布版本：`1.1.5`（SDK 和 CLI 统一版本）
- 版本迭代记录：[CHANGELOG.md](./CHANGELOG.md)

- Node.js SDK，用于服务端、脚本和批量生成视频
- 支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩
- 媒体 URL 自动下载到草稿目录
- 出入场动画、转场效果、关键词高亮
- CLI 已拆到 `@cutcli/cutcli`，命令名是 `cutcli`，版本号跟随 `cutsdk`

## 安装

```bash
npm install cutsdk
```

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

```bash
npm install -g @cutcli/cutcli
cutcli draft create
```

## 快速上手

### CLI

```bash
# 创建草稿
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

```typescript
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` 统一处理输出目录、草稿名和可选云渲染：

```typescript
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：

```typescript
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 会自动读取。
   ```bash
   export CUT_API_TOKEN="your_render_api_token"
   ```

2. **SDK 参数显式传入**：
   在调用 `createAndRenderDraft` 或 `renderDraft` 时，在 `render` 对象中显式传入 `apiToken` 字段：
   ```typescript
   render: {
     cloud: true,
     apiToken: 'your_render_api_token'
   }
   ```

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

## AI Agent 接入

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

```bash
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 命令参考](docs/cli.md) | 所有命令行命令的完整用法 |
| [API 参考](docs/api.md) | Node.js SDK 所有方法的接口文档 |
| [完整文档](docs/README.md) | 草稿存储、时间单位、JSON 参数等详细说明 |

## 时间单位

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

## License

[MIT](LICENSE)