API 参考

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

import {
  createDraft, getDraftInfo, listDrafts, easyCreateMaterial,
  zipDraft, uploadDraft,
  renderDraft, getCloudJob, getCloudJobs,
  runScheduledRenderOnce, startScheduledDraftRendering,
  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	画布高度（像素）
name	string	否	自动生成	草稿名称
userId	string	否	-	用户 ID

返回 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}秒`);

---

listDrafts()

列出当前草稿目录下的所有剪映草稿，按修改时间倒序返回。

返回 Promise<DraftListItem[]>

字段	类型	说明
draftId	string	草稿 ID 或草稿目录名
filePath	string	草稿文件夹路径
name	string	草稿名称
duration	number	草稿总时长（μs）
canvasWidth / canvasHeight	number	画布尺寸
createdAt / modifiedAt	number	创建和修改时间戳

示例

const drafts = await listDrafts();
console.log(drafts[0]?.draftId);

---

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: '欢迎观看',
});

---

zipDraft(params)

将本地剪映草稿文件夹打包为 zip。

参数 ZipDraftInput

字段	类型	必填	说明
draftId	string	是	草稿 ID 或草稿名称
outputPath	string	否	输出 zip 路径；不传则写到草稿目录同级

返回 Promise<ZipDraftOutput>

字段	类型	说明
message	string	状态信息
zipPath	string	zip 文件路径
size	number	zip 文件大小（字节）

示例

const zip = await zipDraft({ draftId: 'abc123' });
console.log(zip.zipPath);

---

uploadDraft(params)

打包并上传草稿 zip，返回云端下载链接。需要先通过 cutcli auth set 保存 API Key，或在当前进程设置 CUTCLI_API_KEY。

参数 UploadDraftInput

字段	类型	必填	说明
draftId	string	是	草稿 ID 或草稿名称
zipPath	string	否	已有 zip 路径；不传则自动调用 zipDraft

返回 Promise<UploadDraftOutput>

字段	类型	说明
message	string	状态信息
draftUploadId	string	云端草稿上传记录 ID
downloadUrl	string	草稿 zip 下载链接
zipPath	string	本地 zip 路径
size	number	zip 文件大小（字节）

示例

const upload = await uploadDraft({ draftId: 'abc123' });
console.log(upload.downloadUrl);

---

云渲染

renderDraft(params)

上传草稿并创建云渲染任务。未传 zipPath 时会自动打包草稿；设置 wait: true 时会继续轮询任务，直到完成、失败或超时。

参数 RenderDraftInput

字段	类型	必填	说明
draftId	string	是	草稿 ID 或草稿名称
zipPath	string	否	已有 zip 路径
wait	boolean	否	是否等待渲染结果
pollIntervalMs	number	否	等待时的轮询间隔，默认 15000
timeoutMs	number	否	等待超时，默认 1800000

返回 Promise<RenderDraftOutput>

字段	类型	说明
message	string	状态信息
draftUploadId	string	云端草稿上传记录 ID
downloadUrl	string	草稿 zip 下载链接
jobId	string	云渲染任务 ID
status	string	当前任务状态
videoUrl	string	渲染完成后的视频链接
failureReason	string	失败原因
renderJob	RenderJob	云渲染任务对象
resultCommand	string	查询结果的 CLI 命令

示例

const result = await renderDraft({ draftId: 'abc123' });
console.log(result.renderJob.id, result.renderJob.status);

const completed = await renderDraft({ draftId: 'abc123', wait: true });
console.log(completed.videoUrl);

---

getCloudJobs(params?)

查询当前用户的云渲染任务列表。

参数 { status?: string }

字段	类型	必填	说明
status	string	否	按状态筛选，如 queued、rendering、completed、failed

返回 Promise<RenderJob[]>

字段	类型	说明
id	string	任务 ID
status	string	任务状态
draft_upload_id	string	草稿上传记录 ID
draft_download_url	string	草稿 zip 下载链接
video_url	string	渲染完成后的成片地址
failure_reason	string	失败原因

示例

const jobs = await getCloudJobs({ status: 'queued' });
console.log(jobs.length);

---

getCloudJob(params)

查询单个云渲染任务详情和事件记录。

参数 { id: string }

字段	类型	必填	说明
id	string	是	云渲染任务 ID

返回 Promise<RenderJobDetail>

字段	类型	说明
renderJob	RenderJob	任务详情
events	Array<Record<string, unknown>>	任务事件记录

示例

const detail = await getCloudJob({ id: 'job_xxx' });
console.log(detail.renderJob.video_url);

---

runScheduledRenderOnce(options?, runNumber?)

创建一个草稿、可选添加默认字幕、上传并提交一次云渲染。适合把定时逻辑交给外部调度系统时调用。

常用参数 ScheduledRenderOptions

字段	类型	默认值	说明
width / height	number	1080 / 1920	画布尺寸
namePrefix	string	auto_render	草稿名称前缀
caption	boolean	true	是否添加默认字幕
captionText	string	Auto render #{count}\n{time}	字幕模板，支持 {count}、{run}、{time}、{iso}、{draftId}
durationSeconds	number	5	默认字幕时长
fontSize	number	12	默认字幕字号
textColor	string	#ffffff	默认字幕颜色
onEvent	function	-	监听草稿创建、任务提交等事件

示例

const run = await runScheduledRenderOnce({
  namePrefix: 'smoke_test',
  captionText: 'Render #{count} {time}',
});
console.log(run.renderJob.id);

---

startScheduledDraftRendering(options?)

启动内置定时循环，按固定间隔创建草稿、上传并提交云渲染。默认立即执行一次，然后每 5 分钟执行一次。

常用参数 ScheduledRenderOptions

字段	类型	默认值	说明
intervalMs	number	300000	执行间隔，单位毫秒
count	number	无限	执行次数
immediate	boolean	true	是否立即执行第一次
signal	AbortSignal	-	用于停止定时循环
onEvent	function	-	监听 scheduler-started、run-started、render-submitted、run-failed 等事件

返回 Promise<ScheduledRenderSummary>

字段	类型	说明
completedRuns	number	已完成次数
successfulRuns	number	成功次数
failedRuns	number	失败次数
startedAt / stoppedAt	string	开始和停止时间

示例

await startScheduledDraftRendering({
  intervalMs: 5 * 60 * 1000,
  count: 1,
  onEvent: (event) => console.log(event.type),
});

---

字幕

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）
mask	string | object	否	图片蒙版，支持 线性/镜面/圆形/矩形/星形/爱心，默认 圆形
maskX / maskY	number	否	蒙版中心偏移（像素，基于图片中心）
maskWidth / maskHeight	number	否	蒙版宽高（像素）
maskFeather	number	否	蒙版羽化（0-100）
maskExpansion	number	否	蒙版扩展（0-100）
maskRotation	number	否	蒙版旋转角度
maskInvert	boolean	否	反转蒙版
maskRoundCorner	number	否	矩形蒙版圆角（0-100）
maskAspectRatio	number	否	形状宽高比（默认使用 CapCut 对应蒙版的原始值）
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 列表
maskIds	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,
      mask: '圆形',
      maskWidth: 720,
      maskHeight: 720,
      maskFeather: 12,
    },
    { 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 对象：

字段	类型	必填	说明
effectId	string	否	特效 ID，和 effectTitle 二选一
effectTitle	string	否	特效名称，和 effectId 二选一
start	number	是	开始时间（μs）
end	number	是	结束时间（μs）
effectType	screen | face	否	特效类型，默认 screen

返回 Promise<AddEffectsOutput>

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

示例

const result = await addEffects({
  draftId: 'abc123',
  effectInfos: [
    { effectId: '7399468886309162246', start: 0, end: 3000000 },
    { 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 | KeyframeGroup)[] | string	是	关键帧数组或 JSON 字符串

KeyframeItem 对象：

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

也支持按属性分组的 KeyframeGroup：

字段	类型	必填	说明
segmentId	string	是	所属片段 ID
property	string	是	属性名（如 scale_x、position_x）
keyframes	array	是	关键帧点数组，点内使用 time/offset 与 value

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

await addKeyframes({
  draftId: 'abc123',
  keyframes: [
    {
      segmentId: 'seg_001',
      property: 'position_x',
      keyframes: [
        { time: 0, value: -0.5, easing: 'ease_in_out' },
        { time: 3000000, value: 0.5, easing: 'linear' },
      ],
    },
  ],
});

---

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';