@flatkey-ai/cli 0.2.9 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.2.9",
+  "version": "0.3.2",
   "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -17,11 +17,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 +38,13 @@ export async function uploadTempMediaImage(options) {
 
 export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
+  const mediaInputs = orderedMediaInputs(options);
+  assertReferenceImageLimit(mediaInputs, "image");
+  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 +56,7 @@ export function planImageRequest(options) {
       quality: options.quality,
       response_format: responseFormat,
       temp_url: tempUrl ?? true,
+      images: imageUrls.length > 0 ? imageUrls : undefined,
     }));
   }
 
@@ -52,7 +68,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,14 +89,15 @@ 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);
+  assertReferenceImageLimit(mediaInputs, "video");
+  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 ratio = validateOptionalValue(
     optionValue(options, "ratio", "aspect") ?? (isMiniMaxModel(model) ? "16:9" : undefined),
     ["16:9", "9:16", "4:3", "3:4", "21:9", "1:1"],
@@ -101,7 +123,7 @@ export function planVideoRequest(options) {
     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({
       ...basePayload,
@@ -392,34 +414,17 @@ function isMiniMaxModel(model) {
   return /^minimax-h3$/i.test(model);
 }
 
-function buildSeedanceContent(options) {
+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 +440,49 @@ function cleanObject(value) {
   );
 }
 
+function assertReferenceImageLimit(mediaInputs, kind) {
+  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.`);
+}
+
+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" && value.toLowerCase().endsWith(".mp4")) return "video";
+  return "image";
+}
+
 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, "\\$&");
+}

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,7 @@ 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"]),
 };
 
 export function parseArgv(argv) {
@@ -61,7 +64,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 +84,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 +93,7 @@ export function parseArgv(argv) {
   return validateCommandOptions({
     group,
     action,
-    options: parseOptions(optionTokens),
+    options: parseOptions(optionTokens, repeatableOptionsFor(group, action)),
   });
 }
 
@@ -98,8 +101,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 +124,36 @@ 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"]);
+  }
+  return REPEATABLE_OPTIONS;
+}
+
 function asArray(value) {
   if (value === undefined) return [];
   return Array.isArray(value) ? value : [value];
@@ -139,6 +163,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
@@ -238,13 +263,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 +455,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 +474,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,8 +512,8 @@ 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 apiKey = command.options.dry_run
     ? (command.options.api_key ?? "FLATKEY_API_KEY")
@@ -509,8 +542,20 @@ 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;
+  }
+  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,
+    });
   }
   if (command.options.dry_run) {
     const request = command.group === "image"
@@ -553,7 +598,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,
@@ -567,58 +612,162 @@ async function handleGenerate(command, deps) {
   }
 }
 
-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);
 
-  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.name));
+    } else {
+      resolved.push(await confirmRemoteMediaUrl(input.value, command.group, deps, input.name));
+    }
   }
-  if (uploads.length > 0) {
-    options.image_url = [...asArray(options.image_url), ...uploads];
+  options.__media_inputs = resolved;
+}
+
+function assertMediaReferenceLimit(mediaInputs, commandGroup) {
+  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}.`);
+}
+
+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 (firstFrame) {
-    options.first_frame_url = await uploadLocalImage(firstFrame, options, deps);
+  if (mediaInputs.length > 0) {
+    return mediaInputs.map((entry) => ({
+      name: entry.name,
+      value: entry.value,
+      kind: entry.name.endsWith("_url") ? "url" : "local",
+    }));
   }
-  if (lastFrame) {
-    options.last_frame_url = await uploadLocalImage(lastFrame, options, deps);
+
+  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,
+  };
+}
+
+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 extractUploadedImageUrl(response) {
+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" };
+  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" };
   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);

package/src/help.js

@@ -14,8 +14,8 @@ JSON mode:
 - ASCII animation and human logs are disabled.
 
 Commands:
-- flatkey image generate --prompt "<prompt>" --json [--model <model>] [--output image.png]
-- flatkey video generate --prompt "<prompt>" --json [--model seedance2] [--ratio 16:9] [--resolution 720p] [--output video.mp4]
+- 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 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]
@@ -66,6 +66,9 @@ Commands:
 
 Global options:
   --json                         Print machine-readable JSON
+  --file <path>                   Attach local media input
+  --image-url <url>               Add remote image input, repeatable
+  --video-url <url>               Add remote video input, repeatable
   --output, -o <file>             Write generated output to a local file
   --verbose                      Print request/response logs to stderr
   --base-url <url>               Override Flatkey router URL
@@ -163,6 +166,8 @@ Options:
   --size <size>                  Image size for OpenAI-style image models
   --quality <quality>             Image quality for supported models
   --n <count>                    Number of images for supported models
+  --file <path>                  Local image input, repeatable
+  --image-url <url>               Remote image input, repeatable
   --output, -o <file>             Write image file
   --json                         Print machine-readable JSON`,
   models: `Usage: flatkey models [options]
@@ -221,6 +226,7 @@ Options:
   --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
@@ -239,6 +245,7 @@ Options:
   --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