zerocut-cli 0.2.1 → 0.3.0

package/README.md

@@ -101,7 +101,7 @@ zerocut config --ott <token> --region <cn|us>   # non-interactive
 - `image` — create a new image (default action; requires `--prompt`)
   - Options:
     - `--prompt <prompt>` (required)
-    - `--model <model>` (seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan)
+    - `--model <model>` (seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan|wan-pro)
     - `--aspectRatio <ratio>` (1:1|3:4|4:3|16:9|9:16|2:3|3:2|21:9|1:4|4:1|1:8|8:1)
     - `--resolution <resolution>` (1K|2K|4K)
     - `--refs <img1,img2,...>` (comma-separated paths/URLs)
@@ -110,15 +110,18 @@ zerocut config --ott <token> --region <cn|us>   # non-interactive
   - Options:
     - `--prompt <prompt>` (required)
     - `--duration <seconds>` (integer 1–16; when `--sourceVideo` is set, must be 3–10)
-    - `--model <model>` (enum: `zerocut3.0|zerocut3.0-pro|zerocut3.0-pro-fast|seedance-1.5-pro|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro`; default `vidu`)
+    - `--model <model>` (enum: `zerocut3.0|zerocut3.0-pro|zerocut3.0-pro-fast|zerocut3.0-turbo|seedance-1.5-pro|seedance-2.0|seedance-2.0-fast|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro`; default `vidu`)
     - `--sourceVideo <video>` (base video path/url for edit mode)
     - `--seed <seed>`
     - `--firstFrame <image>`
     - `--lastFrame <image>`
+    - `--storyboard <image>`
+    - `--persons <persons>` (comma-separated person image paths/URLs)
     - `--refs <assets>`
     - `--resolution <resolution>`
     - `--aspectRatio <ratio>` (9:16|16:9|1:1)
     - `--withAudio`
+    - `--withBGM <withBGM>` (true|false, default true)
     - `--optimizeCameraMotion`
     - `--output <file>`
   - Notes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerocut-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "ZeroCut CLI: AI assistant CLI for creating and editing images/audio/video",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
     "typescript-eslint": "^8.54.0"
   },
   "dependencies": {
-    "cerevox": "^4.29.3",
+    "cerevox": "^4.46.0",
     "commander": "^14.0.3",
     "inquirer": "^13.2.2"
   },

package/src/commands/image.ts

@@ -19,6 +19,7 @@ export function register(program: Command): void {
     "banana2",
     "banana-pro",
     "wan",
+    "wan-pro",
   ] as const;
   type AllowedModel = (typeof allowedModels)[number];
   const allowedAspectRatios = [
@@ -67,6 +68,7 @@ export function register(program: Command): void {
       aspect_ratio: aspectRatio,
       resolution,
       reference_images: referenceImages,
+      sequential_image_generation: "disabled",
       onProgress,
     };
     const res = await (session.ai.generateImage as (arg: Record<string, unknown>) => Promise<any>)(

package/src/commands/skill.ts

@@ -5,16 +5,33 @@ import path from "node:path";
 export const name = "skill";
 export const description = "Print built-in SKILL.md content";
 
+function printSkill(relativePath: string): void {
+  const filePath = path.resolve(__dirname, relativePath);
+  const content = fs.readFileSync(filePath, "utf8");
+  process.stdout.write(content);
+  if (!content.endsWith("\n")) {
+    process.stdout.write("\n");
+  }
+}
+
 export function register(program: Command): void {
-  program
-    .command("skill")
-    .description("Print built-in skill markdown")
+  const parent = program.command("skill").description("Print built-in skill markdown");
+
+  parent
+    .command("one-click-video")
+    .description("Print one-click-video skill markdown")
     .action(() => {
-      const filePath = path.resolve(__dirname, "../skill/SKILL.md");
-      const content = fs.readFileSync(filePath, "utf8");
-      process.stdout.write(content);
-      if (!content.endsWith("\n")) {
-        process.stdout.write("\n");
-      }
+      printSkill("../skill/one-click-video/SKILL.md");
     });
+
+  parent
+    .command("edit-video")
+    .description("Print edit-video skill markdown")
+    .action(() => {
+      printSkill("../skill/edit-video/SKILL.md");
+    });
+
+  parent.action(() => {
+    printSkill("../skill/SKILL.md");
+  });
 }

package/src/commands/video.ts

@@ -34,7 +34,10 @@ export function register(program: Command): void {
     "zerocut3.0",
     "zerocut3.0-pro",
     "zerocut3.0-pro-fast",
+    "zerocut3.0-turbo",
     "seedance-1.5-pro",
+    "seedance-2.0",
+    "seedance-2.0-fast",
     "vidu",
     "vidu-pro",
     "viduq3",
@@ -61,10 +64,13 @@ export function register(program: Command): void {
       seed?: string;
       firstFrame?: string;
       lastFrame?: string;
+      storyboard?: string;
+      persons?: string;
       refs?: string;
       resolution?: "720p" | "1080p";
       aspectRatio?: "9:16" | "16:9" | "1:1";
       withAudio?: boolean;
+      withBGM?: string;
       optimizeCameraMotion?: boolean;
       output?: string;
     }
@@ -122,8 +128,21 @@ export function register(program: Command): void {
       return;
     }
     const aspectRatio = ar as (typeof allowedAspectRatios)[number] | undefined;
+    let withBGM = true;
+    if (typeof opts.withBGM === "string") {
+      const withBGMRaw = opts.withBGM.trim().toLowerCase();
+      if (withBGMRaw === "true") {
+        withBGM = true;
+      } else if (withBGMRaw === "false") {
+        withBGM = false;
+      } else {
+        process.stderr.write("Invalid value for --withBGM: expected true|false\n");
+        process.exitCode = 1;
+        return;
+      }
+    }
     const images: {
-      type: "first_frame" | "last_frame" | "reference" | "storyboard";
+      type: "first_frame" | "last_frame" | "reference" | "storyboard" | "person";
       url: string;
       name?: string;
     }[] = [];
@@ -139,6 +158,25 @@ export function register(program: Command): void {
         url: await getMaterialUri(session, opts.lastFrame),
       });
     }
+    if (opts.storyboard) {
+      images.push({
+        type: "storyboard",
+        url: await getMaterialUri(session, opts.storyboard),
+      });
+    }
+    const personList =
+      typeof opts.persons === "string" && opts.persons.length > 0
+        ? opts.persons
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : [];
+    for (const person of personList) {
+      images.push({
+        type: "person",
+        url: await getMaterialUri(session, person),
+      });
+    }
     const refsList =
       typeof opts.refs === "string" && opts.refs.length > 0
         ? opts.refs
@@ -152,13 +190,14 @@ export function register(program: Command): void {
         url: await getMaterialUri(session, ref),
       });
     }
-    const res = await session.ai.generateVideo({
+    const request = {
       prompt,
       model: model as unknown as Parameters<typeof session.ai.generateVideo>[0]["model"],
       duration: duration || undefined,
       resolution: opts.resolution,
       aspect_ratio: aspectRatio,
       mute: !(opts.withAudio ?? true),
+      bgm: withBGM,
       optimize_camera: opts.optimizeCameraMotion,
       seed: opts.seed ? Number.parseInt(opts.seed, 10) : undefined,
       images: images.length > 0 ? images : undefined,
@@ -172,7 +211,8 @@ export function register(program: Command): void {
         : undefined,
       onProgress: createProgressSpinner("inferencing"),
       timeout: 7_200_000,
-    });
+    } as unknown as Parameters<typeof session.ai.generateVideo>[0];
+    const res = await session.ai.generateVideo(request);
     const initialUrl = resolveResultUrl(res);
     try {
       if (initialUrl) {
@@ -219,10 +259,13 @@ export function register(program: Command): void {
     .option("--seed <seed>", "Random seed")
     .option("--firstFrame <image>", "First frame image path/url")
     .option("--lastFrame <image>", "Last frame image path/url")
+    .option("--storyboard <image>", "Storyboard image path/url")
+    .option("--persons <persons>", "Comma-separated person image paths/urls")
     .option("--refs <refs>", "Comma-separated reference image/video paths/urls")
     .option("--resolution <resolution>", "Resolution, e.g., 720p")
     .option("--aspectRatio <ratio>", "Aspect ratio: 9:16|16:9|1:1")
     .option("--withAudio", "Include audio track")
+    .option("--withBGM <withBGM>", "Include background music: true|false (default: true)")
     .option("--optimizeCameraMotion", "Optimize camera motion")
     .option("--output <file>", "Output file path")
     .action(videoCreateAction);
@@ -241,10 +284,13 @@ export function register(program: Command): void {
     .option("--seed <seed>", "Random seed")
     .option("--firstFrame <image>", "First frame image path/url")
     .option("--lastFrame <image>", "Last frame image path/url")
+    .option("--storyboard <image>", "Storyboard image path/url")
+    .option("--persons <persons>", "Comma-separated person image paths/urls")
     .option("--refs <refs>", "Comma-separated reference image/video paths/urls")
     .option("--resolution <resolution>", "Resolution, e.g., 720p")
     .option("--aspectRatio <ratio>", "Aspect ratio: 9:16|16:9|1:1")
     .option("--withAudio", "Include audio track")
+    .option("--withBGM <withBGM>", "Include background music: true|false (default: true)")
     .option("--optimizeCameraMotion", "Optimize camera motion")
     .option("--output <file>", "Output file path")
     .action(videoCreateAction);

package/src/services/config.ts

@@ -204,7 +204,14 @@ export function applyConfigInterceptor(program: Command): void {
     const current = (actionCommand ?? thisCommand) as Command;
     const name = current?.name?.();
     const parentName = current?.parent?.name?.();
-    if (name === "help" || name === "skill" || name === "config" || parentName === "config") return;
+    if (
+      name === "help" ||
+      name === "skill" ||
+      name === "config" ||
+      parentName === "config" ||
+      parentName === "skill"
+    )
+      return;
     const ok = await ensureConfig();
     if (!ok) {
       process.exit(1);
@@ -217,7 +224,8 @@ export function applyConfigInterceptor(program: Command): void {
   });
   program.hook("postAction", async (thisCommand, actionCommand) => {
     const name = actionCommand?.name?.() ?? thisCommand?.name?.();
-    if (name === "help" || name === "skill") return;
+    const parentName = actionCommand?.parent?.name?.() ?? thisCommand?.parent?.name?.();
+    if (name === "help" || name === "skill" || parentName === "skill") return;
     try {
       const cmd = (actionCommand ?? thisCommand) as Command & {
         [SESSION_SYMBOL]?: import("cerevox").Session;

package/src/skill/SKILL.md

@@ -81,6 +81,21 @@ Notes:
 
 ## Command Reference
 
+### skill
+
+Use `skill` command to fetch built-in skill markdown:
+
+```bash
+npx zerocut-cli skill
+npx zerocut-cli skill one-click-video
+npx zerocut-cli skill edit-video
+```
+
+Routing rules:
+
+- When user requests one-click video creation, run `npx zerocut-cli skill one-click-video` to get the sub-skill and execute.
+- When user requests video editing, run `npx zerocut-cli skill edit-video` to get the sub-skill and execute.
+
 ### image
 
 Default action: `create`
@@ -102,7 +117,7 @@ Options:
 Validation rules:
 
 - `--prompt` must be non-empty
-- `--model` allowed: `seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan`
+- `--model` allowed: `seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan|wan-pro`
 - `--aspectRatio` allowed: `1:1|3:4|4:3|16:9|9:16|2:3|3:2|21:9|1:4|4:1|1:8|8:1`
 - unless user specifies aspect ratio, default to `16:9`
 - `--resolution` allowed: `1K|2K|4K`
@@ -127,17 +142,20 @@ Options:
 - `--seed <seed>`
 - `--firstFrame <image>`
 - `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>`
 - `--refs <assets>`
 - `--resolution <resolution>`
 - `--aspectRatio <ratio>`
 - `--withAudio`
+- `--withBGM <withBGM>`
 - `--optimizeCameraMotion`
 - `--output <file>`
 
 Validation rules:
 
 - `--prompt` must be non-empty
-- `--model` allowed: `zerocut3.0|zerocut3.0-pro|zerocut3.0-pro-fast|seedance-1.5-pro|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro|zerocut-avatar-1.0|zerocut-avatar-1.5|zerocut-mv-1.0`
+- `--model` allowed: `zerocut3.0|zerocut3.0-pro|zerocut3.0-pro-fast|zerocut3.0-turbo|seedance-1.5-pro|seedance-2.0|seedance-2.0-fast|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro|zerocut-avatar-1.0|zerocut-avatar-1.5|zerocut-mv-1.0`
 - `--duration` must follow model range:
   - default models: `1-16`
   - `zerocut-avatar-1.0` / `zerocut-avatar-1.5`: `5-240`
@@ -145,6 +163,7 @@ Validation rules:
 - `--aspectRatio` allowed: `9:16|16:9|1:1`
 - unless user specifies aspect ratio, default to `16:9`
 - unless user specifies resolution, default to `720p`
+- `--withBGM` allowed: `true|false`, default to `true`
 
 Long video guidance:
 

package/src/skill/edit-video/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: edit-video
+description: Use this skill when the user wants to edit existing videos, replace visual elements, preserve camera language, or stitch multiple clips. Execute with zerocut-cli commands only.
+homepage: "https://github.com/liubei-ai/zerocut-cli"
+source: "https://github.com/liubei-ai/zerocut-cli"
+requires_binaries:
+  - "zerocut-cli"
+  - "npx"
+---
+
+# Edit Video
+
+## Runtime Requirements
+
+- Use CLI commands only.
+- Do not use MCP tool names in instructions.
+- Ensure CLI is available:
+  - `pnpm dlx zerocut-cli help`
+  - `pnpm add -g zerocut-cli && zerocut-cli help`
+  - `npx zerocut-cli help`
+
+## Required Pre-Check
+
+```bash
+npx zerocut-cli config list
+```
+
+If `apiKey` is missing, stop and request OTT token:
+
+```bash
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+## Video Edit Defaults
+
+- Default model is `seedance-2.0` unless user explicitly specifies another legal video model.
+- Unless user explicitly specifies, keep original visual specs by not forcing `--aspectRatio` and `--resolution`.
+- Keep user-requested camera language and motion intent.
+
+## Legal Video Parameters
+
+Only use legal `video` command options:
+
+- `--prompt <prompt>` required
+- `--duration <seconds>`
+- `--model <model>`
+- `--sourceVideo <video>`
+- `--seed <seed>`
+- `--firstFrame <image>`
+- `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>`
+- `--refs <assets>`
+- `--resolution <resolution>`
+- `--aspectRatio <ratio>`
+- `--withAudio`
+- `--withBGM <withBGM>`
+- `--optimizeCameraMotion`
+- `--output <file>`
+
+## Replace Elements In Existing Video
+
+When user asks to replace objects/subjects in an existing clip, pass source video and references to `video` command:
+
+```bash
+npx zerocut-cli video \
+  --prompt "Replace the perfume gift-box product with the cream from reference image, keep original camera movement." \
+  --model seedance-2.0 \
+  --sourceVideo input.mp4 \
+  --refs product_ref.png \
+  --withAudio \
+  --withBGM true \
+  --output edited.mp4
+```
+
+## Character-Aware Editing
+
+If user provides character photos, pass them with `--persons` so they map to `type=person`:
+
+```bash
+npx zerocut-cli video \
+  --prompt "Keep scene pacing, replace actor with provided character while preserving performance rhythm." \
+  --model seedance-2.0 \
+  --sourceVideo input.mp4 \
+  --persons actor_front.png,actor_side.png \
+  --withAudio \
+  --output edited_person.mp4
+```
+
+## Stitch Multiple Videos
+
+Use ffmpeg command path for deterministic stitching.
+
+Create concat list:
+
+```bash
+printf "file 'clip1.mp4'\nfile 'clip2.mp4'\nfile 'clip3.mp4'\n" > concat.txt
+```
+
+Concatenate:
+
+```bash
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy merged.mp4 --resources concat.txt clip1.mp4 clip2.mp4 clip3.mp4
+```
+
+## Hard Rules
+
+- Never use non-CLI tool calls in this skill.
+- Do not use unsupported video parameters.
+- Keep edits faithful to user instructions and preserve continuity.
+- If a command returns `Not enough credits`, stop immediately and ask user to recharge before continuing.

package/src/skill/one-click-video/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: one-click-video
+description: Use this skill when the user wants to produce a complete short video from a topic with fast CLI-driven workflow: scene planning, storyboard creation, scene video generation, optional background music, and final ffmpeg composition.
+homepage: "https://github.com/liubei-ai/zerocut-cli"
+source: "https://github.com/liubei-ai/zerocut-cli"
+requires_binaries:
+  - "zerocut-cli"
+  - "npx"
+---
+
+# One-Click Video
+
+## Purpose
+
+Create a deliverable final video by orchestrating `zerocut-cli` commands only.
+
+## Runtime Requirements
+
+- Use CLI commands only, never MCP tool names.
+- Ensure `zerocut-cli` is available:
+  - `pnpm dlx zerocut-cli help`
+  - `pnpm add -g zerocut-cli && zerocut-cli help`
+  - `npx zerocut-cli help`
+
+## Required Pre-Check
+
+Run config check first:
+
+```bash
+npx zerocut-cli config list
+```
+
+If `apiKey` is missing, stop and request user OTT token:
+
+```bash
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+## Video Parameter Contract
+
+When generating scene videos, only use legal `video` command parameters:
+
+- `--prompt <prompt>` required
+- `--duration <seconds>`
+- `--model <model>`
+- `--sourceVideo <video>`
+- `--seed <seed>`
+- `--firstFrame <image>`
+- `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>` comma-separated image paths/URLs, mapped to `type=person`
+- `--refs <assets>`
+- `--resolution <resolution>`
+- `--aspectRatio <ratio>`
+- `--withAudio`
+- `--withBGM <withBGM>` `true|false`, default `true`
+- `--optimizeCameraMotion`
+- `--output <file>`
+
+## Output Naming Rules
+
+- If user does not provide output path, generate meaningful names with 3-digit prefix:
+  - `001_storyboard_scene1.png`
+  - `002_scene1.mp4`
+  - `003_scene2.mp4`
+  - `004_bgm.mp3`
+  - `005_final.mp4`
+
+## Workflow
+
+1. Understand topic, goal, duration, platform orientation, and style.
+2. Split into 1-5 scenes with clear narrative progression.
+3. Create one storyboard image for each scene.
+4. Generate one video clip for each scene using only legal video parameters.
+5. Optionally generate one background music track with `music` command.
+6. Compose final video with `ffmpeg` command.
+
+## Scene Storyboard Step
+
+Generate storyboard for each scene:
+
+```bash
+npx zerocut-cli image --prompt "<scene storyboard prompt>" --model banana2 --aspectRatio 16:9 --resolution 1K --output 001_storyboard_scene1.png
+```
+
+## Scene Video Step
+
+Use storyboard as `--storyboard`, optional character images via `--persons`, and optional extra references via `--refs`.
+
+```bash
+npx zerocut-cli video \
+  --prompt "<scene video prompt>" \
+  --model seedance-2.0 \
+  --duration 12 \
+  --resolution 720p \
+  --aspectRatio 16:9 \
+  --storyboard 001_storyboard_scene1.png \
+  --persons actor_front.png,actor_side.png \
+  --refs prop_ref.png,env_ref.png \
+  --withAudio \
+  --withBGM true \
+  --output 002_scene1.mp4
+```
+
+## Background Music Step
+
+Generate one BGM track when needed:
+
+```bash
+npx zerocut-cli music --prompt "<bgm prompt>" --output 004_bgm.mp3
+```
+
+## Final Composition Step (ffmpeg only)
+
+Create concat list:
+
+```bash
+printf "file '002_scene1.mp4'\nfile '003_scene2.mp4'\n" > concat.txt
+```
+
+Concatenate scene clips:
+
+```bash
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy 005_concat.mp4 --resources concat.txt 002_scene1.mp4 003_scene2.mp4
+```
+
+Mix BGM with original video audio:
+
+```bash
+npx zerocut-cli ffmpeg --args -i 005_concat.mp4 -i 004_bgm.mp3 -filter_complex "[1:a]volume=0.2[bgm];[0:a][bgm]amix=inputs=2:duration=first:dropout_transition=2[aout]" -map 0:v -map "[aout]" -c:v copy -c:a aac 005_final.mp4 --resources 005_concat.mp4 004_bgm.mp3
+```
+
+## Hard Rules
+
+- Do not introduce non-CLI tool calls.
+- Do not use parameters outside the legal `video` parameter contract.
+- Keep single scene duration within model limits.
+- Keep visual style consistent across all scenes.
+- Keep role identity consistent when using `--persons`.
+- Do not generate subtitles in this workflow.