cutsdk 0.0.1 → 1.0.0

package/dist/api/masks/get-masks.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMasks = getMasks;
+const draft_service_1 = require("../../shared/draft-service");
+async function getMasks(params) {
+    const draft = await (0, draft_service_1.loadDraft)(params.draftId);
+    const masks = draft.materials?.masks || [];
+    if (!params.segmentId) {
+        const results = [];
+        for (const track of draft.tracks || []) {
+            for (const segment of track.segments || []) {
+                const refs = segment.extra_material_refs || [];
+                for (const mask of masks) {
+                    if (refs.includes(mask.id))
+                        results.push(toMaskInfo(mask));
+                }
+            }
+        }
+        return results.length > 0 ? results : masks.map(toMaskInfo);
+    }
+    const segment = draft.get_segment_by_id(params.segmentId);
+    if (!segment)
+        return [];
+    const refs = segment.extra_material_refs || [];
+    return masks.filter((m) => refs.includes(m.id)).map(toMaskInfo);
+}
+function toMaskInfo(m) {
+    return {
+        id: m.id,
+        name: m.name || '',
+        resourceType: m.resource_type || '',
+        config: {
+            centerX: m.config?.centerX || 0,
+            centerY: m.config?.centerY || 0,
+            width: m.config?.width || 0,
+            height: m.config?.height || 0,
+            feather: m.config?.feather || 0,
+            rotation: m.config?.rotation || 0,
+            invert: m.config?.invert || false,
+            roundCorner: m.config?.roundCorner || 0,
+        },
+    };
+}
+//# sourceMappingURL=get-masks.js.map

package/dist/api/masks/get-masks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-masks.js","sourceRoot":"","sources":["../../../src/api/masks/get-masks.ts"],"names":[],"mappings":";;AAGA,4BAsBC;AAzBD,8DAAuD;AAGhD,KAAK,UAAU,QAAQ,CAAC,MAA+C;IAC5E,MAAM,KAAK,GAAG,MAAM,IAAA,yBAAS,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAU,KAAK,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC;IAElD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YACvC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAa,OAAO,CAAC,mBAAmB,IAAI,EAAE,CAAC;gBACzD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;wBAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC7D,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,IAAI,GAAa,OAAO,CAAC,mBAAmB,IAAI,EAAE,CAAC;IACzD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,UAAU,CAAC,CAAM;IACxB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE;QAClB,YAAY,EAAE,CAAC,CAAC,aAAa,IAAI,EAAE;QACnC,MAAM,EAAE;YACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC;YAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;YAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,IAAI,CAAC;YACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,KAAK;YACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,WAAW,IAAI,CAAC;SACxC;KACF,CAAC;AACJ,CAAC"}

package/dist/api/query/get-audio-duration.d.ts

@@ -0,0 +1,3 @@
+import type { GetAudioDurationInput, GetAudioDurationOutput } from '../../types';
+export declare function getAudioDurationApi(params: GetAudioDurationInput): Promise<GetAudioDurationOutput>;
+//# sourceMappingURL=get-audio-duration.d.ts.map

package/dist/api/query/get-audio-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-audio-duration.d.ts","sourceRoot":"","sources":["../../../src/api/query/get-audio-duration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEjF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAMxG"}

package/dist/api/query/get-audio-duration.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAudioDurationApi = getAudioDurationApi;
+const media_1 = require("../../shared/media");
+async function getAudioDurationApi(params) {
+    const duration = await (0, media_1.getAudioDuration)(params.url);
+    if (duration === 0) {
+        return { message: 'Failed to get audio duration', duration: 0 };
+    }
+    return { message: 'ok', duration };
+}
+//# sourceMappingURL=get-audio-duration.js.map

package/dist/api/query/get-audio-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-audio-duration.js","sourceRoot":"","sources":["../../../src/api/query/get-audio-duration.ts"],"names":[],"mappings":";;AAGA,kDAMC;AATD,8CAA8E;AAGvE,KAAK,UAAU,mBAAmB,CAAC,MAA6B;IACrE,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAoB,EAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACrC,CAAC"}

package/dist/api/query/get-image-animations.d.ts

@@ -0,0 +1,3 @@
+import type { GetImageAnimationsInput, GetImageAnimationsOutput } from '../../types';
+export declare function getImageAnimations(params?: GetImageAnimationsInput): Promise<GetImageAnimationsOutput>;
+//# sourceMappingURL=get-image-animations.d.ts.map

package/dist/api/query/get-image-animations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-animations.d.ts","sourceRoot":"","sources":["../../../src/api/query/get-image-animations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAIrF,wBAAsB,kBAAkB,CAAC,MAAM,GAAE,uBAA4B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAehH"}

package/dist/api/query/get-image-animations.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImageAnimations = getImageAnimations;
+const { Draft } = require('../../draft');
+async function getImageAnimations(params = {}) {
+    const mode = params.mode || 0;
+    const type = params.type || 'in';
+    const draft = new Draft();
+    let effects;
+    if (type === 'loop') {
+        effects = draft.get_all_video_loop_Effects(mode);
+    }
+    else if (type === 'out') {
+        effects = draft.get_all_video_chuchang_Effects(mode);
+    }
+    else {
+        effects = draft.get_all_video_ruchang_Effects(mode);
+    }
+    return { effects };
+}
+//# sourceMappingURL=get-image-animations.js.map

package/dist/api/query/get-image-animations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-animations.js","sourceRoot":"","sources":["../../../src/api/query/get-image-animations.ts"],"names":[],"mappings":";;AAIA,gDAeC;AAjBD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAElC,KAAK,UAAU,kBAAkB,CAAC,SAAkC,EAAE;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IAE1B,IAAI,OAAc,CAAC;IACnB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,GAAG,KAAK,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;SAAM,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QAC1B,OAAO,GAAG,KAAK,CAAC,8BAA8B,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,KAAK,CAAC,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/api/setup/templates/project/.agents/skills/cut-draft/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: cut-draft
+description: >-
+  使用 cutsdk 创建和操作剪映/CapCut 草稿工程。用户想创建剪映草稿、添加字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩、
+  提交渲染，或提到 cut_sdk、cut、draft spec、剪映、草稿、字幕、CapCut draft 时使用此 skill。
+---
+
+# cut_sdk 项目级 Skill
+
+`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK 和 CLI。生成后的草稿可直接在剪映桌面端打开。
+
+## 先读这些
+
+写代码前，先阅读本项目内的文档：
+
+1. `cut-sdk/README.md`
+2. `cut-sdk/quickstart.md`
+3. `cut-sdk/api-cheatsheet.md`
+
+实现时优先从 `cut-sdk/examples/` 里选择最接近的示例改起。
+
+## 推荐使用路径
+
+- AI 生成完整时间线时，优先使用 `createDraftFromSpec(spec)`。
+- 用户希望“一次创建草稿并提交云渲染”时，使用 `createAndRenderDraft(input)`。
+- 用户要逐步编辑草稿，或 Draft Spec 尚未覆盖某个能力时，再使用低层 API，例如 `createDraft`、`addCaptions`、`addImages`、`addVideos`、`addAudios`、`addMasks`、`addKeyframes`。
+- 只有在用户明确需要命令行，或只是做快速手动操作时，才使用 CLI。
+
+## 关键规则
+
+- 包导入名是 `cutsdk`。
+- 低层 SDK 和 CLI 的所有时间数值都是微秒：`1s = 1000000`。
+- AI Draft Spec 的时间字符串可写为 `1.5s`、`500ms`、`300000us`。
+- 默认草稿目录是 `~/Movies/JianyingPro Drafts/{draftId}/`；可通过 `CUT_DRAFTS_DIR` 覆盖。
+- 媒体 URL 和本地媒体路径会由 SDK 复制/下载到草稿的 `resources/` 文件夹。
+- 图片必须提供 `width` 和 `height`。
+- 使用低层 API 添加视频或音频时，要提供素材原始时长。
+- 同一轨道内的片段不要重叠，除非目标 API 明确会创建独立轨道。
+- CLI 参数使用 kebab-case，例如 `--font-size`，不要写成 `--fontSize`。
+
+## 最小 Draft Spec 示例
+
+```ts
+import { createDraftFromSpec } from 'cutsdk';
+
+await createDraftFromSpec({
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  tracks: [
+    {
+      type: 'text',
+      clips: [
+        { type: 'caption', text: '你好剪映', start: '0s', duration: '3s' },
+      ],
+    },
+  ],
+});
+```
+
+## 云渲染环境变量
+
+云渲染需要：
+
+```env
+CUT_API_TOKEN=your_token
+CUT_UPLOAD_API_BASE=http://your-render-backend:8080
+```
+
+在调用方项目中使用 `.env`，或在调用 SDK 前自行加载环境变量。
+
+## 常见坑
+
+1. 不要混用包名。除非项目明确覆盖，否则始终使用 `cutsdk`。
+2. 不要把“秒”直接作为低层 API 的数字传入。数字 `3` 表示 3 微秒，不是 3 秒。
+3. 对动画/特效名有精确要求时，不要凭空编造。先用 CLI 查询可用资源，或使用项目里已有示例。
+4. 除非 SDK 无法表达目标操作，否则不要手动改剪映草稿 JSON。
+5. 生成复杂时间线时，先用 `validateDraftSpec(spec)` 校验 Draft Spec。

package/dist/api/setup/templates/project/cut-sdk/.env.example

@@ -0,0 +1,7 @@
+# 可选：本地剪映草稿文件夹创建位置。
+# macOS 默认路径是 ~/Movies/JianyingPro Drafts
+CUT_DRAFTS_DIR=/absolute/path/to/JianyingPro Drafts
+
+# 仅云渲染需要。
+CUT_API_TOKEN=your_render_api_token
+CUT_UPLOAD_API_BASE=http://your-render-backend:8080

package/dist/api/setup/templates/project/cut-sdk/README.md

@@ -0,0 +1,54 @@
+# cut_sdk 项目接入指南
+
+这个目录是给 AI Agent 和开发者第一次在项目中使用 `cutsdk` 时看的接入资料。
+
+`cutsdk` 可以用 Node.js 代码创建剪映/CapCut 桌面端草稿文件夹，支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩、AI Draft Spec，以及可选的云渲染。
+
+## 阅读顺序
+
+1. 先读 `quickstart.md`。
+2. 再扫一遍 `api-cheatsheet.md`。
+3. 从 `examples/` 中复制最接近需求的示例改起。
+
+## 安装
+
+```bash
+npm install cutsdk
+```
+
+如果要使用 CLI：
+
+```bash
+npm install -g cutsdk
+cut draft create --width 1080 --height 1920
+```
+
+不全局安装也可以直接用 `npx`：
+
+```bash
+npx cutsdk draft create --width 1080 --height 1920
+```
+
+## 环境变量
+
+当项目需要自定义草稿目录或使用云渲染时，把 `.env.example` 复制为 `.env` 并填写：
+
+```env
+CUT_DRAFTS_DIR=/absolute/path/to/JianyingPro Drafts
+CUT_API_TOKEN=your_token
+CUT_UPLOAD_API_BASE=http://your-render-backend:8080
+```
+
+## 核心概念
+
+- 一个草稿就是磁盘上的剪映兼容工程文件夹。
+- 默认草稿路径是 `~/Movies/JianyingPro Drafts/{draftId}/`。
+- 低层 SDK API 的时间数值使用微秒。
+- AI Draft Spec 支持更易读的时间字符串，例如 `3s`、`500ms`、`300000us`。
+- 媒体 URL 和本地文件路径会被复制/下载到草稿的 `resources` 文件夹。
+
+## 推荐优先使用
+
+AI 生成视频草稿时，优先使用 `createDraftFromSpec`。它允许用一个 JSON 对象描述完整时间线，再由 SDK 调用底层草稿 API。
+
+创建草稿后还需要补充高级操作时，可以使用带 `afterCreate` 的 `createAndRenderDraft`，或直接调用低层 API。

package/dist/api/setup/templates/project/cut-sdk/api-cheatsheet.md

@@ -0,0 +1,132 @@
+# cut_sdk API 速查
+
+从 `cutsdk` 导入：
+
+```ts
+import {
+  createDraftFromSpec,
+  validateDraftSpec,
+  createAndRenderDraft,
+  createDraft,
+  getDraftInfo,
+  addCaptions,
+  addImages,
+  addVideos,
+  addAudios,
+  addEffects,
+  addSticker,
+  addKeyframes,
+  addMasks,
+  renderDraft,
+  isCutSdkError,
+} from 'cutsdk';
+```
+
+## 优先选择：AI Draft Spec
+
+```ts
+const result = await createDraftFromSpec({
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  duration: '5s',
+  tracks: [
+    { type: 'text', clips: [{ type: 'caption', text: 'Hello', start: '0s', duration: '5s' }] },
+  ],
+});
+```
+
+用于一次性生成完整时间线。
+
+## 创建并渲染
+
+```ts
+const result = await createAndRenderDraft({
+  draft: spec,
+  output: {
+    draftsDir: process.env.CUT_DRAFTS_DIR,
+    name: 'demo-draft',
+  },
+  render: {
+    cloud: true,
+    apiToken: process.env.CUT_API_TOKEN,
+    apiBase: process.env.CUT_UPLOAD_API_BASE,
+  },
+});
+
+console.log(result.render?.videoUrl);
+```
+
+## 低层草稿流程
+
+```ts
+const draft = await createDraft({ width: 1080, height: 1920 });
+
+await addImages({
+  draftId: draft.draftId,
+  imageInfos: [
+    { imageUrl: '/absolute/path/bg.png', width: 1080, height: 1920, start: 0, end: 5000000 },
+  ],
+});
+
+await addCaptions({
+  draftId: draft.draftId,
+  captions: [{ text: 'Hello', start: 0, end: 5000000 }],
+  fontSize: 8,
+  textColor: '#ffffff',
+});
+```
+
+需要逐步添加素材或操作时使用这种方式。
+
+## 时间
+
+低层 API 使用微秒：
+
+| 人类时间 | 数值 |
+|------------|-------|
+| 0.5s | `500000` |
+| 1s | `1000000` |
+| 3s | `3000000` |
+| 10s | `10000000` |
+
+Draft Spec 可以使用字符串：
+
+```ts
+'1.5s'
+'500ms'
+'300000us'
+```
+
+## 错误处理
+
+```ts
+try {
+  await createDraftFromSpec(spec);
+} catch (error) {
+  if (isCutSdkError(error)) {
+    console.error(error.code, error.operation, error.details);
+  } else {
+    console.error(error);
+  }
+}
+```
+
+常见错误码：
+
+| code | 含义 |
+|------|---------|
+| `INVALID_INPUT` | SDK 参数不合法 |
+| `DRAFT_NOT_FOUND` | 草稿 ID 或草稿文件夹不存在 |
+| `MEDIA_NOT_FOUND` | 本地媒体文件不存在 |
+| `MEDIA_DOWNLOAD_FAILED` | 远程媒体下载失败 |
+| `MISSING_API_TOKEN` | 缺少云渲染 token |
+| `DRAFT_SPEC_VALIDATION_FAILED` | Draft Spec 校验失败 |
+| `DRAFT_SPEC_RESOLVE_FAILED` | Draft Spec 无法归一化 |
+
+## 对应 CLI 命令
+
+```bash
+cut draft create --width 1080 --height 1920
+cut captions add <draftId> --captions '[{"text":"Hello","start":0,"end":3000000}]'
+cut cloud render <draftId> --wait
+```

package/dist/api/setup/templates/project/cut-sdk/examples/01-create-draft.ts

@@ -0,0 +1,43 @@
+import { addCaptions, addImages, createDraft, getDraftInfo } from 'cutsdk';
+
+async function main() {
+  const draft = await createDraft({ width: 1080, height: 1920 });
+
+  await addImages({
+    draftId: draft.draftId,
+    imageInfos: [
+      {
+        imageUrl: '/absolute/path/to/background.png',
+        width: 1080,
+        height: 1920,
+        start: 0,
+        end: 5000000,
+      },
+    ],
+  });
+
+  await addCaptions({
+    draftId: draft.draftId,
+    captions: [
+      {
+        text: '低层 SDK 示例',
+        start: 0,
+        end: 5000000,
+        keyword: 'SDK',
+        keywordColor: '#00ffaa',
+      },
+    ],
+    fontSize: 8,
+    textColor: '#ffffff',
+    bold: true,
+    transformY: -0.65,
+  });
+
+  const info = await getDraftInfo({ draftId: draft.draftId });
+  console.log({ draft, info });
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/api/setup/templates/project/cut-sdk/examples/02-draft-spec.ts

@@ -0,0 +1,73 @@
+import { createDraftFromSpec, validateDraftSpec } from 'cutsdk';
+
+const spec = {
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  duration: '6s',
+  assets: {
+    cover: {
+      type: 'image',
+      src: '/absolute/path/to/cover.png',
+      width: 1080,
+      height: 1920,
+    },
+    bgm: {
+      type: 'audio',
+      src: '/absolute/path/to/music.mp3',
+      duration: '6s',
+    },
+  },
+  styles: {
+    title: {
+      fontSize: 10,
+      color: '#ffffff',
+      bold: true,
+      shadow: true,
+    },
+  },
+  tracks: [
+    {
+      type: 'visual',
+      clips: [
+        { type: 'image', asset: 'cover', start: '0s', duration: '6s' },
+      ],
+    },
+    {
+      type: 'text',
+      clips: [
+        {
+          type: 'caption',
+          text: 'AI Draft Spec 示例',
+          style: 'title',
+          keyword: 'AI|Spec',
+          keywordColor: '#00ffaa',
+          start: '0s',
+          duration: '6s',
+          position: 'bottom',
+        },
+      ],
+    },
+    {
+      type: 'audio',
+      clips: [
+        { type: 'audio', asset: 'bgm', start: '0s', duration: '6s', volume: 0.7 },
+      ],
+    },
+  ],
+} as const;
+
+async function main() {
+  const validation = validateDraftSpec(spec);
+  if (!validation.valid) {
+    console.error(validation.errors);
+    process.exit(1);
+  }
+
+  const draft = await createDraftFromSpec(spec);
+  console.log(draft);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/api/setup/templates/project/cut-sdk/examples/03-create-and-render.ts

@@ -0,0 +1,67 @@
+import { addKeyframes, addMasks, createAndRenderDraft } from 'cutsdk';
+
+async function main() {
+  const result = await createAndRenderDraft({
+    draft: {
+      version: '1.0',
+      canvas: { width: 1080, height: 1920 },
+      duration: '5s',
+      assets: {
+        bg: {
+          type: 'image',
+          src: '/absolute/path/to/background.png',
+          width: 1080,
+          height: 1920,
+        },
+      },
+      tracks: [
+        {
+          type: 'visual',
+          clips: [{ type: 'image', asset: 'bg', start: '0s', duration: '5s' }],
+        },
+        {
+          type: 'text',
+          clips: [{ type: 'caption', text: '创建并云渲染', start: '0s', duration: '5s' }],
+        },
+      ],
+    },
+    output: {
+      draftsDir: process.env.CUT_DRAFTS_DIR,
+      name: 'cut-sdk-render-demo',
+    },
+    afterCreate: async ({ draft, clip }) => {
+      const firstImage = clip('image', 0);
+      if (!firstImage.segmentId) return;
+
+      await addMasks({
+        draftId: draft.draftId,
+        segmentIds: [firstImage.segmentId],
+        name: '矩形',
+      });
+
+      await addKeyframes({
+        draftId: draft.draftId,
+        keyframes: [
+          { segmentId: firstImage.segmentId, property: 'KFTypeScaleX', offset: 0, value: 1.0 },
+          { segmentId: firstImage.segmentId, property: 'KFTypeScaleX', offset: 5000000, value: 1.08 },
+          { segmentId: firstImage.segmentId, property: 'KFTypeScaleY', offset: 0, value: 1.0 },
+          { segmentId: firstImage.segmentId, property: 'KFTypeScaleY', offset: 5000000, value: 1.08 },
+        ],
+      });
+    },
+    render: {
+      cloud: true,
+      apiToken: process.env.CUT_API_TOKEN,
+      apiBase: process.env.CUT_UPLOAD_API_BASE,
+      wait: true,
+    },
+  });
+
+  console.log(result.draft.filePath);
+  console.log(result.render?.videoUrl);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/api/setup/templates/project/cut-sdk/examples/04-cli-examples.md

@@ -0,0 +1,71 @@
+# cut_sdk CLI 示例
+
+当用户希望使用命令行而不是 SDK 代码时，参考这些示例。
+
+## 创建草稿
+
+```bash
+cut draft create --width 1080 --height 1920 --pretty
+```
+
+输出中会包含 `draftId`，后续命令都使用这个草稿 ID。
+
+## 添加字幕
+
+```bash
+cut captions add <draftId> --captions '[
+  {
+    "text": "CLI 字幕示例",
+    "start": 0,
+    "end": 3000000,
+    "keyword": "CLI",
+    "keywordColor": "#00ffaa",
+    "inAnimation": "渐显",
+    "outAnimation": "渐隐",
+    "inAnimationDuration": 500000,
+    "outAnimationDuration": 500000
+  }
+]' --font-size 8 --text-color "#ffffff" --bold --pretty
+```
+
+## 添加图片
+
+```bash
+cut images add <draftId> --image-infos '[
+  {
+    "imageUrl": "/absolute/path/to/background.png",
+    "width": 1080,
+    "height": 1920,
+    "start": 0,
+    "end": 5000000
+  }
+]' --pretty
+```
+
+## 添加音频
+
+```bash
+cut audios add <draftId> --audio-infos '[
+  {
+    "audioUrl": "/absolute/path/to/music.mp3",
+    "duration": 5000000,
+    "start": 0,
+    "end": 5000000,
+    "volume": 0.7
+  }
+]' --pretty
+```
+
+## 渲染
+
+```bash
+cut cloud render <draftId> --wait --pretty
+```
+
+## JSON 文件输入
+
+大多数 JSON 参数也支持 `@file.json`：
+
+```bash
+cut captions add <draftId> --captions @captions.json --pretty
+```