@flatkey-ai/cli 0.1.18 → 0.1.20

package/README.md

@@ -92,6 +92,12 @@ flatkey image generate \
   -o cover.png
 ```
 
+Upload a local image and get a temporary signed URL:
+
+```bash
+flatkey image upload --file ./reference.png
+```
+
 ### Generate Video
 
 ```bash
@@ -106,6 +112,27 @@ flatkey video generate \
 Video ratios: `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `1:1`.
 Video resolutions: `480p`, `720p`, `1080p`.
 
+Local reference images are uploaded through Flatkey temporary media first:
+
+```bash
+flatkey video generate \
+  --model Seedance2.0-pro \
+  --prompt "a sleepy kitten, soft window light" \
+  --image ./reference.png \
+  -o kitten.mp4
+```
+
+First/last frame:
+
+```bash
+flatkey video generate \
+  --model Seedance2.0-pro \
+  --prompt "slow camera push-in" \
+  --first-frame ./first.png \
+  --last-frame ./last.png \
+  -o transition.mp4
+```
+
 ### Generate Audio
 
 Text to speech:
@@ -196,6 +223,8 @@ Agent rules:
 - Prefer `FLATKEY_API_KEY`.
 - Always pass `--json` for machine-readable output.
 - Use `--output` / `-o` when the generated file path matters.
+- Use `flatkey image upload --file <path>` for a temporary signed image URL.
+- Use `--image`, `--first-frame`, or `--last-frame` to pass local images into video generation.
 - Call `flatkey models --json` before choosing a model.
 - Call `flatkey audio voices --json` before choosing a TTS `voice_id`.
 - Use `--dry-run` to inspect request shape without spending credits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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")) {
@@ -223,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) {
@@ -234,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/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 {
@@ -410,6 +456,7 @@ async function handleGenerate(command, deps) {
     planImageRequest,
     planTextRequest,
     planVideoRequest,
+    uploadTempMediaImage,
   } = await import("./api.js");
   const { persistArtifacts } = await import("./artifacts.js");
   const { createAnimation } = await import("./animation.js");
@@ -432,6 +479,9 @@ async function handleGenerate(command, deps) {
     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)
@@ -484,6 +534,42 @@ 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;
+
+  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);
@@ -669,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);
@@ -688,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