@flatkey-ai/cli 0.3.2 → 0.3.3

package/README.md

@@ -140,7 +140,29 @@ flatkey video generate \
   -o launch.mp4
 ```
 
-Video ratios: `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `1:1`.
+### Copy Video
+
+Recreate a local 5-15 second video using a generated Depth Anything V2 video
+reference:
+
+```bash
+flatkey video copy \
+  --source input.mp4 \
+  --frame-ratio 80 \
+  --depth-resolution 480p \
+  -o result.mp4
+```
+
+`video copy` preserves the source duration by default. The source and requested
+duration must be between 5 and 15 seconds. Depth processing uses a platform
+runtime downloaded by the CLI; runtime distribution is configured through
+`FLATKEY_VIDEO_RUNTIME_BASE_URL` until the Flatkey runtime release channel is
+published. The generated depth video is uploaded as the primary motion
+reference. If the selected upstream model cannot fetch video references, the
+CLI explicitly falls back to three depth keyframes and reports that mode in
+JSON output as `depth-keyframes-fallback`.
+
+Video ratios: `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `1:1`, `adaptive`.
 Video resolutions: `480p`, `720p`, `1080p`.
 
 Local reference images are uploaded through Flatkey temporary media first:
@@ -153,6 +175,22 @@ flatkey video generate \
   -o kitten.mp4
 ```
 
+Seedance 2.5 accepts reference images and videos as ordered content inputs:
+
+```bash
+flatkey video generate \
+  --model seedance-2-5-pro \
+  --prompt "保持人物、服装和镜头运动一致" \
+  --image-url https://example.com/character.png \
+  --video-url https://example.com/motion.mp4 \
+  --ratio adaptive \
+  -o result.mp4
+```
+
+For Seedance 2.5, the CLI allows up to 30 reference images and 10 reference
+videos in one request. Local files are uploaded before generation and all
+inputs keep their command-line order. Reference videos can be `.mp4` or `.mov`.
+
 First/last frame:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
   "type": "module",
   "bin": {
@@ -8,9 +8,11 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "scripts"
   ],
   "scripts": {
+    "postinstall": "node scripts/install-video-runtime.js",
     "test": "node --test"
   },
   "engines": {

package/scripts/install-video-runtime.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { ensureVideoRuntime } from "../src/video-runtime.js";
+
+try {
+  await ensureVideoRuntime();
+} catch (error) {
+  const message = error?.message ?? String(error);
+  if (process.env.FLATKEY_VIDEO_RUNTIME_REQUIRED === "1") {
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  } else {
+    process.stderr.write(`Flatkey video runtime not installed during postinstall: ${message}\n`);
+  }
+}

package/src/api.js

@@ -5,10 +5,11 @@ export const DEFAULT_MODELS_BASE_URL = "https://console.flatkey.ai";
 export const DEFAULT_CONSOLE_URL = "https://console.flatkey.ai";
 
 export class FlatkeyError extends Error {
-  constructor(message, { status } = {}) {
+  constructor(message, { status, code } = {}) {
     super(message);
     this.name = "FlatkeyError";
     this.status = status;
+    this.code = code;
   }
 }
 
@@ -39,7 +40,7 @@ async function uploadTempMediaByKind(options, kind) {
 export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
   const mediaInputs = orderedMediaInputs(options);
-  assertReferenceImageLimit(mediaInputs, "image");
+  assertReferenceLimits(mediaInputs, "image", model);
   if (mediaInputs.some((entry) => entry.kind === "video")) {
     throw new Error("Image models only accept image inputs.");
   }
@@ -90,7 +91,7 @@ export function getVideo(options, taskId) {
 export function planVideoRequest(options) {
   const model = options.model ?? "seedance-2.0-pro";
   const mediaInputs = orderedMediaInputs(options);
-  assertReferenceImageLimit(mediaInputs, "video");
+  assertReferenceLimits(mediaInputs, "video", model);
   if (mediaInputs.some((entry) => entry.role === "first_frame" && entry.kind === "video")
     || mediaInputs.some((entry) => entry.role === "last_frame" && entry.kind === "video")) {
     throw new Error("Video first-frame and last-frame inputs must be images.");
@@ -98,9 +99,13 @@ export function planVideoRequest(options) {
   const imageUrls = mediaInputs
     .filter((entry) => entry.kind !== "video")
     .map((entry) => entry.url);
+  const videoUrls = mediaInputs
+    .filter((entry) => entry.kind === "video")
+    .map((entry) => entry.url);
   const ratio = validateOptionalValue(
-    optionValue(options, "ratio", "aspect") ?? (isMiniMaxModel(model) ? "16:9" : undefined),
-    ["16:9", "9:16", "4:3", "3:4", "21:9", "1:1"],
+    optionValue(options, "ratio", "aspect")
+      ?? (isMiniMaxModel(model) ? "16:9" : isSeedance25Model(model) ? "adaptive" : undefined),
+    ["16:9", "9:16", "4:3", "3:4", "21:9", "1:1", "adaptive"],
     "ratio",
   );
   const resolution = validateOptionalValue(
@@ -113,19 +118,24 @@ export function planVideoRequest(options) {
     prompt: options.prompt,
     duration: options.duration === undefined && isMiniMaxModel(model)
       ? 5
-      : parseOptionalInteger(options.duration),
+      : options.duration === undefined && isSeedance25Model(model)
+        ? -1
+      : parseOptionalFloat(options.duration),
     aspect: ratio,
     ratio,
     resolution,
     quality: resolution,
     fps: parseOptionalInteger(options.fps),
     generate_audio: parseOptionalBoolean(options.generate_audio) ?? true,
+    omni_reference_task_type: isSeedance25Model(model) && mediaInputs.some((entry) => entry.kind === "video" || entry.role === "reference_image")
+      ? "auto"
+      : undefined,
     temp_url: true,
     images: !isSeedanceModel(model) && imageUrls.length > 0 ? imageUrls : undefined,
   });
   const seedanceContent = buildSeedanceContent(options, mediaInputs);
   if ((isSeedanceModel(model) || isMiniMaxModel(model)) && seedanceContent.length > 0) {
-    return planJsonPost(options, "/v1/video/generations", cleanObject({
+    return planJsonPost(options, videoGenerationPath(model, videoUrls), cleanObject({
       ...basePayload,
       content: seedanceContent,
     }));
@@ -282,6 +292,7 @@ async function requestJsonFromPlan(options, plan) {
   if (!response.ok || body?.success === false) {
     throw new FlatkeyError(extractErrorMessage(body, response.status), {
       status: response.status,
+      code: body?.code ?? body?.error?.code,
     });
   }
   return body;
@@ -306,6 +317,7 @@ async function requestBinaryArtifactFromPlan(options, plan) {
     logResponseBody(options, body);
     throw new FlatkeyError(extractErrorMessage(body, response.status), {
       status: response.status,
+      code: body?.code ?? body?.error?.code,
     });
   }
   return {
@@ -414,6 +426,13 @@ function isMiniMaxModel(model) {
   return /^minimax-h3$/i.test(model);
 }
 
+function videoGenerationPath(model, videoUrls = []) {
+  // Seedance keeps text, image, and video-reference content on /v1/videos.
+  // The legacy route does not reliably fetch video references upstream.
+  if (isSeedanceModel(model)) return "/v1/videos";
+  return "/v1/video/generations";
+}
+
 function buildSeedanceContent(options, mediaInputs = orderedMediaInputs(options)) {
   const content = [];
   if (options.prompt !== undefined) {
@@ -440,10 +459,21 @@ function cleanObject(value) {
   );
 }
 
-function assertReferenceImageLimit(mediaInputs, kind) {
+function assertReferenceLimits(mediaInputs, kind, model) {
   const imageInputs = mediaInputs.filter((entry) => entry.kind !== "video");
-  if (imageInputs.length <= 5) return;
-  throw new Error(`Too many reference images for flatkey ${kind} generate: maximum 5.`);
+  const videoInputs = mediaInputs.filter((entry) => entry.kind === "video");
+  if (isSeedance25Model(model)) {
+    if (imageInputs.length > 30) {
+      throw new Error(`Too many reference images for flatkey ${kind} generate with Seedance 2.5: maximum 30.`);
+    }
+    if (videoInputs.length > 10) {
+      throw new Error(`Too many reference videos for flatkey ${kind} generate with Seedance 2.5: maximum 10.`);
+    }
+    return;
+  }
+  if (imageInputs.length > 5) {
+    throw new Error(`Too many reference images for flatkey ${kind} generate: maximum 5.`);
+  }
 }
 
 function orderedMediaInputs(options) {
@@ -479,10 +509,14 @@ function orderedMediaInputs(options) {
 function inferMediaKindFromName(name, value) {
   const lowerName = String(name ?? "").toLowerCase();
   if (lowerName.includes("video")) return "video";
-  if (typeof value === "string" && value.toLowerCase().endsWith(".mp4")) return "video";
+  if (typeof value === "string" && /\.(mp4|mov)$/i.test(value)) return "video";
   return "image";
 }
 
+function isSeedance25Model(model) {
+  return String(model ?? "").toLowerCase().replaceAll(/[-_.]/g, "").includes("seedance25");
+}
+
 async function readJson(response) {
   try {
     return await response.json();

package/src/cli.js

@@ -44,6 +44,7 @@ const COMMAND_OPTIONS = {
   version: new Set([]),
   video: new Set([]),
   "video generate": new Set(["aspect", "duration", "file", "first_frame", "first_frame_url", "fps", "generate_audio", "image", "image_url", "last_frame", "last_frame_url", "model", "prompt", "ratio", "resolution", "video_url"]),
+  "video copy": new Set(["aspect", "depth_location", "depth_model", "depth_resolution", "duration", "fps", "frame_ratio", "generate_audio", "keep_depth", "model", "prompt", "ratio", "resolution", "source"]),
 };
 
 export function parseArgv(argv) {
@@ -151,6 +152,9 @@ function repeatableOptionsFor(group, action) {
   if (group === "video" && action === "generate") {
     return new Set([...REPEATABLE_OPTIONS, "file"]);
   }
+  if (group === "video" && action === "copy") {
+    return REPEATABLE_OPTIONS;
+  }
   return REPEATABLE_OPTIONS;
 }
 
@@ -249,7 +253,9 @@ export async function runCommand(command, deps = {}) {
       ? ["generate", "sfx", "music"].includes(command.action)
       : command.group === "image"
         ? ["generate", "upload"].includes(command.action)
-        : command.action === "generate";
+        : command.group === "video"
+          ? ["generate", "copy"].includes(command.action)
+          : command.action === "generate";
     if (!validAction) {
       throw new Error(`Unknown action for ${command.group}: ${command.action}`);
     }
@@ -515,6 +521,7 @@ async function handleGenerate(command, deps) {
     uploadTempMediaVideo,
   } = await import("./api.js");
   const { createAnimation } = await import("./animation.js");
+  const { prepareVideoCopy } = await import("./video-copy.js");
   const apiKey = command.options.dry_run
     ? (command.options.api_key ?? "FLATKEY_API_KEY")
     : await resolveApiKey({
@@ -545,17 +552,43 @@ async function handleGenerate(command, deps) {
   if (Array.isArray(command.options.__media_inputs)) {
     options.__media_inputs = command.options.__media_inputs;
   }
+  let videoCopy;
+  if (command.group === "video" && command.action === "copy") {
+    if (!command.options.source) {
+      throw new Error("Missing --source value. Run `flatkey video copy --help` to see supported options.");
+    }
+    videoCopy = await (deps.prepareVideoCopy ?? prepareVideoCopy)(command.options, deps);
+    options.prompt ??= "Recreate the reference video as faithfully as possible while following the supplied depth motion.";
+    options.duration = videoCopy.duration;
+    options.__media_inputs = [{
+      name: "depth_video",
+      value: videoCopy.depthPath,
+      kind: "local",
+      optionName: "file",
+      role: "reference_video",
+    }];
+    options.__copy_reference_mode = "depth-video";
+  }
   if (command.group === "image" || command.group === "video") {
-    await prepareMediaInputs(command, options, {
-      apiKey,
-      baseUrl: options.baseUrl,
-      tempMediaBaseUrl: tempMediaBaseUrl ?? DEFAULT_CONSOLE_URL,
-      fetch: deps.fetch,
-      verbose: command.options.verbose,
-      verboseLog: verboseLogger(deps.stderr, command.options.verbose),
-      uploadTempMediaImage,
-      uploadTempMediaVideo,
-    });
+    try {
+      await prepareMediaInputs(command, options, {
+        apiKey,
+        baseUrl: options.baseUrl,
+        tempMediaBaseUrl: tempMediaBaseUrl ?? DEFAULT_CONSOLE_URL,
+        fetch: deps.fetch,
+        verbose: command.options.verbose,
+        verboseLog: verboseLogger(deps.stderr, command.options.verbose),
+        uploadTempMediaImage,
+        uploadTempMediaVideo,
+      });
+    } catch (error) {
+      await videoCopy?.cleanup?.();
+      throw error;
+    }
+  }
+  if (command.group === "video" && command.action === "copy"
+    && !options.__media_inputs?.some((entry) => entry.kind === "video")) {
+    throw new Error("Video copy failed to prepare its depth-video reference.");
   }
   if (command.options.dry_run) {
     const request = command.group === "image"
@@ -569,7 +602,14 @@ async function handleGenerate(command, deps) {
               ? planAudioMusicRequest(options)
               : planAudioRequest(options)
           : planTextRequest(options);
-    return { dryRun: true, kind: command.group, request: redactRequest(request) };
+    await videoCopy?.cleanup?.();
+    return {
+      dryRun: true,
+      kind: command.group,
+      request: redactRequest(request),
+      videoCopy: scrubVideoCopy(videoCopy),
+      copyReferenceMode: options.__copy_reference_mode,
+    };
   }
   const animation = createAnimation({
     json: Boolean(command.options.json),
@@ -577,20 +617,52 @@ async function handleGenerate(command, deps) {
   });
   animation.start(command.group);
   try {
-    const response = command.group === "image"
-      ? await generateImage(options)
-      : command.group === "video"
-        ? await generateVideo(options)
-        : command.group === "audio"
-          ? command.action === "sfx"
-            ? await generateAudioSfx(options)
-            : command.action === "music"
-              ? await generateAudioMusic(options)
-              : await generateAudio(options)
-          : await generateText(options);
-    const artifactResponse = command.group === "video"
-      ? await waitForVideoResult(response, { ...options, getVideo, sleep: deps.sleep })
-      : response;
+    let response;
+    try {
+      response = command.group === "image"
+        ? await generateImage(options)
+        : command.group === "video"
+          ? await generateVideo(options)
+          : command.group === "audio"
+            ? command.action === "sfx"
+              ? await generateAudioSfx(options)
+              : command.action === "music"
+                ? await generateAudioMusic(options)
+                : await generateAudio(options)
+            : await generateText(options);
+      response = command.group === "video"
+        ? await waitForVideoResult(response, { ...options, getVideo, sleep: deps.sleep })
+        : response;
+    } catch (error) {
+      if (!videoCopy || options.__copy_reference_mode !== "depth-video" || !isDepthVideoFetchFailure(error)) {
+        throw error;
+      }
+      options.__media_inputs = (videoCopy.referencePaths ?? []).map((value, index) => ({
+        name: `depth_frame_${String(index + 1).padStart(2, "0")}`,
+        value,
+        kind: "local",
+        optionName: "image",
+        role: index === 0
+          ? "first_frame"
+          : index === (videoCopy.referencePaths.length - 1)
+            ? "last_frame"
+            : "reference_image",
+      }));
+      await prepareMediaInputs(command, options, {
+        apiKey,
+        baseUrl: options.baseUrl,
+        tempMediaBaseUrl: tempMediaBaseUrl ?? DEFAULT_CONSOLE_URL,
+        fetch: deps.fetch,
+        verbose: command.options.verbose,
+        verboseLog: verboseLogger(deps.stderr, command.options.verbose),
+        uploadTempMediaImage,
+        uploadTempMediaVideo,
+      });
+      options.__copy_reference_mode = "depth-keyframes-fallback";
+      response = await generateVideo(options);
+      response = await waitForVideoResult(response, { ...options, getVideo, sleep: deps.sleep });
+    }
+    const artifactResponse = response;
     if (command.group === "text") {
       const text = extractText(response);
       const output = await writeTextOutput(text, command.options.output);
@@ -606,21 +678,27 @@ async function handleGenerate(command, deps) {
       output,
       fetch: deps.fetch,
     });
-    return { kind: command.group, artifacts, response: scrubArtifactResponse(artifactResponse) };
+    return {
+      kind: command.group,
+      artifacts,
+      response: scrubArtifactResponse(artifactResponse),
+      ...(videoCopy ? { copyReferenceMode: options.__copy_reference_mode } : {}),
+    };
   } finally {
     animation.stop();
+    await videoCopy?.cleanup?.();
   }
 }
 
 async function prepareMediaInputs(command, options, deps) {
   const mediaInputs = orderedMediaInputs(command, options);
   if (mediaInputs.length === 0) return;
-  assertMediaReferenceLimit(mediaInputs, command.group);
+  assertMediaReferenceLimit(mediaInputs, command.group, options.model);
 
   const resolved = [];
   for (const input of mediaInputs) {
     if (input.kind === "local") {
-      resolved.push(await uploadLocalMedia(input.value, command.group, deps, input.name));
+      resolved.push(await uploadLocalMedia(input.value, command.group, deps, input.optionName ?? input.name));
     } else {
       resolved.push(await confirmRemoteMediaUrl(input.value, command.group, deps, input.name));
     }
@@ -628,10 +706,25 @@ async function prepareMediaInputs(command, options, deps) {
   options.__media_inputs = resolved;
 }
 
-function assertMediaReferenceLimit(mediaInputs, commandGroup) {
+function assertMediaReferenceLimit(mediaInputs, commandGroup, model) {
   const imageInputs = mediaInputs.filter((entry) => entry.kind !== "video");
-  if (imageInputs.length <= MAX_REFERENCE_IMAGES) return;
-  throw new Error(`Too many reference images for flatkey ${commandGroup} generate: maximum ${MAX_REFERENCE_IMAGES}.`);
+  const videoInputs = mediaInputs.filter((entry) => entry.kind === "video");
+  if (isSeedance25Model(model)) {
+    if (imageInputs.length > 30) {
+      throw new Error(`Too many reference images for flatkey ${commandGroup} generate with Seedance 2.5: maximum 30.`);
+    }
+    if (videoInputs.length > 10) {
+      throw new Error(`Too many reference videos for flatkey ${commandGroup} generate with Seedance 2.5: maximum 10.`);
+    }
+    return;
+  }
+  if (imageInputs.length > MAX_REFERENCE_IMAGES) {
+    throw new Error(`Too many reference images for flatkey ${commandGroup} generate: maximum ${MAX_REFERENCE_IMAGES}.`);
+  }
+}
+
+function isSeedance25Model(model) {
+  return String(model ?? "").toLowerCase().replaceAll(/[-_.]/g, "").includes("seedance25");
 }
 
 function orderedMediaInputs(command, options) {
@@ -730,6 +823,12 @@ function mediaInfoFromPath(file) {
   if (lower.endsWith(".png")) return { kind: "image", contentType: "image/png" };
   if (lower.endsWith(".webp")) return { kind: "image", contentType: "image/webp" };
   if (lower.endsWith(".mp4")) return { kind: "video", contentType: "video/mp4" };
+  if (lower.endsWith(".mov")) return { kind: "video", contentType: "video/quicktime" };
+  if (lower.endsWith(".bmp")) return { kind: "image", contentType: "image/bmp" };
+  if (lower.endsWith(".tif") || lower.endsWith(".tiff")) return { kind: "image", contentType: "image/tiff" };
+  if (lower.endsWith(".gif")) return { kind: "image", contentType: "image/gif" };
+  if (lower.endsWith(".heic")) return { kind: "image", contentType: "image/heic" };
+  if (lower.endsWith(".heif")) return { kind: "image", contentType: "image/heif" };
   return undefined;
 }
 
@@ -740,6 +839,12 @@ function mediaInfoFromMime(contentType) {
   if (lower.startsWith("image/png")) return { kind: "image", contentType: "image/png" };
   if (lower.startsWith("image/webp")) return { kind: "image", contentType: "image/webp" };
   if (lower.startsWith("video/mp4")) return { kind: "video", contentType: "video/mp4" };
+  if (lower.startsWith("video/quicktime")) return { kind: "video", contentType: "video/quicktime" };
+  if (lower.startsWith("image/bmp")) return { kind: "image", contentType: "image/bmp" };
+  if (lower.startsWith("image/tiff")) return { kind: "image", contentType: "image/tiff" };
+  if (lower.startsWith("image/gif")) return { kind: "image", contentType: "image/gif" };
+  if (lower.startsWith("image/heic")) return { kind: "image", contentType: "image/heic" };
+  if (lower.startsWith("image/heif")) return { kind: "image", contentType: "image/heif" };
   return undefined;
 }
 
@@ -864,6 +969,29 @@ function scrubArtifactResponse(value) {
   );
 }
 
+function scrubVideoCopy(value) {
+  if (!value) return undefined;
+  return {
+    source: value.source,
+    depthPath: value.depthPath,
+    referencePaths: value.referencePaths,
+    duration: value.duration,
+    sourceInfo: value.sourceInfo,
+    helper: value.helper,
+  };
+}
+
+function isDepthVideoFetchFailure(error) {
+  const code = String(error?.code ?? "").toLowerCase();
+  const message = String(error?.message ?? error).toLowerCase();
+  return code.includes("fail_to_fetch")
+    || code.includes("video_fetch")
+    || message.includes("fail_to_fetch")
+    || message.includes("failed to fetch")
+    || message.includes("unable to fetch")
+    || message.includes("video reference");
+}
+
 async function handleVoices(command, deps) {
   const { resolveApiKey, resolveOrigins } = await import("./config.js");
   const { getVoices } = await import("./api.js");

package/src/help.js

@@ -16,6 +16,7 @@ JSON mode:
 Commands:
 - flatkey image generate --prompt "<prompt>" --json [--model <model>] [--file <path>] [--image-url <url>] [--output image.png]
 - flatkey video generate --prompt "<prompt>" --json [--model seedance2] [--file <path>] [--image-url <url>] [--video-url <url>] [--ratio 16:9] [--resolution 720p] [--output video.mp4]
+- flatkey video copy --source input.mp4 --json [--model seedance2] [--frame-ratio 80] [--depth-resolution 480p] [--output video.mp4]
 - flatkey audio generate --prompt "<text>" --json [--voice-id <voice_id>] [--model eleven_multilingual_v2] [--output speech.mp3]
 - flatkey audio sfx --prompt "<sound>" --json [--duration <seconds>] [--output sfx.mp3]
 - flatkey audio music --prompt "<music prompt>" --json [--music-length-ms <ms>] [--output music.mp3]
@@ -54,6 +55,7 @@ Commands:
   image generate --prompt <txt>  Generate image
   image upload --file <path>     Upload local image and return a temporary URL
   video generate --prompt <txt>  Generate video
+  video copy --source <mp4>       Recreate a 5-15s video from Depth Anything V2 motion
   audio generate --prompt <txt>  Generate speech with ElevenLabs voices
   audio sfx --prompt <txt>       Generate sound effects
   audio music --prompt <txt>     Generate music
@@ -79,7 +81,7 @@ Environment:
   --console-url <url>            Override Flatkey console URL for login
 
 Video options:
-  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, or adaptive
   --resolution <value>            480p, 720p, or 1080p
 `;
 }
@@ -216,22 +218,34 @@ Aliases:
 
 Options:
   --json                         Print machine-readable JSON`,
-  video: `Usage: flatkey video generate --prompt <txt> [options]
+  video: `Usage: flatkey video <command> [options]
+
+Commands:
+  generate --prompt <txt>        Generate video
+  copy --source <mp4>            Recreate a 5-15s video from local depth motion
 
 Options:
   --model <model>                Model id, default seedance-2.0-pro
   --duration <seconds>            Video duration
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, or adaptive
+  --resolution <value>            480p, 720p, or 1080p
+  --generate-audio <true|false>   Generate audio, default true
+  --output, -o <file>             Write video file
+  --json                         Print machine-readable JSON`,
+  "video copy": `Usage: flatkey video copy --source <mp4> [options]
+
+Options:
+  --source <mp4>                  Local source video, must be 5-15 seconds
+  --frame-ratio <20..100>         Percent of frames kept for depth, default 100
+  --depth-resolution <value>      original, 480p, or 320p; default 480p
+  --depth-location <dir>          Directory for temporary depth video files
+  --keep-depth                    Keep generated depth video and reference frames
+  --model <model>                Model id, default seedance-2.0-pro
+  --prompt <txt>                 Prompt override for copy generation
+  --duration <seconds>            Must match source duration, 5-15 seconds
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
   --resolution <value>            480p, 720p, or 1080p
   --generate-audio <true|false>   Generate audio, default true
-  --image <file>                  Upload local reference image, repeatable
-  --image-url <url>               Add reference image URL, repeatable
-  --file <path>                   Local image or video input, repeatable
-  --first-frame <file>            Upload local first frame image
-  --video-url <url>               Add reference video URL, repeatable
-  --first-frame-url <url>         Add first frame image URL
-  --last-frame <file>             Upload local last frame image
-  --last-frame-url <url>          Add last frame image URL
   --fps <fps>                    Frames per second
   --output, -o <file>             Write video file
   --json                         Print machine-readable JSON`,
@@ -247,7 +261,7 @@ Options:
   --image-url <url>               Add reference image URL, repeatable
   --file <path>                   Local image or video input, repeatable
   --first-frame <file>            Upload local first frame image
-  --video-url <url>               Add reference video URL, repeatable
+  --video-url <url>               Add reference video URL, repeatable; Seedance 2.5 supports up to 10
   --first-frame-url <url>         Add first frame image URL
   --last-frame <file>             Upload local last frame image
   --last-frame-url <url>          Add last frame image URL

package/src/video-copy.js

@@ -0,0 +1,251 @@
+import { access, mkdir, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+export const MIN_COPY_DURATION_SECONDS = 5;
+export const MAX_COPY_DURATION_SECONDS = 15;
+export const DEFAULT_FRAME_RATIO = 100;
+export const DEFAULT_DEPTH_RESOLUTION = "480p";
+
+export async function prepareVideoCopy(options, deps = {}) {
+  const source = await expandHomePath(options.source);
+  const sourceInfo = await inspectVideo(source, deps);
+  const duration = sourceInfo.duration;
+  validateCopyDuration(duration, "source video");
+
+  const requestedDuration = options.duration === undefined
+    ? duration
+    : parseDuration(options.duration, "--duration");
+  validateCopyDuration(requestedDuration, "--duration");
+  if (Math.abs(requestedDuration - duration) > 0.01) {
+    throw new Error(
+      `--duration must match the source video duration (${formatSeconds(duration)}s); time stretching is not supported by video copy.`,
+    );
+  }
+
+  const depthRoot = await resolveDepthLocation(options.depth_location, deps);
+  const workDir = join(depthRoot, `copy-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(workDir, { recursive: true });
+  const depthPath = join(workDir, "depth.mp4");
+  let helperResult;
+  try {
+    helperResult = await runDepthHelper({
+      source,
+      output: depthPath,
+      frameRatio: parseFrameRatio(options.frame_ratio),
+      resolution: parseDepthResolution(options.depth_resolution),
+      model: options.depth_model,
+      workDir,
+    }, deps);
+  } catch (error) {
+    if (!options.keep_depth) await rm(workDir, { recursive: true, force: true });
+    throw error;
+  }
+  let referencePaths;
+  try {
+    referencePaths = await (deps.extractReferenceFrames ?? extractReferenceFrames)({
+      source: helperResult.output ?? depthPath,
+      outputDir: workDir,
+      duration,
+      ffmpegPath: deps.ffmpegPath,
+      env: deps.env,
+    }, deps);
+  } catch (error) {
+    if (!options.keep_depth) await rm(workDir, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    source,
+    depthPath: helperResult.output ?? depthPath,
+    referencePaths,
+    workDir,
+    duration: requestedDuration,
+    sourceInfo,
+    helper: helperResult,
+    cleanup: async () => {
+      if (!options.keep_depth) {
+        await rm(workDir, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+export function validateCopyDuration(value, label = "duration") {
+  const duration = parseDuration(value, label);
+  if (duration < MIN_COPY_DURATION_SECONDS || duration > MAX_COPY_DURATION_SECONDS) {
+    throw new Error(
+      `${label} must be between ${MIN_COPY_DURATION_SECONDS} and ${MAX_COPY_DURATION_SECONDS} seconds; received ${formatSeconds(duration)}s.`,
+    );
+  }
+  return duration;
+}
+
+export function parseDuration(value, label = "duration") {
+  const duration = Number(value);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`${label} must be a positive number of seconds.`);
+  }
+  return duration;
+}
+
+export function parseFrameRatio(value = DEFAULT_FRAME_RATIO) {
+  const ratio = Number(value);
+  if (!Number.isInteger(ratio) || ratio < 20 || ratio > 100) {
+    throw new Error("--frame-ratio must be an integer between 20 and 100.");
+  }
+  return ratio;
+}
+
+export function parseDepthResolution(value = DEFAULT_DEPTH_RESOLUTION) {
+  const normalized = String(value).toLowerCase();
+  if (normalized === "original" || normalized === "480" || normalized === "480p") return normalized === "original" ? "original" : "480p";
+  if (normalized === "320" || normalized === "320p") return "320p";
+  throw new Error("--depth-resolution must be original, 480p, or 320p.");
+}
+
+export async function resolveDepthLocation(value, deps = {}) {
+  const candidates = [
+    value,
+    deps.tmpdir,
+    tmpdir(),
+    join(homedir(), ".tmp"),
+    join(process.cwd(), ".flatkey-tmp"),
+  ].filter(Boolean);
+
+  let lastError;
+  for (const candidate of candidates) {
+    const expanded = await expandHomePath(candidate);
+    try {
+      await mkdir(expanded, { recursive: true });
+      await access(expanded);
+      return join(expanded, "flatkey-video-copy");
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new Error(`Unable to create a writable depth-video directory${lastError ? `: ${lastError.message}` : "."}`);
+}
+
+export async function inspectVideo(source, deps = {}) {
+  const ffprobe = deps.ffprobePath ?? "ffprobe";
+  const result = await runProcess(ffprobe, [
+    "-v", "error",
+    "-show_entries", "format=duration:stream=width,height,avg_frame_rate",
+    "-of", "json",
+    source,
+  ], deps);
+  let metadata;
+  try {
+    metadata = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`ffprobe returned invalid metadata for ${source}.`);
+  }
+  const duration = Number(metadata?.format?.duration);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`Unable to read source video duration: ${source}`);
+  }
+  return {
+    duration,
+    width: Number(metadata?.streams?.[0]?.width) || undefined,
+    height: Number(metadata?.streams?.[0]?.height) || undefined,
+    frameRate: metadata?.streams?.[0]?.avg_frame_rate,
+  };
+}
+
+export async function runDepthHelper(options, deps = {}) {
+  let helper = deps.depthHelperPath ?? deps.env?.FLATKEY_DEPTH_HELPER ?? process.env.FLATKEY_DEPTH_HELPER;
+  if (!helper) {
+    const { ensureVideoRuntime } = await import("./video-runtime.js");
+    helper = (await ensureVideoRuntime({
+      env: deps.env,
+      fetch: deps.fetch,
+      platform: deps.platform,
+      arch: deps.arch,
+    })).helperPath;
+  }
+
+  const args = [
+    "--source", options.source,
+    "--output", options.output,
+    "--frame-ratio", String(options.frameRatio),
+    "--resolution", options.resolution,
+    "--work-dir", options.workDir,
+  ];
+  if (options.model) args.push("--model", options.model);
+  const result = await runProcess(helper, args, deps);
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error("The Flatkey Rust depth helper returned invalid JSON.");
+  }
+}
+
+export async function extractReferenceFrames(options, deps = {}) {
+  const ffmpeg = options.ffmpegPath
+    ?? deps.env?.FFMPEG_PATH
+    ?? process.env.FFMPEG_PATH
+    ?? "ffmpeg";
+  const duration = Number(options.duration);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error("Cannot extract depth reference frames without a valid duration.");
+  }
+
+  await mkdir(options.outputDir, { recursive: true });
+  const timestamps = [
+    0,
+    duration / 2,
+    Math.max(0, duration - 1 / 30),
+  ];
+  const paths = [];
+  for (let index = 0; index < timestamps.length; index += 1) {
+    const output = join(options.outputDir, `depth-frame-${String(index + 1).padStart(2, "0")}.png`);
+    await runProcess(ffmpeg, [
+      "-v", "error",
+      "-y",
+      "-ss", timestamps[index].toFixed(6),
+      "-i", options.source,
+      "-frames:v", "1",
+      output,
+    ], deps);
+    paths.push(output);
+  }
+  return paths;
+}
+
+export function runProcess(command, args, deps = {}) {
+  if (deps.runProcess) return deps.runProcess(command, args);
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: deps.cwd,
+      env: deps.env ?? process.env,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once("error", (error) => {
+      reject(new Error(`Failed to start ${command}: ${error.message}`));
+    });
+    child.once("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr, code });
+        return;
+      }
+      reject(new Error(`${command} failed with exit code ${code}${stderr.trim() ? `: ${stderr.trim()}` : "."}`));
+    });
+  });
+}
+
+async function expandHomePath(value) {
+  if (typeof value !== "string") return value;
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+function formatSeconds(value) {
+  return Number(value).toFixed(3).replace(/\.?0+$/, "");
+}

package/src/video-runtime.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const VIDEO_RUNTIME_VERSION = "0.1.0";
+
+export function runtimePlatform(platform = process.platform, arch = process.arch) {
+  const supported = {
+    darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+    linux: { arm64: "linux-arm64", x64: "linux-x64" },
+    win32: { arm64: "win32-arm64", x64: "win32-x64" },
+  };
+  const target = supported[platform]?.[arch];
+  if (!target) throw new Error(`Unsupported Flatkey video runtime platform: ${platform}-${arch}`);
+  return target;
+}
+
+export async function runtimeDirectory({ platform = process.platform, arch = process.arch, env = process.env } = {}) {
+  const target = runtimePlatform(platform, arch);
+  const base = env.FLATKEY_RUNTIME_HOME
+    ?? (platform === "win32"
+      ? join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "flatkey")
+      : platform === "darwin"
+        ? join(homedir(), "Library", "Caches", "flatkey")
+        : join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "flatkey"));
+  return join(base, "runtime", VIDEO_RUNTIME_VERSION, target);
+}
+
+export async function ensureVideoRuntime(options = {}) {
+  const directory = await runtimeDirectory(options);
+  const helperName = options.platform === "win32" || (options.platform ?? process.platform) === "win32"
+    ? "flatkey-depth.exe"
+    : "flatkey-depth";
+  const helperPath = join(directory, helperName);
+  try {
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: false };
+  } catch {
+    // Continue to download below.
+  }
+
+  const baseUrl = options.baseUrl
+    ?? options.env?.FLATKEY_VIDEO_RUNTIME_BASE_URL
+    ?? process.env.FLATKEY_VIDEO_RUNTIME_BASE_URL;
+  if (!baseUrl) {
+    throw new Error(
+      `Flatkey video runtime is missing at ${helperPath}. Set FLATKEY_VIDEO_RUNTIME_BASE_URL to enable automatic download.`,
+    );
+  }
+  const target = runtimePlatform(options.platform, options.arch);
+  const fetchImpl = options.fetch ?? fetch;
+  const manifestUrl = `${baseUrl.replace(/\/$/, "")}/${VIDEO_RUNTIME_VERSION}/${target}/manifest.json`;
+  const manifestResponse = await fetchImpl(manifestUrl);
+  if (!manifestResponse.ok) throw new Error(`Failed to download Flatkey video runtime manifest: HTTP ${manifestResponse.status}`);
+  const manifest = await manifestResponse.json();
+  const archiveUrl = manifest.archive_url ?? manifest.url;
+  if (Array.isArray(manifest.files)) {
+    await mkdir(directory, { recursive: true });
+    for (const file of manifest.files) {
+      await downloadRuntimeFile(file, directory, fetchImpl);
+    }
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: true };
+  }
+
+  const sha256 = manifest.sha256;
+  if (!archiveUrl || !sha256) throw new Error("Flatkey video runtime manifest is missing files or archive_url/sha256.");
+
+  const archivePath = join(tmpdir(), `flatkey-video-runtime-${Date.now()}.archive`);
+  try {
+    const response = await fetchImpl(archiveUrl);
+    if (!response.ok) throw new Error(`Failed to download Flatkey video runtime: HTTP ${response.status}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const actualHash = createHash("sha256").update(bytes).digest("hex");
+    if (actualHash !== sha256.toLowerCase()) throw new Error("Flatkey video runtime checksum verification failed.");
+    await mkdir(directory, { recursive: true });
+    await writeFile(archivePath, bytes);
+    await extractArchive(archivePath, directory, options);
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: true };
+  } finally {
+    await rm(archivePath, { force: true });
+  }
+}
+
+async function downloadRuntimeFile(file, directory, fetchImpl) {
+  if (!file?.path || !file?.url || !file?.sha256) {
+    throw new Error("Flatkey video runtime manifest contains an invalid file entry.");
+  }
+  if (file.path.includes("..") || file.path.startsWith("/") || /^[a-z]:/i.test(file.path)) {
+    throw new Error(`Flatkey video runtime manifest contains an unsafe path: ${file.path}`);
+  }
+  const response = await fetchImpl(file.url);
+  if (!response.ok) throw new Error(`Failed to download Flatkey video runtime file ${file.path}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const actualHash = createHash("sha256").update(bytes).digest("hex");
+  if (actualHash !== file.sha256.toLowerCase()) {
+    throw new Error(`Flatkey video runtime checksum verification failed for ${file.path}.`);
+  }
+  const destination = join(directory, file.path);
+  await mkdir(join(destination, ".."), { recursive: true });
+  await writeFile(destination, bytes);
+  if (file.executable || file.mode === "755") {
+    await chmod(destination, 0o755);
+  }
+}
+
+async function extractArchive(archivePath, directory, options) {
+  if (options.extractArchive) {
+    await options.extractArchive(archivePath, directory);
+    return;
+  }
+  throw new Error("Flatkey video runtime archive extraction is not configured for this build.");
+}
+
+export async function sha256File(path) {
+  return createHash("sha256").update(await readFile(path)).digest("hex");
+}