@flatkey-ai/cli 0.1.17 → 0.1.19

package/package.json

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

package/src/api.js

@@ -14,6 +14,16 @@ export async function generateImage(options) {
   return requestJsonFromPlan(options, planImageRequest(options));
 }
 
+export async function uploadTempMediaImage(options) {
+  const form = new FormData();
+  form.append("file", new Blob([options.file]), options.filename ?? "image");
+  return requestJsonFromPlan(options, planRequest(options, "/v1/temp-media/images", {
+    method: "POST",
+    headers: authHeaders(options.apiKey),
+    body: form,
+  }));
+}
+
 export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
   if (model.startsWith("gpt")) {
@@ -43,6 +53,10 @@ export function generateVideo(options) {
   return requestJsonFromPlan(options, planVideoRequest(options));
 }
 
+export function getVideo(options, taskId) {
+  return requestJsonFromPlan(options, planVideoStatusRequest(options, taskId));
+}
+
 export function planVideoRequest(options) {
   const model = options.model ?? "seedance-2.0-pro";
   const imageUrls = [
@@ -84,6 +98,10 @@ export function planVideoRequest(options) {
   return planJsonPost(options, "/v1/video/generations", basePayload);
 }
 
+export function planVideoStatusRequest(options, taskId) {
+  return planRequest(options, `/v1/videos/${encodeURIComponent(taskId)}`);
+}
+
 export function generateAudio(options) {
   return requestBinaryArtifactFromPlan(options, planAudioRequest(options));
 }
@@ -215,7 +233,11 @@ async function requestJsonFromPlan(options, plan) {
   const response = await fetchImpl(plan.url, {
     method: plan.method,
     headers: plan.headers,
-    body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
+    body: plan.body === undefined
+      ? undefined
+      : isFormData(plan.body)
+        ? plan.body
+        : JSON.stringify(plan.body),
   });
   const body = await readJson(response);
   if (!response.ok) {
@@ -226,6 +248,10 @@ async function requestJsonFromPlan(options, plan) {
   return body;
 }
 
+function isFormData(value) {
+  return typeof FormData !== "undefined" && value instanceof FormData;
+}
+
 async function requestBinaryArtifactFromPlan(options, plan) {
   const fetchImpl = options.fetch ?? fetch;
   const response = await fetchImpl(plan.url, {

package/src/artifacts.js

@@ -47,7 +47,7 @@ function expandHomePath(path) {
 }
 
 async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
-  const dataUrl = getString(item, ["url", "data_url", "dataUrl"]);
+  const dataUrl = getString(item, ["url", "video_url", "data_url", "dataUrl"]);
   if (dataUrl?.startsWith("data:")) {
     const parsed = parseDataUrl(dataUrl);
     const path = artifactPath({ kind, outDir, output, index, extension: parsed.extension });
@@ -90,15 +90,20 @@ async function downloadArtifact({ url, path, fetchImpl }) {
 function extractItems(response) {
   if (Array.isArray(response?.data)) return response.data;
   if (Array.isArray(response?.artifacts)) return response.artifacts;
+  if (Array.isArray(response?.content)) return response.content;
   if (Array.isArray(response?.candidates)) {
     return response.candidates.flatMap((candidate) => candidate.content?.parts ?? []);
   }
+  if (typeof response?.metadata?.url === "string") return [{ url: response.metadata.url }];
+  if (typeof response?.url === "string") return [response];
+  if (typeof response?.video_url?.url === "string") return [{ url: response.video_url.url }];
   return [];
 }
 
 function getString(item, keys) {
   for (const key of keys) {
     if (typeof item?.[key] === "string") return item[key];
+    if (typeof item?.[key]?.url === "string") return item[key].url;
     if (typeof item?.inlineData?.[key] === "string") return item.inlineData[key];
     if (typeof item?.inline_data?.[key] === "string") return item.inline_data[key];
   }

package/src/cli.js

@@ -16,7 +16,7 @@ const COMMANDS = new Set([
 
 const GROUP_ACTIONS = new Set(["audio", "auth", "image", "text", "video"]);
 const GLOBAL_OPTIONS = new Set(["api_key", "base_url", "dry_run", "help", "json", "output", "out"]);
-const REPEATABLE_OPTIONS = new Set(["image_url", "video_url"]);
+const REPEATABLE_OPTIONS = new Set(["image", "image_url", "video_url"]);
 const COMMAND_OPTIONS = {
   "audio generate": new Set(["model", "prompt", "similarity_boost", "stability", "style", "voice_id"]),
   "audio music": new Set(["music_length_ms", "prompt"]),
@@ -27,6 +27,7 @@ const COMMAND_OPTIONS = {
   help: new Set(["ai", "command"]),
   image: new Set([]),
   "image generate": new Set(["model", "n", "prompt", "quality", "size"]),
+  "image upload": new Set(["file"]),
   login: new Set(["console_url", "no_open", "open"]),
   logout: new Set([]),
   models: new Set(["type"]),
@@ -36,7 +37,7 @@ const COMMAND_OPTIONS = {
   "text generate": new Set(["model", "prompt"]),
   version: new Set([]),
   video: new Set([]),
-  "video generate": new Set(["aspect", "duration", "first_frame_url", "fps", "image_url", "last_frame_url", "model", "prompt", "ratio", "resolution", "video_url"]),
+  "video generate": new Set(["aspect", "duration", "first_frame", "first_frame_url", "fps", "image", "image_url", "last_frame", "last_frame_url", "model", "prompt", "ratio", "resolution", "video_url"]),
 };
 
 export function parseArgv(argv) {
@@ -214,10 +215,15 @@ export async function runCommand(command, deps = {}) {
     }
     const validAction = command.group === "audio"
       ? ["generate", "sfx", "music"].includes(command.action)
-      : command.action === "generate";
+      : command.group === "image"
+        ? ["generate", "upload"].includes(command.action)
+        : command.action === "generate";
     if (!validAction) {
       throw new Error(`Unknown action for ${command.group}: ${command.action}`);
     }
+    if (command.group === "image" && command.action === "upload") {
+      return handleImageUpload(command, deps);
+    }
     return handleGenerate(command, { ...deps, stdout, stderr });
   }
 
@@ -394,6 +400,46 @@ async function handleAuthStatus(command, deps) {
   return command.options.json ? status : formatAuthStatus(status);
 }
 
+async function handleImageUpload(command, deps) {
+  const { basename } = await import("node:path");
+  const { readFile } = await import("node:fs/promises");
+  const { resolveApiKey, resolveOrigins } = await import("./config.js");
+  const { uploadTempMediaImage } = await import("./api.js");
+  const file = command.options.file;
+  if (typeof file !== "string" || file.trim() === "") {
+    throw new Error("Missing --file value. Run `flatkey image upload --help` to see supported options.");
+  }
+  const apiKey = await resolveApiKey({
+    apiKey: command.options.api_key,
+    env: deps.env ?? process.env,
+    configDir: deps.configDir,
+  });
+  const { routerOrigin } = await resolveOrigins({
+    baseUrl: command.options.base_url,
+    env: deps.env ?? process.env,
+    configDir: deps.configDir,
+  });
+  const response = await uploadTempMediaImage({
+    apiKey,
+    baseUrl: routerOrigin,
+    file: await readFile(await expandHomePath(file)),
+    filename: basename(file),
+    fetch: deps.fetch,
+  });
+  const data = response?.data ?? response;
+  if (!data?.signed_url) {
+    throw new Error("Image upload failed: missing signed_url.");
+  }
+  return {
+    kind: "upload",
+    url: data?.signed_url,
+    objectKey: data?.object_key,
+    expiresAt: data?.expires_at,
+    expiresIn: data?.expires_in,
+    response,
+  };
+}
+
 async function handleGenerate(command, deps) {
   const { resolveApiKey, resolveOrigins } = await import("./config.js");
   const {
@@ -403,12 +449,14 @@ async function handleGenerate(command, deps) {
     generateImage,
     generateText,
     generateVideo,
+    getVideo,
     planAudioMusicRequest,
     planAudioRequest,
     planAudioSfxRequest,
     planImageRequest,
     planTextRequest,
     planVideoRequest,
+    uploadTempMediaImage,
   } = await import("./api.js");
   const { persistArtifacts } = await import("./artifacts.js");
   const { createAnimation } = await import("./animation.js");
@@ -428,8 +476,12 @@ async function handleGenerate(command, deps) {
     ...command.options,
     apiKey,
     baseUrl: routerOrigin,
+    env: deps.env ?? process.env,
     fetch: deps.fetch,
   };
+  if (command.group === "video" && !command.options.dry_run) {
+    await uploadVideoLocalImages(options, { uploadTempMediaImage });
+  }
   if (command.options.dry_run) {
     const request = command.group === "image"
       ? planImageRequest(options)
@@ -461,6 +513,9 @@ async function handleGenerate(command, deps) {
               ? await generateAudioMusic(options)
               : await generateAudio(options)
           : await generateText(options);
+    const artifactResponse = command.group === "video"
+      ? await waitForVideoResult(response, { ...options, getVideo, sleep: deps.sleep })
+      : response;
     if (command.group === "text") {
       const text = extractText(response);
       const output = await writeTextOutput(text, command.options.output);
@@ -468,17 +523,111 @@ async function handleGenerate(command, deps) {
     }
     const artifacts = await persistArtifacts({
       kind: command.group,
-      response,
+      response: artifactResponse,
       outDir: command.options.out ?? "flatkey-output",
       output: command.options.output,
       fetch: deps.fetch,
     });
-    return { kind: command.group, artifacts, response: scrubArtifactResponse(response) };
+    return { kind: command.group, artifacts, response: scrubArtifactResponse(artifactResponse) };
   } finally {
     animation.stop();
   }
 }
 
+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;
+
+  const uploads = [];
+  for (const file of localImages) {
+    uploads.push(await uploadLocalImage(file, options, deps));
+  }
+  if (uploads.length > 0) {
+    options.image_url = [...asArray(options.image_url), ...uploads];
+  }
+  if (firstFrame) {
+    options.first_frame_url = await uploadLocalImage(firstFrame, options, deps);
+  }
+  if (lastFrame) {
+    options.last_frame_url = await uploadLocalImage(lastFrame, options, deps);
+  }
+}
+
+async function uploadLocalImage(file, options, deps) {
+  const { basename } = await import("node:path");
+  const { readFile } = await import("node:fs/promises");
+  const response = await deps.uploadTempMediaImage({
+    apiKey: options.apiKey,
+    baseUrl: options.baseUrl,
+    file: await readFile(await expandHomePath(file)),
+    filename: basename(file),
+    fetch: options.fetch,
+  });
+  const url = response?.data?.signed_url ?? response?.signed_url;
+  if (!url) throw new Error(`Image upload failed: missing signed_url for ${file}`);
+  return url;
+}
+
+async function waitForVideoResult(response, options) {
+  if (hasArtifact(response)) return response;
+  const taskId = videoTaskId(response);
+  if (!taskId) return response;
+
+  const timeoutMs = parsePositiveInteger(
+    options.video_wait_timeout_ms ?? options.env?.FLATKEY_VIDEO_WAIT_TIMEOUT_MS,
+    600_000,
+  );
+  const intervalMs = parsePositiveInteger(
+    options.video_poll_interval_ms ?? options.env?.FLATKEY_VIDEO_POLL_INTERVAL_MS,
+    5_000,
+  );
+  const deadline = Date.now() + timeoutMs;
+  let last = response;
+
+  while (Date.now() <= deadline) {
+    last = await options.getVideo(options, taskId);
+    if (hasArtifact(last) || isVideoDone(last)) return last;
+    if (isVideoFailed(last)) {
+      const message = last?.error?.message ?? last?.message ?? `Video generation failed: ${taskId}`;
+      throw new Error(message);
+    }
+    await delay(intervalMs, { sleep: options.sleep });
+  }
+
+  throw new Error(`Video task still processing after ${Math.round(timeoutMs / 1000)}s: ${taskId}`);
+}
+
+function hasArtifact(response) {
+  return Boolean(
+    response?.metadata?.url
+      || response?.url
+      || response?.video_url?.url
+      || response?.data?.some?.((item) => item?.url || item?.b64_json || item?.base64 || item?.data)
+      || response?.artifacts?.some?.((item) => item?.url || item?.path)
+      || response?.content?.some?.((item) => item?.url || item?.video_url?.url || item?.data_url || item?.b64_json || item?.base64 || item?.data),
+  );
+}
+
+function videoTaskId(response) {
+  return firstNonEmpty(response?.id, response?.task_id, response?.taskId, response?.data?.id, response?.data?.task_id);
+}
+
+function isVideoDone(response) {
+  return ["completed", "succeeded", "success"].includes(String(response?.status ?? "").toLowerCase());
+}
+
+function isVideoFailed(response) {
+  return ["failed", "failure", "cancelled", "canceled"].includes(String(response?.status ?? "").toLowerCase())
+    || Boolean(response?.error);
+}
+
+function parsePositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 function scrubArtifactResponse(value) {
   if (Array.isArray(value)) return value.map(scrubArtifactResponse);
   if (!value || typeof value !== "object") {
@@ -606,6 +755,7 @@ function formatHuman(result) {
   if (typeof result === "string") return result;
   if (!result || typeof result !== "object") return String(result);
   if (result.dryRun && result.request) return formatDryRun(result);
+  if (result.kind === "upload") return formatUploadResult(result);
   if (result.kind) return formatGenerationResult(result);
   if (Array.isArray(result.models)) return formatModels(result.models);
   if (Array.isArray(result.voices)) return formatVoices(result.voices);
@@ -625,6 +775,13 @@ function formatDryRun(result) {
   return lines.join("\n");
 }
 
+function formatUploadResult(result) {
+  const lines = ["Image uploaded:"];
+  if (result.url) lines.push(`URL: ${result.url}`);
+  if (result.expiresIn) lines.push(`Expires in: ${result.expiresIn}s`);
+  return lines.join("\n");
+}
+
 function formatGenerationResult(result) {
   if (result.kind === "text") {
     const lines = [result.text || "(empty text)"];

package/src/help.js

@@ -52,6 +52,7 @@ Commands:
   auth status                    Show saved auth state
   onboard --api-key <key>        Save Flatkey API key from https://console.flatkey.ai/keys
   image generate --prompt <txt>  Generate image
+  image upload --file <path>     Upload local image and return a temporary URL
   video generate --prompt <txt>  Generate video
   audio generate --prompt <txt>  Generate speech with ElevenLabs voices
   audio sfx --prompt <txt>       Generate sound effects
@@ -141,14 +142,18 @@ Options:
 
 Options:
   --ai                           Print agent-focused usage guide`,
-  image: `Usage: flatkey image generate --prompt <txt> [options]
+  image: `Usage: flatkey image <command> [options]
+
+Commands:
+  generate --prompt <txt>        Generate image
+  upload --file <path>           Upload local image and return a temporary URL
 
 Options:
-  --model <model>                Model id
-  --size <size>                  Image size for OpenAI-style image models
-  --quality <quality>             Image quality for supported models
-  --n <count>                    Number of images for supported models
-  --output, -o <file>             Write image file
+  --json                         Print machine-readable JSON`,
+  "image upload": `Usage: flatkey image upload --file <path> [options]
+
+Options:
+  --file <path>                  Local image file to upload
   --json                         Print machine-readable JSON`,
   "image generate": `Usage: flatkey image generate --prompt <txt> [options]
 
@@ -212,9 +217,12 @@ Options:
   --duration <seconds>            Video duration
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
   --resolution <value>            480p, 720p, or 1080p
+  --image <file>                  Upload local reference image, repeatable
   --image-url <url>               Add reference image URL, 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
@@ -226,9 +234,12 @@ Options:
   --duration <seconds>            Video duration
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
   --resolution <value>            480p, 720p, or 1080p
+  --image <file>                  Upload local reference image, repeatable
   --image-url <url>               Add reference image URL, 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