API 参考

所有方法均从 cut_cli 包导出，返回 Promise。

import {
  createDraft, getDraftInfo, easyCreateMaterial,
  addCaptions, getCaptions,
  addImages, getImages,
  addVideos, getVideos,
  addAudios, getAudios,
  addEffects, getEffects,
  addSticker, getStickers,
  addKeyframes, getKeyframes,
  addMasks, getMasks,
  addTextStyle,
  getAudioDuration, getImageAnimations,
  registerDraftUrl,
} from 'cut_cli';

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

---

草稿管理

createDraft(params?)

创建新的剪映草稿。会在 draftsDir 下创建一个完整的剪映标准草稿文件夹，包含模板文件和 resources/ 媒体目录，可直接被剪映桌面端打开。

参数 CreateDraftInput

字段	类型	必填	默认值	说明
width	number	否	1080	画布宽度（像素）
height	number	否	1920	画布高度（像素）

返回 Promise<CreateDraftOutput>

字段	类型	说明
draftId	string	草稿唯一标识
filePath	string	草稿文件夹路径

示例

const draft = await createDraft({ width: 1080, height: 1920 });
console.log(draft.draftId);  // "a1b2c3d4-..."
console.log(draft.filePath); // "~/Movies/JianyingPro Drafts/a1b2c3d4-.../"

---

getDraftInfo(params)

获取草稿的基本信息。

参数 { draftId: string }

字段	类型	必填	说明
draftId	string	是	草稿 ID

返回 Promise<DraftInfo>

字段	类型	说明
draftId	string	草稿 ID
canvasWidth	number	画布宽度
canvasHeight	number	画布高度
duration	number	总时长（μs）
fps	number	帧率
trackSummary	{ id, type, segmentCount }[]	轨道摘要
materialSummary	object	素材统计（videos/audios/texts/stickers/effects）

示例

const info = await getDraftInfo({ draftId: 'abc123' });
console.log(`时长: ${info.duration / 1000000}秒`);

---

easyCreateMaterial(params)

按音频时长自动铺设素材，将图片/视频/文字铺满整个音频时长。传入的媒体 URL 会自动下载到草稿的 resources/ 目录。

参数 EasyCreateMaterialInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
audioUrl	string	是	音频 URL（自动下载）
imgUrl	string	否	图片 URL（自动下载）
videoUrl	string	否	视频 URL（自动下载）
text	string	否	文字内容
textColor	string	否	文字颜色
fontSize	number	否	字号
textTransformY	number	否	文字 Y 轴偏移

返回 Promise<EasyCreateMaterialOutput>

字段	类型	说明
draftId	string	草稿 ID
message	string	操作结果信息

示例

await easyCreateMaterial({
  draftId: 'abc123',
  audioUrl: 'https://example.com/audio.mp3',
  imgUrl: 'https://example.com/bg.jpg',
  text: '欢迎观看',
});

---

字幕

addCaptions(params)

向草稿批量添加字幕。

参数 AddCaptionsInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
captions	CaptionItem[] | string	是	字幕数组或 JSON 字符串
font	string	否	字体名称
alignment	number	否	对齐方式
alpha	number	否	透明度（0-1）
textColor	string	否	文字颜色
fontSize	number	否	字号
bold	boolean	否	加粗
italic	boolean	否	斜体
underline	boolean	否	下划线
textEffect	string	否	文字特效
letterSpacing	number	否	字间距
lineSpacing	number	否	行间距
borderColor	string	否	描边颜色
styleText	boolean	否	是否应用样式
hasShadow	boolean	否	是否有阴影
shadowInfo	object	否	阴影配置（见下方）
scaleX	number	否	X 轴缩放
scaleY	number	否	Y 轴缩放
transformX	number	否	X 轴位移
transformY	number	否	Y 轴位移

shadowInfo 对象：

字段	类型	说明
shadowColor	string	阴影颜色
shadowAlpha	number	阴影透明度
shadowDiffuse	number	阴影扩散
shadowDistance	number	阴影距离
shadowAngle	number	阴影角度

CaptionItem 对象：

字段	类型	必填	说明
text	string	是	字幕文本
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
keyword	string	否	关键词高亮文本
keywordColor	string	否	关键词颜色
fontSize	number	否	单条字号
keywordFontSize	number	否	关键词字号
inAnimation	string	否	入场动画名
outAnimation	string	否	出场动画名
loopAnimation	string	否	循环动画名
inAnimationDuration	number	否	入场动画时长（μs）
outAnimationDuration	number	否	出场动画时长（μs）
loopAnimationDuration	number	否	循环动画时长（μs）

返回 Promise<AddCaptionsOutput>

字段	类型	说明
draftId	string	草稿 ID
trackId	string	轨道 ID
textIds	string[]	文本素材 ID 列表
segmentIds	string[]	片段 ID 列表
segmentInfos	SegmentInfo[]	片段详情（id/start/end）

示例

const result = await addCaptions({
  draftId: 'abc123',
  captions: [
    { text: '第一句话', start: 0, end: 3000000 },
    { text: '第二句话', start: 3000000, end: 6000000 },
  ],
  fontSize: 8,
  textColor: '#FFFFFF',
  bold: true,
});

---

getCaptions(params)

获取草稿中的所有字幕。

参数 { draftId: string }

返回 Promise<CaptionInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
text	string	字幕文本
start	number	开始时间（μs）
duration	number	持续时间（μs）
materialId	string	素材 ID

---

图片

addImages(params)

向草稿添加图片素材。传入的图片 URL 会自动下载到草稿的 resources/ 目录，工程 JSON 中使用本地路径引用。

参数 AddImagesInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
imageInfos	ImageItem[] | string	是	图片数组或 JSON 字符串
alpha	number	否	透明度（0-1）
scaleX	number	否	X 轴缩放
scaleY	number	否	Y 轴缩放
transformX	number	否	X 轴位移
transformY	number	否	Y 轴位移

ImageItem 对象：

字段	类型	必填	说明
imageUrl	string	是	图片 URL（自动下载到本地）
width	number	是	宽度（像素）
height	number	是	高度（像素）
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
inAnimation	string	否	入场动画名
outAnimation	string	否	出场动画名
loopAnimation	string	否	循环动画名
inAnimationDuration	number	否	入场动画时长（μs）
outAnimationDuration	number	否	出场动画时长（μs）
loopAnimationDuration	number	否	循环动画时长（μs）
transition	string	否	转场效果名
transitionDuration	number	否	转场时长（μs）

返回 Promise<AddImagesOutput>

字段	类型	说明
draftId	string	草稿 ID
trackId	string	轨道 ID
imageIds	string[]	图片素材 ID 列表
segmentIds	string[]	片段 ID 列表
segmentInfos	SegmentInfo[]	片段详情

示例

const result = await addImages({
  draftId: 'abc123',
  imageInfos: [
    { imageUrl: 'https://example.com/1.jpg', width: 1920, height: 1080, start: 0, end: 5000000 },
    { imageUrl: 'https://example.com/2.jpg', width: 1920, height: 1080, start: 5000000, end: 10000000 },
  ],
});

---

getImages(params)

获取草稿中的所有图片素材。

参数 { draftId: string }

返回 Promise<ImageInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
materialUrl	string	素材本地路径（占位符格式）
width	number	宽度
height	number	高度
start	number	开始时间（μs）
duration	number	持续时间（μs）
materialId	string	素材 ID

---

视频

addVideos(params)

向草稿添加视频素材，支持变速和曲线变速。传入的视频 URL 会自动下载到草稿的 resources/ 目录。

参数 AddVideosInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
videoInfos	VideoItem[] | string	是	视频数组或 JSON 字符串
alpha	number	否	透明度（0-1）
scaleX	number	否	X 轴缩放
scaleY	number	否	Y 轴缩放
transformX	number	否	X 轴位移
transformY	number	否	Y 轴位移
sceneTimelines	SceneTimeline[]	否	场景时间线（变速/曲线变速）

VideoItem 对象：

字段	类型	必填	说明
videoUrl	string	是	视频 URL（自动下载到本地）
width	number	是	宽度（像素）
height	number	是	高度（像素）
duration	number	是	视频原始时长（μs）
start	number	是	在时间线的开始时间（μs）
end	number	是	在时间线的结束时间（μs）
mask	string	否	遮罩
transition	string	否	转场效果名
transitionDuration	number	否	转场时长（μs）
volume	number	否	音量

SceneTimeline 对象：

字段	类型	必填	说明
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
curveSpeed	string	否	曲线变速配置

返回 Promise<AddVideosOutput>

字段	类型	说明
draftId	string	草稿 ID
trackId	string	轨道 ID
videoIds	string[]	视频素材 ID 列表
segmentIds	string[]	片段 ID 列表

示例

const result = await addVideos({
  draftId: 'abc123',
  videoInfos: [
    {
      videoUrl: 'https://example.com/video.mp4',
      width: 1920, height: 1080,
      duration: 10000000,
      start: 0, end: 10000000,
    },
  ],
});

---

getVideos(params)

获取草稿中的所有视频片段（不含图片类型）。

参数 { draftId: string }

返回 Promise<VideoInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
materialUrl	string	素材本地路径（占位符格式）
width	number	宽度
height	number	高度
start	number	开始时间（μs）
duration	number	持续时间（μs）
materialId	string	素材 ID

---

音频

addAudios(params)

向草稿添加音频素材。传入的音频 URL 会自动下载到草稿的 resources/ 目录。

参数 AddAudiosInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
audioInfos	AudioItem[] | string	是	音频数组或 JSON 字符串

AudioItem 对象：

字段	类型	必填	说明
audioUrl	string	是	音频 URL（自动下载到本地）
duration	number	是	音频时长（μs）
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
audioEffect	string	否	音效名称
volume	number	否	音量

返回 Promise<AddAudiosOutput>

字段	类型	说明
draftId	string	草稿 ID
trackId	string	轨道 ID
audioIds	string[]	音频素材 ID 列表

示例

const result = await addAudios({
  draftId: 'abc123',
  audioInfos: [
    {
      audioUrl: 'https://example.com/bgm.mp3',
      duration: 60000000,
      start: 0,
      end: 60000000,
      volume: 0.8,
    },
  ],
});

---

getAudios(params)

获取草稿中的所有音频片段。

参数 { draftId: string }

返回 Promise<AudioInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
materialUrl	string	素材本地路径（占位符格式）
start	number	开始时间（μs）
duration	number	持续时间（μs）
volume	number	音量
materialId	string	素材 ID

---

特效

addEffects(params)

向草稿添加视频特效。

参数 AddEffectsInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
effectInfos	EffectItem[] | string	是	特效数组或 JSON 字符串

EffectItem 对象：

字段	类型	必填	说明
effectTitle	string	是	特效名称
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）

返回 Promise<AddEffectsOutput>

字段	类型	说明
draftId	string	草稿 ID
trackId	string	轨道 ID
effectIds	string[]	特效素材 ID 列表
segmentIds	string[]	片段 ID 列表

示例

const result = await addEffects({
  draftId: 'abc123',
  effectInfos: [
    { effectTitle: '模糊', start: 0, end: 3000000 },
  ],
});

---

getEffects(params)

获取草稿中的所有特效。

参数 { draftId: string }

返回 Promise<EffectInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
start	number	开始时间（μs）
duration	number	持续时间（μs）
materialId	string	素材 ID

---

贴纸

addSticker(params)

向草稿添加贴纸。

参数 AddStickerInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
stickerId	string	是	贴纸资源 ID
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
scale	number	否	缩放比例
transformX	number	否	X 轴位移
transformY	number	否	Y 轴位移

返回 Promise<AddStickerOutput>

字段	类型	说明
draftId	string	草稿 ID

示例

await addSticker({
  draftId: 'abc123',
  stickerId: 'sticker_001',
  start: 0,
  end: 5000000,
  scale: 1.5,
});

---

getStickers(params)

获取草稿中的所有贴纸。

参数 { draftId: string }

返回 Promise<StickerInfo[]>

字段	类型	说明
segmentId	string	片段 ID
trackId	string	轨道 ID
start	number	开始时间（μs）
duration	number	持续时间（μs）
materialId	string	素材 ID

---

关键帧

addKeyframes(params)

为草稿中的片段添加关键帧动画。

参数 AddKeyframesInput

字段	类型	必填	说明
draftId	string	是	草稿 ID
keyframes	KeyframeItem[] | string	是	关键帧数组或 JSON 字符串

KeyframeItem 对象：

字段	类型	必填	说明
segmentId	string	是	所属片段 ID
property	string	是	属性名（如 scale_x、position_x）
offset	number	是	在片段内的时间偏移（μs）
value	number	是	属性值

返回 Promise<AddKeyframesOutput>

字段	类型	说明
draftId	string	草稿 ID

示例

await addKeyframes({
  draftId: 'abc123',
  keyframes: [
    { segmentId: 'seg_001', property: 'scale_x', offset: 0, value: 1.0 },
    { segmentId: 'seg_001', property: 'scale_x', offset: 3000000, value: 1.5 },
  ],
});

---

getKeyframes(params)

获取指定片段的关键帧列表。

参数 { draftId: string; segmentId: string }

字段	类型	必填	说明
draftId	string	是	草稿 ID
segmentId	string	是	片段 ID

返回 Promise<KeyframeInfo[]>

字段	类型	说明
property	string	属性名
timeOffset	number	时间偏移（μs）
value	number	属性值

---

遮罩

addMasks(params)

为草稿中的多个片段批量添加遮罩。

参数 AddMasksInput

字段	类型	必填	默认值	说明
draftId	string	是	—	草稿 ID
segmentIds	string[]	是	—	目标片段 ID 列表
name	string	否	线性	遮罩类型名称
X	number	否	—	中心 X 坐标
Y	number	否	—	中心 Y 坐标
width	number	否	—	宽度
height	number	否	—	高度
feather	number	否	—	羽化值
rotation	number	否	—	旋转角度
invert	boolean	否	—	反转遮罩
roundCorner	number	否	—	圆角

返回 Promise<AddMasksOutput>

字段	类型	说明
draftId	string	草稿 ID

示例

await addMasks({
  draftId: 'abc123',
  segmentIds: ['seg_001', 'seg_002'],
  name: '线性',
  feather: 0.5,
  rotation: 45,
});

---

getMasks(params)

获取草稿中的遮罩信息。

参数 { draftId: string; segmentId?: string }

字段	类型	必填	说明
draftId	string	是	草稿 ID
segmentId	string	否	过滤指定片段

返回 Promise<MaskInfo[]>

字段	类型	说明
id	string	遮罩 ID
name	string	遮罩类型名称
resourceType	string	资源类型
config	object	遮罩配置
config.centerX	number	中心 X
config.centerY	number	中心 Y
config.width	number	宽度
config.height	number	高度
config.feather	number	羽化
config.rotation	number	旋转
config.invert	boolean	是否反转
config.roundCorner	number	圆角

---

文字样式

addTextStyle(params)

生成文字样式 JSON（不写入草稿），可用于关键词高亮等场景。

参数 AddTextStyleInput

字段	类型	必填	说明
text	string	是	文字内容
keyword	string	是	关键词（多个用 | 分隔）
keywordColor	string	否	关键词颜色
fontSize	number	否	默认字号
keywordFontSize	number	否	关键词字号

返回 Promise<AddTextStyleOutput>

字段	类型	说明
textStyle	string	生成的样式 JSON 字符串

示例

const { textStyle } = await addTextStyle({
  text: '欢迎来到我的世界',
  keyword: '世界',
  keywordColor: '#FF0000',
  keywordFontSize: 12,
});

---

工具查询

getAudioDuration(params)

获取远程音频文件的时长。

参数 GetAudioDurationInput

字段	类型	必填	说明
url	string	是	音频文件 URL

返回 Promise<GetAudioDurationOutput>

字段	类型	说明
message	string	状态信息
duration	number	音频时长（μs）

示例

const { duration } = await getAudioDuration({ url: 'https://example.com/audio.mp3' });
console.log(`时长: ${duration / 1000000}秒`);

---

getImageAnimations(params?)

获取可用的图片动画效果列表。

参数 GetImageAnimationsInput（可选）

字段	类型	必填	默认值	说明
mode	number	否	0	模式
type	'in' | 'out' | 'loop'	否	'in'	动画类型

返回 Promise<GetImageAnimationsOutput>

字段	类型	说明
effects	any[]	动画效果列表

示例

const { effects } = await getImageAnimations({ type: 'in' });
console.log(`共 ${effects.length} 个入场动画`);

---

工具函数

registerDraftUrl(draftId, ossUrl)

手动注册草稿 ID 与 OSS URL 的映射关系，之后可用短 draftId 加载草稿。

参数

字段	类型	必填	说明
draftId	string	是	草稿 ID
ossUrl	string	是	OSS 存储地址

返回 void

示例

registerDraftUrl('abc123', 'https://oss.example.com/draft/abc123/draft_content.json');

---

类型导出

所有 TypeScript 类型接口均从包中导出，可直接引用：

import type {
  CreateDraftInput, CreateDraftOutput, DraftInfo,
  EasyCreateMaterialInput, EasyCreateMaterialOutput,
  CaptionItem, AddCaptionsInput, AddCaptionsOutput, CaptionInfo,
  ImageItem, AddImagesInput, AddImagesOutput, ImageInfo,
  VideoItem, SceneTimeline, AddVideosInput, AddVideosOutput, VideoInfo,
  AudioItem, AddAudiosInput, AddAudiosOutput, AudioInfo,
  EffectItem, AddEffectsInput, AddEffectsOutput, EffectInfo,
  AddStickerInput, AddStickerOutput, StickerInfo,
  KeyframeItem, AddKeyframesInput, AddKeyframesOutput, KeyframeInfo,
  AddMasksInput, AddMasksOutput, MaskInfo,
  AddTextStyleInput, AddTextStyleOutput,
  GetAudioDurationInput, GetAudioDurationOutput,
  GetImageAnimationsInput, GetImageAnimationsOutput,
  SegmentInfo,
} from 'cut_cli';