@flatkey-ai/cli 0.2.9 → 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.2.9",
+  "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;
   }
 }
 
@@ -17,11 +18,19 @@ export async function generateImage(options) {
 }
 
 export async function uploadTempMediaImage(options) {
+  return uploadTempMediaByKind(options, "images");
+}
+
+export async function uploadTempMediaVideo(options) {
+  return uploadTempMediaByKind(options, "videos");
+}
+
+async function uploadTempMediaByKind(options, kind) {
   const form = new FormData();
   form.append("file", new Blob([options.file], cleanObject({
     type: options.contentType,
-  })), options.filename ?? "image");
-  return requestJsonFromPlan(options, planRequest(options, "/v1/temp-media/images", {
+  })), options.filename ?? (kind === "videos" ? "video" : "image"));
+  return requestJsonFromPlan(options, planRequest(options, `/v1/temp-media/${kind}`, {
     method: "POST",
     headers: authHeaders(options.apiKey),
     body: form,
@@ -30,6 +39,13 @@ export async function uploadTempMediaImage(options) {
 
 export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
+  const mediaInputs = orderedMediaInputs(options);
+  assertReferenceLimits(mediaInputs, "image", model);
+  if (mediaInputs.some((entry) => entry.kind === "video")) {
+    throw new Error("Image models only accept image inputs.");
+  }
+  const imageUrls = mediaInputs
+    .map((entry) => entry.url);
   if (model.startsWith("gpt")) {
     const responseFormat = options.response_format ?? options.responseFormat ?? "url";
     const tempUrl = options.temp_url ?? options.tempUrl;
@@ -41,6 +57,7 @@ export function planImageRequest(options) {
       quality: options.quality,
       response_format: responseFormat,
       temp_url: tempUrl ?? true,
+      images: imageUrls.length > 0 ? imageUrls : undefined,
     }));
   }
 
@@ -52,7 +69,12 @@ export function planImageRequest(options) {
       "x-goog-api-key": options.apiKey,
     },
     body: {
-      contents: [{ parts: [{ text: options.prompt }] }],
+      contents: [{
+        parts: [
+          { text: options.prompt },
+          ...imageUrls.map((url) => ({ type: "image_url", image_url: { url } })),
+        ],
+      }],
       temp_url: true,
     },
   });
@@ -68,17 +90,22 @@ export function getVideo(options, taskId) {
 
 export function planVideoRequest(options) {
   const model = options.model ?? "seedance-2.0-pro";
-  const imageUrls = [
-    ...arrayOption(options.image_url),
-    ...arrayOption(options.imageUrl),
-    ...arrayOption(options.first_frame_url),
-    ...arrayOption(options.firstFrameUrl),
-    ...arrayOption(options.last_frame_url),
-    ...arrayOption(options.lastFrameUrl),
-  ];
+  const mediaInputs = orderedMediaInputs(options);
+  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.");
+  }
+  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(
@@ -91,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);
+  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,
     }));
@@ -260,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;
@@ -284,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 {
@@ -392,34 +426,24 @@ function isMiniMaxModel(model) {
   return /^minimax-h3$/i.test(model);
 }
 
-function buildSeedanceContent(options) {
+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) {
     content.push({ type: "text", text: options.prompt });
   }
-  for (const url of arrayOption(options.image_url)) {
-    content.push({ type: "image_url", image_url: { url }, role: "reference_image" });
-  }
-  for (const url of arrayOption(options.imageUrl)) {
-    content.push({ type: "image_url", image_url: { url }, role: "reference_image" });
-  }
-  for (const url of arrayOption(options.first_frame_url)) {
-    content.push({ type: "image_url", image_url: { url }, role: "first_frame" });
-  }
-  for (const url of arrayOption(options.firstFrameUrl)) {
-    content.push({ type: "image_url", image_url: { url }, role: "first_frame" });
-  }
-  for (const url of arrayOption(options.last_frame_url)) {
-    content.push({ type: "image_url", image_url: { url }, role: "last_frame" });
-  }
-  for (const url of arrayOption(options.lastFrameUrl)) {
-    content.push({ type: "image_url", image_url: { url }, role: "last_frame" });
-  }
-  for (const url of arrayOption(options.video_url)) {
-    content.push({ type: "video_url", video_url: { url }, role: "reference_video" });
-  }
-  for (const url of arrayOption(options.videoUrl)) {
-    content.push({ type: "video_url", video_url: { url }, role: "reference_video" });
+  for (const entry of mediaInputs) {
+    if (entry.kind === "video") {
+      content.push({ type: "video_url", video_url: { url: entry.url }, role: entry.role ?? "reference_video" });
+      continue;
+    }
+    content.push({ type: "image_url", image_url: { url: entry.url }, role: entry.role ?? "reference_image" });
   }
   return content;
 }
@@ -435,6 +459,64 @@ function cleanObject(value) {
   );
 }
 
+function assertReferenceLimits(mediaInputs, kind, model) {
+  const imageInputs = mediaInputs.filter((entry) => entry.kind !== "video");
+  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) {
+  const hidden = Array.isArray(options.__media_inputs) ? options.__media_inputs : [];
+  if (hidden.length > 0 && hidden[0] && Object.prototype.hasOwnProperty.call(hidden[0], "url")) {
+    return hidden;
+  }
+  if (hidden.length > 0) {
+    return hidden.map((entry) => ({
+      ...entry,
+      url: entry.url ?? entry.value,
+      kind: entry.kind ?? inferMediaKindFromName(entry.name, entry.value),
+    }));
+  }
+
+  const legacy = [];
+  const push = (name, value, kind = "image", role) => {
+    for (const item of arrayOption(value)) {
+      legacy.push({ name, url: item, kind: kind === "image" ? inferMediaKindFromName(name, item) : kind, role });
+    }
+  };
+  push("file", options.file, "image");
+  push("image", options.image, "image");
+  push("image_url", options.image_url, "image");
+  push("first_frame", options.first_frame, "image", "first_frame");
+  push("first_frame_url", options.first_frame_url, "image", "first_frame");
+  push("last_frame", options.last_frame, "image", "last_frame");
+  push("last_frame_url", options.last_frame_url, "image", "last_frame");
+  push("video_url", options.video_url, "video", "reference_video");
+  return legacy;
+}
+
+function inferMediaKindFromName(name, value) {
+  const lowerName = String(name ?? "").toLowerCase();
+  if (lowerName.includes("video")) 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/artifacts.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join } from "node:path";
 
@@ -32,15 +32,23 @@ export async function persistArtifacts({
   const items = extractItems(response);
   const artifacts = [];
   await mkdir(output ? dirname(output) : outDir, { recursive: true });
+  const startIndex = output ? 0 : await nextArtifactIndex({ kind, outDir });
 
   for (const [index, item] of items.entries()) {
-    const artifact = await persistItem({ kind, item, outDir, output, index, fetchImpl });
+    const artifact = await persistItem({ kind, item, outDir, output, index: index + startIndex, fetchImpl });
     if (artifact) artifacts.push(artifact);
   }
 
   return artifacts;
 }
 
+export async function nextArtifactPath({ kind, outDir = "flatkey-output" }) {
+  const extension = DEFAULT_EXTENSIONS[kind] ?? "bin";
+  const index = await nextArtifactIndex({ kind, outDir });
+  const number = String(index + 1).padStart(2, "0");
+  return join(outDir, `${kind}-${number}.${extension}`);
+}
+
 function expandHomePath(path) {
   if (typeof path !== "string") return path;
   if (path === "~") return homedir();
@@ -136,3 +144,23 @@ function artifactPath({ kind, outDir, output, index, extension }) {
   const number = String(index + 1).padStart(2, "0");
   return join(outDir, `${kind}-${number}.${extension}`);
 }
+
+async function nextArtifactIndex({ kind, outDir }) {
+  const extension = DEFAULT_EXTENSIONS[kind] ?? "bin";
+  const pattern = new RegExp(`^${escapeRegExp(kind)}-(\\d+)\\.${escapeRegExp(extension)}$`);
+  let max = 0;
+  try {
+    for (const entry of await readdir(outDir)) {
+      const match = pattern.exec(entry);
+      if (!match) continue;
+      max = Math.max(max, Number.parseInt(match[1], 10));
+    }
+  } catch {
+    return 0;
+  }
+  return max;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}