Node.js SDK overview

cut_cli ships an npm package alongside the standalone binary. Most users only need the binary (install via curl -s https://cutcli.com/cli | bash) — but if you're building automation in JavaScript / TypeScript, the SDK exposes the same operations as plain functions.

Install

npm install cut_cli

Minimal example

import {
  createDraft,
  addCaptions,
  addImages,
  addAudios,
  renderDraft,
  getCloudJob,
} from 'cut_cli';

const draft = await createDraft({ width: 1080, height: 1920 });

await addCaptions({
  draftId: draft.draftId,
  captions: [{ text: 'Hello', start: 0, end: 3000000 }],
  fontSize: 8,
  bold: true,
});

await addImages({
  draftId: draft.draftId,
  imageInfos: [{
    imageUrl: 'https://cutcli.com/assets/demo/scene-01.jpg',
    width: 1080,
    height: 1920,
    start: 0,
    end: 3000000,
  }],
});

await addAudios({
  draftId: draft.draftId,
  audioInfos: [{
    audioUrl: 'https://cutcli.com/assets/demo/bgm-light.mp3',
    duration: 3000000,
    start: 0,
    end: 3000000,
    volume: 0.5,
  }],
});

const submitted = await renderDraft({ draftId: draft.draftId });
const detail = await getCloudJob({ id: submitted.renderJob.id });
console.log(detail.renderJob.status, detail.renderJob.video_url);

Available functions

The SDK mirrors the CLI surface 1:1. Function names are camelCase versions of the CLI subcommands:

CLI	SDK
cutcli draft create	createDraft({ width, height, name? })
cutcli draft list	listDrafts()
cutcli draft info	getDraftInfo({ draftId })
cutcli draft easy	easyCreateMaterial({ draftId, audioUrl, imgUrl?, videoUrl?, text? })
cutcli draft zip	zipDraft({ draftId, output? })
cutcli draft upload	uploadDraft({ draftId })
cutcli cloud render	renderDraft({ draftId, zipPath? })
cutcli cloud jobs	getCloudJobs({ status? })
cutcli cloud job	getCloudJob({ id })
cutcli cloud result	getCloudJob({ id })
cutcli timer render --count 1	runScheduledRenderOnce(options?, runNumber?)
cutcli timer render	startScheduledDraftRendering(options?)
cutcli captions add	addCaptions({ draftId, captions, ...style })
cutcli captions list	getCaptions({ draftId })
cutcli images add	addImages({ draftId, imageInfos })
cutcli images list	getImages({ draftId })
cutcli videos add	addVideos({ draftId, videoInfos })
cutcli videos list	getVideos({ draftId })
cutcli audios add	addAudios({ draftId, audioInfos })
cutcli audios list	getAudios({ draftId })
cutcli effects add	addEffects({ draftId, effectInfos })
cutcli effects list	getEffects({ draftId })
cutcli sticker add	addSticker({ draftId, stickerId, start, end, scale? })
cutcli sticker list	getStickers({ draftId })
cutcli keyframes add	addKeyframes({ draftId, keyframes })
cutcli keyframes list	getKeyframes({ draftId, segmentId })
cutcli masks add	addMasks({ draftId, segmentIds, ...options })
cutcli masks list	getMasks({ draftId, segmentId? })
cutcli filters add	addFilters({ draftId, filterInfos })
cutcli text-style	addTextStyle({ text, keyword, ...style })

Cloud rendering

The cloud SDK helpers use the same credentials as the CLI. Save them with cutcli auth set --api-key <key>, or set CUTCLI_API_KEY in the environment before running your Node.js process.

import {
  renderDraft,
  getCloudJobs,
  getCloudJob,
  runScheduledRenderOnce,
  startScheduledDraftRendering,
} from 'cut_cli';

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

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

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

await runScheduledRenderOnce({
  namePrefix: 'smoke_test',
  captionText: 'Cloud render smoke test {time}',
});

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

Field shapes

The JSON shapes accepted by the SDK are exactly the same as the CLI's --captions / --image-infos / etc. arrays. See:

• captions
• images
• videos
• audios
• keyframes

TypeScript types

import type {
  Caption,
  ImageInfo,
  VideoInfo,
  AudioInfo,
  EffectInfo,
  Keyframe,
  // ... and so on
} from 'cut_cli';

Where the full per-function reference lives

The exhaustive parameter tables (every option, default value, error case) live in:

• /zh/reference/api — full Chinese reference, auto-synced from the source repo
• TypeScript declaration files inside the npm package: node_modules/cut_cli/dist/index.d.ts
• Source on the closed-source repo (request access via the maintainer)

Or simply:

node -e "console.log(Object.keys(require('cut_cli')))"

to see every exported name.