@flatkey-ai/cli 0.3.4 → 0.3.6

package/README.md

@@ -123,6 +123,30 @@ flatkey image generate \
   -o cover.png
 ```
 
+Reference images (`--file` / `--image-url`) are sent as an image edit: gpt
+models go through `/v1/images/edits`, Gemini models receive them as native
+`fileData` parts, so the input image is preserved instead of being ignored.
+
+Animated GIFs (gpt-image-2.6):
+
+```bash
+flatkey image generate \
+  --prompt "a paper crane folding itself, soft studio light" \
+  --model gpt-image-2.6 \
+  --output-format gif \
+  --frame-count 9 \
+  --frame-duration-ms 200 \
+  --quality high \
+  --complexity low \
+  -o crane.gif
+```
+
+`--output-format` accepts `png`, `jpeg`, `webp`, or `gif`. `--frame-count`,
+`--frame-duration-ms`, `--quality`, and `--complexity` shape the animation.
+These options are gpt image model only; passing them with a Gemini model fails
+instead of silently returning a still image. When no `-o` path is given, saved
+artifacts use the requested format's extension (e.g. `flatkey-output/image-01.gif`).
+
 Upload a local image and get a temporary signed URL:
 
 ```bash

package/package.json

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

package/src/api.js

@@ -3,6 +3,7 @@ import { withCliRequestHeaders } from "./requestHeaders.js";
 export const DEFAULT_BASE_URL = "https://router.flatkey.ai";
 export const DEFAULT_MODELS_BASE_URL = "https://console.flatkey.ai";
 export const DEFAULT_CONSOLE_URL = "https://console.flatkey.ai";
+export const IMAGE_OUTPUT_FORMATS = ["png", "jpeg", "webp", "gif"];
 
 export class FlatkeyError extends Error {
   constructor(message, { status, code } = {}) {
@@ -44,23 +45,45 @@ export function planImageRequest(options) {
   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;
-    return planJsonPost(options, "/v1/images/generations", cleanObject({
+    const payload = cleanObject({
       model,
       prompt: options.prompt,
       size: options.size,
       n: parseOptionalInteger(options.n),
       quality: options.quality,
+      // Animated GIF output and its frame controls are gpt-image-2.6 features.
+      output_format: validateOptionalValue(
+        optionValue(options, "output_format", "outputFormat"),
+        IMAGE_OUTPUT_FORMATS,
+        "output format",
+      ),
+      frame_count: parseOptionalPositiveInteger(
+        optionValue(options, "frame_count", "frameCount"),
+        "frame count",
+      ),
+      frame_duration_ms: parseOptionalPositiveInteger(
+        optionValue(options, "frame_duration_ms", "frameDurationMs"),
+        "frame duration",
+      ),
+      complexity: options.complexity,
       response_format: responseFormat,
       temp_url: tempUrl ?? true,
-      images: imageUrls.length > 0 ? imageUrls : undefined,
-    }));
+    });
+    if (mediaInputs.length === 0) {
+      return planJsonPost(options, "/v1/images/generations", payload);
+    }
+    // Reference images are only honoured on the edits endpoint; generations
+    // silently ignores them and runs a plain text-to-image.
+    return planJsonPost(options, "/v1/images/edits", {
+      ...payload,
+      images: mediaInputs.map((entry) => ({ image_url: entry.url })),
+    });
   }
 
+  assertGptImageOnlyOptions(options, model);
   const path = `/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(options.apiKey)}`;
   return planRequest(options, path, {
     method: "POST",
@@ -72,7 +95,10 @@ export function planImageRequest(options) {
       contents: [{
         parts: [
           { text: options.prompt },
-          ...imageUrls.map((url) => ({ type: "image_url", image_url: { url } })),
+          // Gemini native parts: an OpenAI-style image_url part is ignored upstream.
+          ...mediaInputs.map((entry) => ({
+            fileData: { mimeType: imageMimeType(entry), fileUri: entry.url },
+          })),
         ],
       }],
       temp_url: true,
@@ -80,6 +106,32 @@ export function planImageRequest(options) {
   });
 }
 
+// gpt-image animation and complexity controls have no Gemini equivalent, so
+// silently dropping them would hand back a still PNG with a .gif name.
+const GPT_IMAGE_ONLY_OPTIONS = [
+  ["output_format", "outputFormat"],
+  ["frame_count", "frameCount"],
+  ["frame_duration_ms", "frameDurationMs"],
+  ["complexity"],
+];
+
+function assertGptImageOnlyOptions(options, model) {
+  for (const aliases of GPT_IMAGE_ONLY_OPTIONS) {
+    if (optionValue(options, ...aliases) === undefined) continue;
+    const flag = `--${aliases[0].replaceAll("_", "-")}`;
+    throw new Error(`${flag} is only supported by gpt image models, not ${model}.`);
+  }
+}
+
+function imageMimeType(entry) {
+  if (entry.mime) return entry.mime;
+  const path = String(entry.url ?? "").split(/[?#]/)[0].toLowerCase();
+  if (path.endsWith(".jpg") || path.endsWith(".jpeg")) return "image/jpeg";
+  if (path.endsWith(".webp")) return "image/webp";
+  if (path.endsWith(".gif")) return "image/gif";
+  return "image/png";
+}
+
 export function generateVideo(options) {
   return requestJsonFromPlan(options, planVideoRequest(options));
 }
@@ -393,6 +445,15 @@ function parseOptionalInteger(value) {
   return Number.parseInt(value, 10);
 }
 
+function parseOptionalPositiveInteger(value, name) {
+  if (value === undefined) return undefined;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`Invalid ${name}: ${value}. Expected a positive integer.`);
+  }
+  return parsed;
+}
+
 function parseOptionalFloat(value) {
   if (value === undefined) return undefined;
   return Number.parseFloat(value);

package/src/artifacts.js

@@ -16,39 +16,65 @@ const MIME_EXTENSIONS = {
   "audio/mpeg": "mp3",
   "audio/mp3": "mp3",
   "audio/wav": "wav",
+  "image/gif": "gif",
   "image/jpeg": "jpg",
   "image/png": "png",
+  "image/webp": "webp",
   "video/mp4": "mp4",
 };
 
+const FORMAT_EXTENSIONS = {
+  gif: "gif",
+  jpeg: "jpg",
+  jpg: "jpg",
+  png: "png",
+  webp: "webp",
+};
+
 export async function persistArtifacts({
   kind,
   response,
   outDir = "flatkey-output",
   output,
+  format,
   fetch: fetchImpl = fetch,
 }) {
   output = expandHomePath(output);
   const items = extractItems(response);
   const artifacts = [];
+  const extension = artifactExtension({ kind, format });
   await mkdir(output ? dirname(output) : outDir, { recursive: true });
-  const startIndex = output ? 0 : await nextArtifactIndex({ kind, outDir });
+  const startIndex = output ? 0 : await nextArtifactIndex({ kind, outDir, format });
 
   for (const [index, item] of items.entries()) {
-    const artifact = await persistItem({ kind, item, outDir, output, index: index + startIndex, fetchImpl });
+    const artifact = await persistItem({
+      kind,
+      item,
+      outDir,
+      output,
+      index: index + startIndex,
+      extension,
+      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 });
+export async function nextArtifactPath({ kind, outDir = "flatkey-output", format }) {
+  const extension = artifactExtension({ kind, format });
+  const index = await nextArtifactIndex({ kind, outDir, format });
   const number = String(index + 1).padStart(2, "0");
   return join(outDir, `${kind}-${number}.${extension}`);
 }
 
+function artifactExtension({ kind, format }) {
+  return FORMAT_EXTENSIONS[String(format ?? "").toLowerCase()]
+    ?? DEFAULT_EXTENSIONS[kind]
+    ?? "bin";
+}
+
 function expandHomePath(path) {
   if (typeof path !== "string") return path;
   if (path === "~") return homedir();
@@ -56,7 +82,7 @@ function expandHomePath(path) {
   return path;
 }
 
-async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
+async function persistItem({ kind, item, outDir, output, index, extension, fetchImpl }) {
   const dataUrl = getString(item, ["url", "video_url", "data_url", "dataUrl", "temp_url"]);
   if (dataUrl?.startsWith("data:")) {
     const parsed = parseDataUrl(dataUrl);
@@ -66,13 +92,7 @@ async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
   }
   if (dataUrl?.startsWith("http://") || dataUrl?.startsWith("https://")) {
     if (output) {
-      const path = artifactPath({
-        kind,
-        outDir,
-        output,
-        index,
-        extension: DEFAULT_EXTENSIONS[kind] ?? "bin",
-      });
+      const path = artifactPath({ kind, outDir, output, index, extension });
       await downloadArtifact({ url: dataUrl, path, fetchImpl });
       return { path };
     }
@@ -81,7 +101,7 @@ async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
 
   const base64 = getString(item, ["b64_json", "base64", "data"]);
   if (base64) {
-    const path = artifactPath({ kind, outDir, output, index, extension: DEFAULT_EXTENSIONS[kind] });
+    const path = artifactPath({ kind, outDir, output, index, extension });
     await writeFile(path, Buffer.from(base64, "base64"));
     return { path };
   }
@@ -145,8 +165,8 @@ function artifactPath({ kind, outDir, output, index, extension }) {
   return join(outDir, `${kind}-${number}.${extension}`);
 }
 
-async function nextArtifactIndex({ kind, outDir }) {
-  const extension = DEFAULT_EXTENSIONS[kind] ?? "bin";
+async function nextArtifactIndex({ kind, outDir, format }) {
+  const extension = artifactExtension({ kind, format });
   const pattern = new RegExp(`^${escapeRegExp(kind)}-(\\d+)\\.${escapeRegExp(extension)}$`);
   let max = 0;
   try {

package/src/cli.js

@@ -32,7 +32,7 @@ const COMMAND_OPTIONS = {
   credits: new Set([]),
   help: new Set(["ai", "command"]),
   image: new Set([]),
-  "image generate": new Set(["file", "image", "image_url", "model", "n", "prompt", "quality", "size"]),
+  "image generate": new Set(["complexity", "file", "frame_count", "frame_duration_ms", "image", "image_url", "model", "n", "output_format", "prompt", "quality", "size"]),
   "image upload": new Set(["file"]),
   login: new Set(["console_url", "no_open", "open"]),
   logout: new Set([]),
@@ -669,6 +669,7 @@ async function handleGenerate(command, deps) {
       return { kind: command.group, text, output, response };
     }
     const outDir = command.options.out ?? "flatkey-output";
+    const format = command.group === "image" ? command.options.output_format : undefined;
     const output = command.options.output
       ?? (command.group === "video" ? await nextArtifactPath({ kind: command.group, outDir }) : undefined);
     const artifacts = await persistArtifacts({
@@ -676,6 +677,7 @@ async function handleGenerate(command, deps) {
       response: artifactResponse,
       outDir,
       output,
+      format,
       fetch: deps.fetch,
     });
     return {

package/src/help.js

@@ -15,6 +15,7 @@ JSON mode:
 
 Commands:
 - flatkey image generate --prompt "<prompt>" --json [--model <model>] [--file <path>] [--image-url <url>] [--output image.png]
+- flatkey image generate --prompt "<prompt>" --json --model gpt-image-2.6 --output-format gif [--frame-count 9] [--frame-duration-ms 200] [--quality high] [--complexity low] [--output loop.gif]
 - 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 video copy --source input.mp4 --json [--model seedance2] [--frame-ratio 80] [--depth-resolution 480p] [--output video.mp4]
 - flatkey audio generate --prompt "<text>" --json [--voice-id <voice_id>] [--model eleven_multilingual_v2] [--output speech.mp3]
@@ -83,6 +84,14 @@ Environment:
 Video options:
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, or adaptive
   --resolution <value>            480p, 720p, or 1080p
+
+Image options (gpt image models):
+  --size <size>                   Image size, e.g. 1024x1024
+  --quality <quality>             Image quality, e.g. high
+  --output-format <format>        png, jpeg, webp, or gif
+  --frame-count <count>           Animation frames for gif output
+  --frame-duration-ms <ms>        Milliseconds per gif frame
+  --complexity <level>            Animation complexity, e.g. low
 `;
 }
 
@@ -168,6 +177,10 @@ 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
+  --output-format <format>        png, jpeg, webp, or gif; gpt image models only
+  --frame-count <count>           Animation frames for gif output, gpt image models only
+  --frame-duration-ms <ms>        Milliseconds per gif frame, gpt image models only
+  --complexity <level>            Animation complexity, e.g. low; gpt image models only
   --file <path>                  Local image input, repeatable
   --image-url <url>               Remote image input, repeatable
   --output, -o <file>             Write image file