@flatkey-ai/cli 0.2.9 → 0.3.3

package/src/cli.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { DEFAULT_BASE_URL } from "./api.js";
+import { nextArtifactPath, persistArtifacts } from "./artifacts.js";
 
 const COMMANDS = new Set([
   "audio",
@@ -20,6 +21,8 @@ const COMMANDS = new Set([
 const GROUP_ACTIONS = new Set(["audio", "auth", "image", "text", "video"]);
 const GLOBAL_OPTIONS = new Set(["api_key", "base_url", "console_url", "dry_run", "help", "json", "output", "out", "verbose"]);
 const REPEATABLE_OPTIONS = new Set(["image", "image_url", "video_url"]);
+const MEDIA_INPUT_OPTIONS = new Set(["file", "image", "image_url", "video_url", "first_frame", "first_frame_url", "last_frame", "last_frame_url"]);
+const MAX_REFERENCE_IMAGES = 5;
 const COMMAND_OPTIONS = {
   "audio generate": new Set(["model", "prompt", "similarity_boost", "stability", "style", "voice_id"]),
   "audio music": new Set(["music_length_ms", "prompt"]),
@@ -29,7 +32,7 @@ const COMMAND_OPTIONS = {
   credits: new Set([]),
   help: new Set(["ai", "command"]),
   image: new Set([]),
-  "image generate": new Set(["model", "n", "prompt", "quality", "size"]),
+  "image generate": new Set(["file", "image", "image_url", "model", "n", "prompt", "quality", "size"]),
   "image upload": new Set(["file"]),
   login: new Set(["console_url", "no_open", "open"]),
   logout: new Set([]),
@@ -40,7 +43,8 @@ const COMMAND_OPTIONS = {
   "text generate": new Set(["model", "prompt"]),
   version: new Set([]),
   video: new Set([]),
-  "video generate": new Set(["aspect", "duration", "first_frame", "first_frame_url", "fps", "generate_audio", "image", "image_url", "last_frame", "last_frame_url", "model", "prompt", "ratio", "resolution", "video_url"]),
+  "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) {
@@ -61,7 +65,7 @@ export function parseArgv(argv) {
     return validateCommandOptions({
       group: "help",
       action: undefined,
-      options: { command: maybeAction, ...parseOptions(rest) },
+      options: { command: maybeAction, ...parseOptions(rest, repeatableOptionsFor("help")) },
     });
   }
 
@@ -81,7 +85,7 @@ export function parseArgv(argv) {
       group,
       action,
       options: {
-        ...parseOptions(optionTokens.filter((token) => token !== "help" && token !== "--help" && token !== "-h")),
+        ...parseOptions(optionTokens.filter((token) => token !== "help" && token !== "--help" && token !== "-h"), repeatableOptionsFor(group, action)),
         help: true,
       },
     });
@@ -90,7 +94,7 @@ export function parseArgv(argv) {
   return validateCommandOptions({
     group,
     action,
-    options: parseOptions(optionTokens),
+    options: parseOptions(optionTokens, repeatableOptionsFor(group, action)),
   });
 }
 
@@ -98,8 +102,9 @@ function isHelpToken(token) {
   return token === "help" || token === "--help" || token === "-h";
 }
 
-function parseOptions(tokens) {
+function parseOptions(tokens, repeatableOptions = REPEATABLE_OPTIONS) {
   const options = {};
+  const mediaInputs = [];
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index];
     if (token === "-o") {
@@ -120,16 +125,39 @@ function parseOptions(tokens) {
       options[name] = true;
       continue;
     }
-    if (REPEATABLE_OPTIONS.has(name)) {
+    if (repeatableOptions.has(name)) {
       options[name] = [...asArray(options[name]), next];
     } else {
       options[name] = next;
     }
+    if (MEDIA_INPUT_OPTIONS.has(name)) {
+      mediaInputs.push({ name, value: next });
+    }
     index += 1;
   }
+  if (mediaInputs.length > 0) {
+    Object.defineProperty(options, "__media_inputs", {
+      value: mediaInputs,
+      enumerable: false,
+      writable: true,
+    });
+  }
   return options;
 }
 
+function repeatableOptionsFor(group, action) {
+  if (group === "image" && action === "generate") {
+    return new Set([...REPEATABLE_OPTIONS, "file"]);
+  }
+  if (group === "video" && action === "generate") {
+    return new Set([...REPEATABLE_OPTIONS, "file"]);
+  }
+  if (group === "video" && action === "copy") {
+    return REPEATABLE_OPTIONS;
+  }
+  return REPEATABLE_OPTIONS;
+}
+
 function asArray(value) {
   if (value === undefined) return [];
   return Array.isArray(value) ? value : [value];
@@ -139,6 +167,7 @@ function validateCommandOptions(command) {
   const key = command.action ? `${command.group} ${command.action}` : command.group;
   const allowed = COMMAND_OPTIONS[key] ?? new Set();
   for (const option of Object.keys(command.options)) {
+    if (option.startsWith("_")) continue;
     if (GLOBAL_OPTIONS.has(option) || allowed.has(option)) continue;
     const flag = `--${option.replaceAll("_", "-")}`;
     const helpCommand = command.action
@@ -224,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}`);
     }
@@ -238,13 +269,17 @@ export async function runCommand(command, deps = {}) {
 }
 
 async function handleLogin(command, deps) {
-  const { ensureDeviceId, readConfig, writeAuthConfig } = await import("./config.js");
+  const { ensureDeviceId, readConfig, resolveOrigins, writeAuthConfig } = await import("./config.js");
   const { DEFAULT_CONSOLE_URL, createDeviceAuthorization, pollDeviceAuthorization } = await import("./api.js");
   const deviceId = await ensureDeviceId({ configDir: deps.configDir });
   const version = await readPackageVersion();
-  const consoleOrigin = firstNonEmpty(command.options.console_url, DEFAULT_CONSOLE_URL);
+  const { consoleOrigin } = await resolveOrigins({
+    consoleUrl: command.options.console_url,
+    env: deps.env ?? process.env,
+    configDir: deps.configDir,
+  });
   const requestOptions = {
-    consoleUrl: consoleOrigin,
+    consoleUrl: consoleOrigin ?? DEFAULT_CONSOLE_URL,
     fetch: deps.fetch,
     verbose: command.options.verbose,
     verboseLog: verboseLogger(deps.stderr, command.options.verbose),
@@ -426,6 +461,10 @@ async function handleImageUpload(command, deps) {
   if (typeof file !== "string" || file.trim() === "") {
     throw new Error("Missing --file value. Run `flatkey image upload --help` to see supported options.");
   }
+  const media = mediaInfoFromPath(file);
+  if (!media || media.kind !== "image") {
+    throw new Error(`Unsupported image file type: ${file}`);
+  }
   const apiKey = await resolveApiKey({
     apiKey: command.options.api_key,
     env: deps.env ?? process.env,
@@ -441,13 +480,13 @@ async function handleImageUpload(command, deps) {
     baseUrl: consoleOrigin ?? DEFAULT_CONSOLE_URL,
     file: await readFile(await expandHomePath(file)),
     filename: basename(file),
-    contentType: imageContentTypeFromPath(file),
+    contentType: media.contentType,
     fetch: deps.fetch,
     verbose: command.options.verbose,
     verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   });
   const data = response?.data ?? response;
-  const signedUrl = extractUploadedImageUrl(response);
+  const signedUrl = extractUploadedMediaUrl(response);
   if (!signedUrl) {
     throw new Error("Image upload failed: missing signed_url.");
   }
@@ -479,9 +518,10 @@ async function handleGenerate(command, deps) {
     planTextRequest,
     planVideoRequest,
     uploadTempMediaImage,
+    uploadTempMediaVideo,
   } = await import("./api.js");
-  const { persistArtifacts } = await import("./artifacts.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({
@@ -509,8 +549,46 @@ async function handleGenerate(command, deps) {
     fetch: deps.fetch,
     verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   };
-  if (command.group === "video" && !command.options.dry_run) {
-    await uploadVideoLocalImages(options, { uploadTempMediaImage });
+  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") {
+    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"
@@ -524,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),
@@ -532,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);
@@ -553,7 +670,7 @@ async function handleGenerate(command, deps) {
     }
     const outDir = command.options.out ?? "flatkey-output";
     const output = command.options.output
-      ?? (command.group === "video" ? join(outDir, "video-01.mp4") : undefined);
+      ?? (command.group === "video" ? await nextArtifactPath({ kind: command.group, outDir }) : undefined);
     const artifacts = await persistArtifacts({
       kind: command.group,
       response: artifactResponse,
@@ -561,64 +678,201 @@ 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 uploadVideoLocalImages(options, deps) {
-  const localImages = asArray(options.image);
-  const firstFrame = options.first_frame;
-  const lastFrame = options.last_frame;
-  if (localImages.length === 0 && !firstFrame && !lastFrame) return;
+async function prepareMediaInputs(command, options, deps) {
+  const mediaInputs = orderedMediaInputs(command, options);
+  if (mediaInputs.length === 0) return;
+  assertMediaReferenceLimit(mediaInputs, command.group, options.model);
 
-  const uploads = [];
-  for (const file of localImages) {
-    uploads.push(await uploadLocalImage(file, options, deps));
+  const resolved = [];
+  for (const input of mediaInputs) {
+    if (input.kind === "local") {
+      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));
+    }
+  }
+  options.__media_inputs = resolved;
+}
+
+function assertMediaReferenceLimit(mediaInputs, commandGroup, 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 ${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 (uploads.length > 0) {
-    options.image_url = [...asArray(options.image_url), ...uploads];
+  if (imageInputs.length > MAX_REFERENCE_IMAGES) {
+    throw new Error(`Too many reference images for flatkey ${commandGroup} generate: maximum ${MAX_REFERENCE_IMAGES}.`);
   }
-  if (firstFrame) {
-    options.first_frame_url = await uploadLocalImage(firstFrame, options, deps);
+}
+
+function isSeedance25Model(model) {
+  return String(model ?? "").toLowerCase().replaceAll(/[-_.]/g, "").includes("seedance25");
+}
+
+function orderedMediaInputs(command, options) {
+  const mediaInputs = Array.isArray(options.__media_inputs) ? options.__media_inputs : [];
+  if (mediaInputs.length > 0 && mediaInputs[0] && Object.prototype.hasOwnProperty.call(mediaInputs[0], "kind")) {
+    return mediaInputs;
   }
-  if (lastFrame) {
-    options.last_frame_url = await uploadLocalImage(lastFrame, options, deps);
+  if (mediaInputs.length > 0) {
+    return mediaInputs.map((entry) => ({
+      name: entry.name,
+      value: entry.value,
+      kind: entry.name.endsWith("_url") ? "url" : "local",
+    }));
   }
+
+  const legacyInputs = [];
+  const pushLocal = (name, value) => {
+    for (const file of asArray(value)) {
+      legacyInputs.push({ name, value: file, kind: "local" });
+    }
+  };
+  const pushUrl = (name, value) => {
+    for (const url of asArray(value)) {
+      legacyInputs.push({ name, value: url, kind: "url" });
+    }
+  };
+
+  pushLocal("file", options.file);
+  pushLocal("image", options.image);
+  pushUrl("image_url", options.image_url);
+  if (command.group === "video") {
+    pushUrl("video_url", options.video_url);
+    pushLocal("first_frame", options.first_frame);
+    pushUrl("first_frame_url", options.first_frame_url);
+    pushLocal("last_frame", options.last_frame);
+    pushUrl("last_frame_url", options.last_frame_url);
+  }
+  return legacyInputs;
 }
 
-async function uploadLocalImage(file, options, deps) {
+async function uploadLocalMedia(file, commandGroup, deps, optionName) {
   const { basename } = await import("node:path");
   const { readFile } = await import("node:fs/promises");
-  const response = await deps.uploadTempMediaImage({
-    apiKey: options.apiKey,
-    baseUrl: options.tempMediaBaseUrl ?? options.baseUrl,
+  const media = mediaInfoFromPath(file);
+  const allowedKinds = allowedMediaKindsForOption(commandGroup, optionName);
+  if (!media || !allowedKinds.has(media.kind)) {
+    throw new Error(`Unsupported --${optionName.replaceAll("_", "-")} file type for flatkey ${commandGroup} generate: ${file}`);
+  }
+  const uploader = media.kind === "video" ? deps.uploadTempMediaVideo : deps.uploadTempMediaImage;
+  const response = await uploader({
+    apiKey: deps.apiKey,
+    baseUrl: deps.tempMediaBaseUrl ?? deps.baseUrl,
     file: await readFile(await expandHomePath(file)),
     filename: basename(file),
-    contentType: imageContentTypeFromPath(file),
-    fetch: options.fetch,
-    verbose: options.verbose,
-    verboseLog: options.verboseLog,
+    contentType: media.contentType,
+    fetch: deps.fetch,
+    verbose: deps.verbose,
+    verboseLog: deps.verboseLog,
   });
-  const url = extractUploadedImageUrl(response);
-  if (!url) throw new Error(`Image upload failed: missing signed_url for ${file}`);
-  return url;
+  const url = extractUploadedMediaUrl(response);
+  if (!url) throw new Error(`Media upload failed: missing signed_url for ${file}`);
+  return {
+    name: optionName,
+    value: url,
+    kind: media.kind,
+    role: mediaRoleFromOption(optionName, media.kind),
+    mime: media.contentType,
+  };
 }
 
-function extractUploadedImageUrl(response) {
+async function confirmRemoteMediaUrl(url, commandGroup, deps, optionName) {
+  const fetchImpl = deps.fetch ?? fetch;
+  const response = await fetchImpl(url, { method: "HEAD" });
+  const media = mediaInfoFromMime(headerValue(response?.headers, "content-type"));
+  const allowedKinds = allowedMediaKindsForOption(commandGroup, optionName);
+  if (!media || !allowedKinds.has(media.kind)) {
+    throw new Error(`Unsupported --${optionName.replaceAll("_", "-")} MIME type for flatkey ${commandGroup} generate: ${headerValue(response?.headers, "content-type") ?? "unknown"}`);
+  }
+  return {
+    name: optionName,
+    value: url,
+    kind: media.kind,
+    role: mediaRoleFromOption(optionName, media.kind),
+    mime: media.contentType,
+  };
+}
+
+function extractUploadedMediaUrl(response) {
   const data = response?.data ?? response;
   return data?.signed_url ?? data?.signedUrl ?? data?.url ?? response?.signed_url ?? response?.signedUrl ?? response?.url;
 }
 
-function imageContentTypeFromPath(file) {
+function mediaInfoFromPath(file) {
   const lower = String(file).toLowerCase();
-  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
-  if (lower.endsWith(".png")) return "image/png";
-  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return { kind: "image", contentType: "image/jpeg" };
+  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;
 }
 
+function mediaInfoFromMime(contentType) {
+  if (typeof contentType !== "string") return undefined;
+  const lower = contentType.toLowerCase();
+  if (lower.startsWith("image/jpeg")) return { kind: "image", contentType: "image/jpeg" };
+  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;
+}
+
+function mediaRoleFromOption(optionName, kind) {
+  if (optionName === "first_frame" || optionName === "first_frame_url") return "first_frame";
+  if (optionName === "last_frame" || optionName === "last_frame_url") return "last_frame";
+  if (kind === "video") return "reference_video";
+  return "reference_image";
+}
+
+function allowedMediaKindsForOption(commandGroup, optionName) {
+  if (commandGroup === "image") return new Set(["image"]);
+  if (optionName === "file") return new Set(["image", "video"]);
+  if (optionName === "video_url") return new Set(["video"]);
+  if (optionName === "first_frame" || optionName === "first_frame_url" || optionName === "last_frame" || optionName === "last_frame_url" || optionName === "image" || optionName === "image_url") {
+    return new Set(["image"]);
+  }
+  return new Set(["image"]);
+}
+
+function headerValue(headers, name) {
+  if (!headers) return undefined;
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? headers.get(name.toLowerCase());
+  }
+  return headers[name] ?? headers[name.toLowerCase()];
+}
+
 async function waitForVideoResult(response, options) {
   if (hasArtifact(response)) return response;
   const taskId = videoTaskId(response);
@@ -715,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");