focalapi-cli 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.1 - 2026-08-18
+
+- Added `@file` syntax for local reference media on all gen paths (`--image @C:/path/ref.jpg`): the file is read and inlined as a data URI with per-file 8MB and per-command 12MB guards — local files no longer require manual hosting.
+- Bare local paths (e.g., `C:/...` without `@`) are intercepted locally with actionable guidance to add the `@` prefix or host the file, instead of round-tripping to the server's 400.
+- Added `--content @file.json` and `--content -` (stdin) for gen video, bypassing the Windows ~32KB argv limit for multi-image content arrays; capped at 64MB.
+- Added `task download --direct`: fetches the task's upstream artifact URL directly (CDN/edge typically beats the cross-border gateway hop; measured 328KB/s client-side vs 26MB/s server-local) and falls back to the gateway proxy automatically.
+- Added grok video prompt budget validation: the upstream 4096-character limit applies to the composite of text plus ~500 characters per reference image — the CLI mirrors the gateway's calibrated gate and rejects locally before submission.
+
+## 0.4.0 - 2026-08-18
+
+- Added `task status --wait [--download]`: built-in bounded polling with elapsed-time reporting and an optional auto-download, so agents never need to write their own poller (the audited agent session's custom script crashed on the Windows `.cmd` shim and stalled blind).
+- Added `task list [--status] [--action] [--limit] [--offset]` backed by `GET /v1/tasks`, so a caller that lost a submission output can reconcile recent tasks instead of resubmitting and double-charging.
+- Added `--idempotency-key` to `gen video` and async `gen image`: same-key retries replay the original task server-side without a second charge. Keys are auto-generated when omitted, breadcrumbed on stderr (`idempotency_key=...`), and the server's `idempotent_replay` marker is surfaced in both JSON output and stderr.
+- Aligned `task download --json` output with `gen image` by exposing `files[]` alongside the legacy `file`.
+- Added a stderr warning for double-encoded reference URLs (`%25XX`) before submission — the top cause of 403 `invalid_reference_url` from presigned URLs.
+
 ## 0.3.1 - 2026-08-18
 
 - Added `--duration` as an alias of `--seconds` on `gen video` so the API contract field name works directly; conflicting values are rejected locally.

package/dist/cli.js

@@ -176,7 +176,7 @@ function displayWidth(s) {
 }
 
 // src/lib/version.ts
-var VERSION = true ? "0.3.1" : "0.0.0-dev";
+var VERSION = true ? "0.4.1" : "0.0.0-dev";
 
 // src/commands/auth.ts
 import { createInterface } from "readline/promises";
@@ -912,10 +912,11 @@ function registerDoctor(program) {
 
 // src/commands/gen.ts
 import { createWriteStream as createWriteStream2 } from "fs";
-import { mkdir as mkdir2, writeFile } from "fs/promises";
-import { join as join3, resolve as resolve2 } from "path";
+import { mkdir as mkdir2, readFile, writeFile } from "fs/promises";
+import { extname as extname2, join as join3, resolve as resolve2 } from "path";
 import { pipeline as pipeline2 } from "stream/promises";
 import { Readable as Readable2 } from "stream";
+import { randomUUID } from "crypto";
 
 // src/lib/model-capabilities.ts
 var GEMINI_IMAGE_MAX_SEED = 9007199254740991;
@@ -1157,7 +1158,8 @@ var VIDEO_CONSTRAINTS = {
     disallowReferences: true,
     maxFirstFrameImages: 1,
     supportsGenerateAudio: false,
-    supportsWatermark: false
+    supportsWatermark: false,
+    maxPromptRunes: 4096
   },
   "grok-imagine-video-1.5": {
     resolutions: ["480p", "720p", "1080p"],
@@ -1168,7 +1170,8 @@ var VIDEO_CONSTRAINTS = {
     referenceResolutions: ["480p", "720p"],
     maxFirstFrameImages: 1,
     supportsGenerateAudio: false,
-    supportsWatermark: false
+    supportsWatermark: false,
+    maxPromptRunes: 4096
   },
   "kling-3.0": {
     resolutions: ["720p", "1080p", "4k"],
@@ -1394,6 +1397,12 @@ function validateGeminiImageGeneration(model, input) {
 function validateVideoGeneration(model, input) {
   const constraint = VIDEO_CONSTRAINTS[model.trim()];
   if (!constraint) return;
+  if (constraint.maxPromptRunes !== void 0 && input.promptRunes !== void 0) {
+    const referenceCount = input.imageCount ?? input.firstFrameCount ?? 0;
+    if (input.promptRunes + 500 * referenceCount > constraint.maxPromptRunes) {
+      throw new ApiError("invalid_request", `${model} prompt budget exceeded: upstream counts prompt text plus ~500 characters per reference image against its ${constraint.maxPromptRunes}-character limit (received ${input.promptRunes} characters of text + ${referenceCount} reference images)`);
+    }
+  }
   if ((input.imageCount ?? 0) > 0 && (input.firstFrameCount ?? 0) > 0) {
     throw new ApiError("invalid_request", `${model}: --image and --first-frame are mutually exclusive (reference-to-video vs image-to-video)`);
   }
@@ -1526,6 +1535,19 @@ function extractProgress(body) {
   }
   return void 0;
 }
+function extractCreatedAt(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const obj = raw;
+  const candidates = [obj.created_at, obj.data?.created_at];
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && candidate > 0) return candidate;
+    if (typeof candidate === "string") {
+      const parsed = Number.parseInt(candidate, 10);
+      if (Number.isFinite(parsed) && parsed > 0) return parsed;
+    }
+  }
+  return void 0;
+}
 async function cancelTask(baseUrl, apiKey, taskId) {
   try {
     await request({
@@ -1588,9 +1610,24 @@ async function fetchTask(baseUrl, apiKey, taskId) {
     status: normalizeTaskStatus(rawStatus),
     rawStatus,
     progress: extractProgress(raw),
+    createdAt: extractCreatedAt(raw),
     raw
   };
 }
+async function listTasks(baseUrl, apiKey, opts) {
+  const raw = await request({
+    baseUrl,
+    path: "/v1/tasks",
+    apiKey,
+    query: {
+      status: opts?.status,
+      action: opts?.action,
+      limit: opts?.limit,
+      offset: opts?.offset
+    }
+  });
+  return raw.data ?? [];
+}
 async function pollTask(baseUrl, apiKey, taskId, opts) {
   const intervalMs = opts?.intervalMs ?? 5e3;
   const timeoutMs = opts?.timeoutMs ?? 30 * 6e4;
@@ -1615,7 +1652,7 @@ async function pollTask(baseUrl, apiKey, taskId, opts) {
     }
     if (Date.now() > deadline) {
       throw new ApiError("timeout", `\u4EFB\u52A1 ${taskId} \u7B49\u5F85\u8D85\u65F6\uFF08${Math.round(timeoutMs / 6e4)} \u5206\u949F\uFF09`, {
-        hint: `\u53EF\u7A0D\u540E\u8FD0\u884C focalapi task status ${taskId} \u67E5\u770B\uFF0C\u6216 focalapi task download ${taskId} \u7EED\u53D6\u4EA7\u7269\u3002`
+        hint: `\u53EF\u8FD0\u884C focalapi task status ${taskId} --wait \u7EE7\u7EED\u7B49\u5F85\uFF0C\u6216 focalapi task status ${taskId} \u67E5\u770B\u5F53\u524D\u72B6\u6001\u3002`
       });
     }
     await new Promise((r) => setTimeout(r, intervalMs));
@@ -1630,6 +1667,46 @@ var EXT_BY_CONTENT_TYPE = {
   "audio/mpeg": ".mp3",
   "audio/wav": ".wav"
 };
+function extractTaskArtifactURL(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const obj = raw;
+  const data = obj.data;
+  const candidates = [obj.url, data?.url, data?.data?.url, data?.data?.video_url];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && /^https?:\/\//.test(candidate)) return candidate;
+  }
+  return void 0;
+}
+async function downloadTaskArtifact(baseUrl, apiKey, taskId, outDir, opts) {
+  let upstreamURL;
+  if (opts?.direct) {
+    const info2 = await fetchTask(baseUrl, apiKey, taskId);
+    upstreamURL = extractTaskArtifactURL(info2.raw);
+    if (upstreamURL) {
+      try {
+        const res = await fetch(upstreamURL, {
+          signal: AbortSignal.timeout(6e5)
+        });
+        if (res.ok && res.body) {
+          const contentType = res.headers.get("content-type")?.split(";")[0]?.trim() ?? "";
+          const ext = EXT_BY_CONTENT_TYPE[contentType] ?? extFromURL(upstreamURL) ?? ".bin";
+          const dir = resolve(outDir);
+          await mkdir(dir, { recursive: true });
+          const filePath = join2(dir, `${opts?.filenameBase ?? `task-${taskId}`}${ext}`);
+          await pipeline(Readable.fromWeb(res.body), createWriteStream(filePath));
+          return { file: filePath, source: "upstream" };
+        }
+      } catch {
+      }
+    }
+  }
+  const file = await downloadTaskContent(baseUrl, apiKey, taskId, outDir, opts?.filenameBase);
+  return { file, source: "proxy" };
+}
+function extFromURL(url) {
+  const match = /\.(mp4|webm|png|jpe?g|webp|mp3|wav)(?:[?#]|$)/i.exec(url);
+  return match ? match[1].toLowerCase() === "jpeg" ? ".jpg" : `.${match[1].toLowerCase()}` : void 0;
+}
 async function downloadTaskContent(baseUrl, apiKey, taskId, outDir, filenameBase) {
   const res = await rawRequest({
     baseUrl,
@@ -1653,6 +1730,20 @@ async function downloadTaskContent(baseUrl, apiKey, taskId, outDir, filenameBase
 var MAX_IMAGE_N = 128;
 var MAX_TASK_DURATION_SECONDS = 3600;
 var DEFAULT_OUT_DIR = "focalapi-out";
+function resolveIdempotencyKey(provided) {
+  const key = provided?.trim() || randomUUID();
+  if (!/^[\x21-\x7e]{8,128}$/.test(key)) {
+    throw new ApiError("invalid_request", "--idempotency-key \u5FC5\u987B\u662F 8\u2013128 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF08\u6536\u5230\uFF1A" + provided + "\uFF09");
+  }
+  return key;
+}
+function warnDoubleEncodedReferenceURLs(label, urls) {
+  for (const url of urls) {
+    if (url && /%25[0-9a-f]{2}/i.test(url)) {
+      info(`\u8B66\u544A\uFF1A${label} \u7684 URL \u7591\u4F3C\u88AB\u4E8C\u6B21\u7F16\u7801\uFF08\u5305\u542B %25XX\uFF09\uFF1A${url.slice(0, 100)} \u2014\u2014 \u9884\u7B7E\u540D URL \u5FC5\u987B\u539F\u6837\u4F20\u9012\uFF0C\u5426\u5219\u4E0A\u6E38\u4F1A\u8FD4\u56DE 403 invalid_reference_url`);
+    }
+  }
+}
 function clampInt(value, min, max, name) {
   if (!Number.isInteger(value) || value < min || value > max) {
     throw new ApiError("invalid_request", `${name} \u5FC5\u987B\u662F ${min}\u2013${max} \u7684\u6574\u6570\uFF08\u6536\u5230\uFF1A${value}\uFF09`);
@@ -1726,6 +1817,93 @@ function parseJsonArray(raw, option) {
     throw new ApiError("invalid_request", `--${option} must be a JSON array`);
   }
 }
+var MAX_CONTENT_FILE_BYTES = 64 * 1024 * 1024;
+async function readContentArgument(raw) {
+  if (raw === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.from(chunk));
+      if (Buffer.concat(chunks).byteLength > MAX_CONTENT_FILE_BYTES) {
+        throw new ApiError("invalid_request", "--content stdin \u8F93\u5165\u8D85\u8FC7 64MB \u4E0A\u9650");
+      }
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  if (raw.startsWith("@")) {
+    const path = raw.slice(1);
+    let content;
+    try {
+      content = await readFile(path);
+    } catch (err) {
+      throw new ApiError("invalid_request", `\u8BFB\u53D6 --content \u6587\u4EF6\u5931\u8D25 @${path}\uFF1A${err.message}`);
+    }
+    if (content.byteLength > MAX_CONTENT_FILE_BYTES) {
+      throw new ApiError("invalid_request", `--content \u6587\u4EF6 ${(content.byteLength / 1048576).toFixed(1)}MB \u8D85\u8FC7 64MB \u4E0A\u9650`);
+    }
+    return content.toString("utf8");
+  }
+  return raw;
+}
+var MAX_LOCAL_MEDIA_BYTES = 8 * 1024 * 1024;
+var MAX_TOTAL_LOCAL_MEDIA_BYTES = 12 * 1024 * 1024;
+var MEDIA_MIME_BY_EXT = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav"
+};
+async function resolveMediaInputs(sources) {
+  let totalLocalBytes = 0;
+  const resolved = [];
+  for (const source of sources) {
+    if (!source) continue;
+    if (!source.startsWith("@")) {
+      const lowered = source.toLowerCase();
+      if (!source.startsWith("data:") && !lowered.startsWith("http://") && !lowered.startsWith("https://")) {
+        throw new ApiError("invalid_request", `\u53C2\u8003\u5A92\u4F53\u5FC5\u987B\u662F http(s) URL\u3001data URI \u6216 @\u672C\u5730\u8DEF\u5F84\uFF08\u6536\u5230\uFF1A${source.slice(0, 80)}\uFF09`, {
+          hint: "\u672C\u5730\u6587\u4EF6\u8BF7\u52A0 @ \u524D\u7F00\u5185\u8054\uFF08\u5982 --image @C:/imgs/ref.png\uFF0C\u5355\u6587\u4EF6 \u22648MB\uFF09\uFF1B\u5927\u56FE/\u591A\u56FE\u8BF7\u5148\u6258\u7BA1\u4E3A URL \u518D\u4F20\u5165\u3002"
+        });
+      }
+      resolved.push(source);
+      continue;
+    }
+    const path = source.slice(1);
+    let content;
+    try {
+      content = await readFile(path);
+    } catch (err) {
+      throw new ApiError("invalid_request", `\u8BFB\u53D6\u672C\u5730\u5A92\u4F53\u5931\u8D25 @${path}\uFF1A${err.message}`, {
+        hint: "@ \u540E\u9762\u662F\u6587\u4EF6\u8DEF\u5F84\uFF08\u5982 --image @C:/imgs/ref.png\uFF09\u3002\u82E5\u6587\u4EF6\u5728\u522B\u7684\u4E3B\u673A\u4E0A\uFF0C\u8BF7\u5148\u6258\u7BA1\u5E76\u4F20 http(s) URL\u3002"
+      });
+    }
+    const ext = extname2(path).toLowerCase();
+    const mime = MEDIA_MIME_BY_EXT[ext];
+    if (!mime) {
+      throw new ApiError("invalid_request", `\u4E0D\u652F\u6301\u7684\u672C\u5730\u5A92\u4F53\u7C7B\u578B ${ext}\uFF08@${path}\uFF09`, {
+        hint: `\u652F\u6301\uFF1A${Object.keys(MEDIA_MIME_BY_EXT).join(" ")}`
+      });
+    }
+    if (content.byteLength > MAX_LOCAL_MEDIA_BYTES) {
+      throw new ApiError("invalid_request", `\u672C\u5730\u5A92\u4F53 @${path} \u4E3A ${(content.byteLength / 1048576).toFixed(1)}MB\uFF0C\u8D85\u8FC7\u5355\u6587\u4EF6 ${MAX_LOCAL_MEDIA_BYTES / 1048576}MB \u4E0A\u9650`, {
+        hint: "\u5927\u6587\u4EF6\u8BF7\u5148\u538B\u7F29\u6216\u6258\u7BA1\u4E3A URL \u518D\u4F20\u5165\uFF1B\u547D\u4EE4\u884C\u5185\u8054\u4EC5\u9002\u5408\u4E2D\u5C0F\u56FE\u3002"
+      });
+    }
+    totalLocalBytes += content.byteLength;
+    if (totalLocalBytes > MAX_TOTAL_LOCAL_MEDIA_BYTES) {
+      throw new ApiError("invalid_request", `\u672C\u5730\u5A92\u4F53\u603B\u91CF\u8D85\u8FC7 ${MAX_TOTAL_LOCAL_MEDIA_BYTES / 1048576}MB \u4E0A\u9650`, {
+        hint: "\u591A\u5F20\u5927\u56FE\u8BF7\u5148\u6258\u7BA1\u4E3A URL\uFF08\u751F\u6210\u7C7B\u63A5\u53E3\u8FD4\u56DE\u7684\u4EA7\u7269 URL \u53EF\u76F4\u63A5\u590D\u7528\uFF09\u3002"
+      });
+    }
+    resolved.push(`data:${mime};base64,${content.toString("base64")}`);
+  }
+  return resolved;
+}
 function parseGeminiResponseModalities(raw) {
   const modalities = raw.split(",").map((value) => value.trim().toUpperCase()).filter(Boolean);
   const unique = new Set(modalities);
@@ -1769,7 +1947,7 @@ function extractGeminiImageItems(response) {
 }
 function registerGen(program) {
   const gen = program.command("gen").description("\u56FE\u50CF / \u89C6\u9891\u751F\u6210");
-  gen.command("image").description("\u751F\u6210\u56FE\u50CF\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u56FE\u50CF\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--size <size>", "\u5C3A\u5BF8\uFF0C\u5982 1024x1024").option("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9").option("--resolution <resolution>", "\u6A21\u578B\u539F\u751F\u8F93\u51FA\u6863\u4F4D\uFF0C\u5982 1k\u30012k").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--quality <quality>", "\u56FE\u50CF\u8D28\u91CF\u6863\u4F4D\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09").option("--background <background>", "\u80CC\u666F\u6A21\u5F0F\uFF08\u4EC5 gpt-image-2 \u652F\u6301 auto/opaque\uFF09").option("--negative-prompt <text>", "\u8D1F\u9762\u63D0\u793A\u8BCD\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09").option("--creativity <level>", "\u63D0\u793A\u8BCD\u6269\u5C55\u5F3A\u5EA6\uFF0C\u5982 raw\u3001low\u3001medium\u3001high").option("--prompt-extend <boolean>", "\u662F\u5426\u6269\u5C55\u63D0\u793A\u8BCD\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "prompt-extend")).option("--style-references <json>", "Krea image_style_references JSON \u6570\u7EC4").option("--moodboards <json>", "Krea moodboards JSON \u6570\u7EC4").option("--watermark <boolean>", "\u662F\u5426\u6DFB\u52A0\u6C34\u5370\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => parseBooleanOption(v, "watermark")).option("--output-format <format>", "\u8F93\u51FA\u683C\u5F0F\uFF08\u4EC5 Seedream\uFF1Apng \u6216 jpeg\uFF09").option("--optimize-prompt <mode>", "\u63D0\u793A\u8BCD\u4F18\u5316\uFF08\u4EC5 Seedream\uFF1Aauto\u3001enabled \u6216 disabled\uFF09").option("--image <url...>", "\u53C2\u8003\u56FE\u6216\u7F16\u8F91\u56FE URL\uFF0C\u53EF\u591A\u4E2A").option("--mask <url>", "\u7F16\u8F91 mask URL\uFF08gpt-image-2 \u9700\u8981\u5355\u5F20\u53C2\u8003\u56FE\uFF09").option("--response-format <format>", "\u56FE\u50CF\u54CD\u5E94\u683C\u5F0F\uFF1Aurl \u6216 b64_json").option("--n <count>", "\u5F20\u6570\uFF081\u2013128\uFF09", (v) => Number.parseInt(v, 10), 1).option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u56FE\u50CF\u751F\u6210\u5B8C\u6210").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).action(async (promptParts, opts, cmd) => {
+  gen.command("image").description("\u751F\u6210\u56FE\u50CF\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u56FE\u50CF\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--size <size>", "\u5C3A\u5BF8\uFF0C\u5982 1024x1024").option("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9").option("--resolution <resolution>", "\u6A21\u578B\u539F\u751F\u8F93\u51FA\u6863\u4F4D\uFF0C\u5982 1k\u30012k").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--quality <quality>", "\u56FE\u50CF\u8D28\u91CF\u6863\u4F4D\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09").option("--background <background>", "\u80CC\u666F\u6A21\u5F0F\uFF08\u4EC5 gpt-image-2 \u652F\u6301 auto/opaque\uFF09").option("--negative-prompt <text>", "\u8D1F\u9762\u63D0\u793A\u8BCD\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09").option("--creativity <level>", "\u63D0\u793A\u8BCD\u6269\u5C55\u5F3A\u5EA6\uFF0C\u5982 raw\u3001low\u3001medium\u3001high").option("--prompt-extend <boolean>", "\u662F\u5426\u6269\u5C55\u63D0\u793A\u8BCD\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "prompt-extend")).option("--style-references <json>", "Krea image_style_references JSON \u6570\u7EC4").option("--moodboards <json>", "Krea moodboards JSON \u6570\u7EC4").option("--watermark <boolean>", "\u662F\u5426\u6DFB\u52A0\u6C34\u5370\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => parseBooleanOption(v, "watermark")).option("--output-format <format>", "\u8F93\u51FA\u683C\u5F0F\uFF08\u4EC5 Seedream\uFF1Apng \u6216 jpeg\uFF09").option("--optimize-prompt <mode>", "\u63D0\u793A\u8BCD\u4F18\u5316\uFF08\u4EC5 Seedream\uFF1Aauto\u3001enabled \u6216 disabled\uFF09").option("--image <url...>", "\u53C2\u8003\u56FE/\u7F16\u8F91\u56FE URL \u6216\u672C\u5730\u8DEF\u5F84\uFF08@C:/path/x.jpg \u81EA\u52A8\u5185\u8054\uFF09\uFF0C\u53EF\u591A\u4E2A").option("--mask <url>", "\u7F16\u8F91 mask URL\uFF08gpt-image-2 \u9700\u8981\u5355\u5F20\u53C2\u8003\u56FE\uFF09").option("--response-format <format>", "\u56FE\u50CF\u54CD\u5E94\u683C\u5F0F\uFF1Aurl \u6216 b64_json").option("--n <count>", "\u5F20\u6570\uFF081\u2013128\uFF09", (v) => Number.parseInt(v, 10), 1).option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u56FE\u50CF\u751F\u6210\u5B8C\u6210").option("--idempotency-key <key>", "\u5E42\u7B49\u952E\uFF088\u2013128 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF09\u3002\u540C\u4E00 key \u7684\u91CD\u590D\u63D0\u4EA4\u62FF\u56DE\u539F\u4EFB\u52A1\u800C\u4E0D\u91CD\u590D\u8BA1\u8D39\uFF1B\u7701\u7565\u65F6\u81EA\u52A8\u751F\u6210\u3002\u91CD\u8BD5\u4E0D\u786E\u5B9A\u7684\u63D0\u4EA4\u65F6\u52A1\u5FC5\u590D\u7528\u539F key").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).action(async (promptParts, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
     const model = opts.model ?? (await resolveCreativeModel(auth, "image")).model.id;
@@ -1777,6 +1955,8 @@ function registerGen(program) {
     const n = clampInt(opts.n, 1, MAX_IMAGE_N, "n");
     const styleReferences = opts.styleReferences ? parseJsonArray(opts.styleReferences, "style-references") : void 0;
     const moodboards = opts.moodboards ? parseJsonArray(opts.moodboards, "moodboards") : void 0;
+    const referenceImages = await resolveMediaInputs(opts.image ?? []);
+    const maskImage = (await resolveMediaInputs(opts.mask ? [opts.mask] : []))[0];
     validateImageGeneration(model, {
       n,
       size: opts.size,
@@ -1794,8 +1974,8 @@ function registerGen(program) {
       styleReferenceCount: styleReferences?.length,
       moodboardCount: moodboards?.length,
       responseFormat: opts.responseFormat,
-      imageCount: opts.image?.length,
-      hasMask: Boolean(opts.mask)
+      imageCount: referenceImages.length,
+      hasMask: Boolean(maskImage)
     });
     if (opts.wait === false && opts.responseFormat === "b64_json") {
       throw new ApiError("invalid_request", "--response-format b64_json cannot be used with --no-wait; use url");
@@ -1815,15 +1995,20 @@ function registerGen(program) {
     if (opts.watermark !== void 0) body.watermark = opts.watermark;
     if (opts.outputFormat) body.output_format = opts.outputFormat.toLowerCase();
     if (opts.optimizePrompt) body.optimize_prompt_options = { thinking: opts.optimizePrompt.toLowerCase() };
-    if (opts.image) body.image = opts.image;
-    if (opts.mask) body.mask = opts.mask;
+    if (referenceImages.length > 0) body.image = referenceImages;
+    if (maskImage) body.mask = maskImage;
     if (opts.responseFormat) body.response_format = opts.responseFormat;
+    const idempotencyKey = opts.wait === false ? resolveIdempotencyKey(opts.idempotencyKey) : void 0;
+    warnDoubleEncodedReferenceURLs("--image", referenceImages);
     const res = await withProgress(opts.wait === false ? "\u6B63\u5728\u63D0\u4EA4\u56FE\u50CF\u4EFB\u52A1" : "\u6B63\u5728\u751F\u6210\u56FE\u50CF", () => request({
       baseUrl: auth.baseUrl,
       path: "/v1/images/generations",
       apiKey: auth.apiKey,
       body,
-      headers: opts.wait === false ? { Prefer: "respond-async" } : void 0,
+      headers: {
+        ...opts.wait === false ? { Prefer: "respond-async" } : {},
+        ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
+      },
       timeoutMs: 6e5
     }));
     if (opts.wait === false) {
@@ -1832,8 +2017,9 @@ function registerGen(program) {
         throw new ApiError("bad_response", "\u5F02\u6B65\u56FE\u50CF\u4EFB\u52A1\u54CD\u5E94\u4E2D\u672A\u627E\u5230 task_id", { body: res });
       }
       info(`task_id=${taskId}`);
+      if (idempotencyKey) info(`idempotency_key=${idempotencyKey}`);
       if (g.json) {
-        printJson({ model, task_id: taskId, status: res.status ?? "queued", submitted: true, next_command: `focalapi task status ${taskId} --json` });
+        printJson({ model, task_id: taskId, status: res.status ?? "queued", submitted: true, ...res.idempotent_replay ? { idempotent_replay: true } : {}, next_command: `focalapi task status ${taskId} --json` });
       } else {
         process.stdout.write(taskId + "\n");
         info(`\u4EFB\u52A1\u5DF2\u63D0\u4EA4\u3002\u67E5\u8BE2\uFF1Afocalapi task status ${taskId}`);
@@ -1857,18 +2043,19 @@ function registerGen(program) {
       for (const f of files) info(`\u2713 ${f}`);
     }
   });
-  gen.command("gemini-image").description("\u4F7F\u7528 Gemini \u539F\u751F generateContent \u63A5\u53E3\u751F\u6210\u56FE\u50CF").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "Gemini \u56FE\u50CF\u6A21\u578B ID\uFF1B\u5148\u7528 focalapi models get \u786E\u8BA4").option("--aspect-ratio <ratio>", "\u753B\u9762\u6BD4\u4F8B\uFF0C\u4F8B\u5982 1:1\u300116:9\u3001auto").option("--image-size <size>", "\u8F93\u51FA\u5C3A\u5BF8\uFF0C\u4F8B\u5982 1K\u30012K\u30014K").option("--response-modalities <modalities>", "\u8F93\u51FA\u7C7B\u578B\uFF1AIMAGE \u6216 IMAGE,TEXT\uFF1B\u672A\u4F20\u65F6\u7531\u670D\u52A1\u7AEF\u9ED8\u8BA4 IMAGE,TEXT").option("--config <json>", "\u9644\u52A0 Gemini generationConfig JSON\uFF1B\u547D\u4EE4\u56FA\u5B9A responseFormat.image \u548C\u5355\u5019\u9009").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--image <url...>", "Gemini reference image URL or data URI; repeatable").option("--system <text>", "Gemini systemInstruction text").option("--seed <n>", "Non-negative Gemini generation seed", (v) => Number.parseInt(v, 10)).option("--thinking-level <level>", "Nano Banana 2 Lite: MINIMAL or HIGH").option("--temperature <n>", "Nano Banana 2 Lite: 0 through 2", (v) => Number.parseFloat(v)).option("--top-p <n>", "Nano Banana 2 Lite: 0 through 1", (v) => Number.parseFloat(v)).action(async (promptParts, opts, cmd) => {
+  gen.command("gemini-image").description("\u4F7F\u7528 Gemini \u539F\u751F generateContent \u63A5\u53E3\u751F\u6210\u56FE\u50CF").argument("<prompt...>", "\u63D0\u793A\u8BCD").requiredOption("-m, --model <model>", "Gemini \u56FE\u50CF\u6A21\u578B ID\uFF1B\u5148\u7528 focalapi models get \u786E\u8BA4").option("--aspect-ratio <ratio>", "\u753B\u9762\u6BD4\u4F8B\uFF0C\u4F8B\u5982 1:1\u300116:9\u3001auto").option("--image-size <size>", "\u8F93\u51FA\u5C3A\u5BF8\uFF0C\u4F8B\u5982 1K\u30012K\u30014K").option("--response-modalities <modalities>", "\u8F93\u51FA\u7C7B\u578B\uFF1AIMAGE \u6216 IMAGE,TEXT\uFF1B\u672A\u4F20\u65F6\u7531\u670D\u52A1\u7AEF\u9ED8\u8BA4 IMAGE,TEXT").option("--config <json>", "\u9644\u52A0 Gemini generationConfig JSON\uFF1B\u547D\u4EE4\u56FA\u5B9A responseFormat.image \u548C\u5355\u5019\u9009").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--image <url...>", "Gemini reference image URL, data URI, or local path (@C:/path/x.jpg); repeatable").option("--system <text>", "Gemini systemInstruction text").option("--seed <n>", "Non-negative Gemini generation seed", (v) => Number.parseInt(v, 10)).option("--thinking-level <level>", "Nano Banana 2 Lite: MINIMAL or HIGH").option("--temperature <n>", "Nano Banana 2 Lite: 0 through 2", (v) => Number.parseFloat(v)).option("--top-p <n>", "Nano Banana 2 Lite: 0 through 1", (v) => Number.parseFloat(v)).action(async (promptParts, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
+    const geminiReferenceImages = await resolveMediaInputs(opts.image ?? []);
     validateGeminiImageGeneration(opts.model, {
+      referenceImageCount: geminiReferenceImages.length,
+      nonDataUriReferenceCount: geminiReferenceImages.filter((source) => !source.startsWith("data:")).length,
       aspectRatio: opts.aspectRatio,
       imageSize: opts.imageSize,
       seed: opts.seed,
       thinkingLevel: opts.thinkingLevel,
       temperature: opts.temperature,
-      topP: opts.topP,
-      referenceImageCount: opts.image?.length,
-      nonDataUriReferenceCount: opts.image?.filter((source) => !source.trim().startsWith("data:")).length
+      topP: opts.topP
     });
     const suppliedConfig = parseGenerationConfig(opts.config);
     const suppliedResponseFormat = suppliedConfig.responseFormat;
@@ -1893,7 +2080,7 @@ function registerGen(program) {
       path: `/v1beta/models/${encodeURIComponent(opts.model)}:generateContent`,
       apiKey: auth.apiKey,
       body: {
-        contents: [{ role: "user", parts: [{ text: promptParts.join(" ") }, ...(opts.image ?? []).map(geminiImagePart)] }],
+        contents: [{ role: "user", parts: [{ text: promptParts.join(" ") }, ...geminiReferenceImages.map(geminiImagePart)] }],
         ...opts.system ? { systemInstruction: { parts: [{ text: opts.system }] } } : {},
         generationConfig
       },
@@ -1958,7 +2145,7 @@ function registerGen(program) {
       if (res.id) info(`\u4EA4\u4E92 ID\uFF1A${res.id}`);
     }
   });
-  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF1B--duration \u4E3A\u540C\u4E49\u522B\u540D\u3002\u7CBE\u786E\u8303\u56F4\u8FD0\u884C focalapi models get <model> \u67E5\u770B", (v) => Number.parseInt(v, 10)).option("--duration <n>", "\u65F6\u957F\u79D2\u6570\uFF08--seconds \u7684\u522B\u540D\uFF0C\u4E0E API \u5951\u7EA6\u5B57\u6BB5\u540C\u540D\uFF09", (v) => Number.parseInt(v, 10)).option("--size <size>", "\u5206\u8FA8\u7387\uFF0C\u5982 1280x720").option("--resolution <resolution>", "\u539F\u751F\u8F93\u51FA\u5206\u8FA8\u7387\uFF0C\u5982 480p\u3001720p\u30011080p\u30014k").option("--ratio <ratio>", "\u539F\u751F\u5BBD\u9AD8\u6BD4\uFF0C\u5982 16:9\u30019:16\u3001adaptive").option("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9\u30019:16\u3001auto").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--fps <n>", "\u8F93\u51FA\u5E27\u7387\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-tolerance <n>", "\u5B89\u5168\u5BB9\u5FCD\u5EA6\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--image <url...>", "\u53C2\u8003\u56FE URL\uFF08Grok \u89C6\u9891\u4E3A reference-to-video \u6A21\u5F0F\uFF0C\u53EF\u591A\u4E2A\uFF09").option("--first-frame <url>", "\u56FE\u751F\u89C6\u9891\u9996\u5E27\u56FE URL\uFF08image-to-video \u6A21\u5F0F\uFF1B\u4E0E --image \u4E92\u65A5\uFF09").option("--generate-audio <boolean>", "\u662F\u5426\u751F\u6210\u97F3\u9891\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "generate-audio")).option("--watermark <boolean>", "\u662F\u5426\u6DFB\u52A0\u6C34\u5370\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "watermark")).option("--service-tier <tier>", "\u670D\u52A1\u5C42\u7EA7\uFF08Seedance 2.0 \u9ED8\u8BA4 default\uFF09").option("--priority <n>", "\u4EFB\u52A1\u4F18\u5148\u7EA7\uFF08\u4EC5 Seedance 2.0 \u7CFB\u5217\uFF09", (v) => Number.parseInt(v, 10)).option("--callback-url <url>", "\u4EFB\u52A1\u5B8C\u6210\u56DE\u8C03 URL").option("--return-last-frame <boolean>", "\u662F\u5426\u8FD4\u56DE\u6700\u540E\u4E00\u5E27\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "return-last-frame")).option("--execution-expires-after <seconds>", "\u4EFB\u52A1\u8FC7\u671F\u79D2\u6570\uFF083600\u2013259200\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-identifier <identifier>", "Seedance \u5B89\u5168\u6807\u8BC6\u7B26\uFF081\u201364 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF09").option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u5B8C\u6210").option("--poll-interval <ms>", "\u8F6E\u8BE2\u95F4\u9694\u6BEB\u79D2", (v) => Number.parseInt(v, 10), 5e3).option("--timeout <minutes>", "\u6700\u957F\u7B49\u5F85\u5206\u949F", (v) => Number.parseInt(v, 10), 30).option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--content <json>", "Ark-compatible content JSON array; overrides prompt/image facade fields").action(
+  gen.command("video").description("\u751F\u6210\u89C6\u9891\uFF08\u7701\u7565 --model \u65F6\u81EA\u52A8\u9009\u62E9\u5F53\u524D\u53EF\u7528\u9ED8\u8BA4\u6A21\u578B\uFF09").argument("<prompt...>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u89C6\u9891\u6A21\u578B ID\uFF1B\u7701\u7565\u65F6\u7531 focalapi \u81EA\u52A8\u9009\u62E9").option("--seconds <n>", "\u65F6\u957F\u79D2\u6570\uFF1B--duration \u4E3A\u540C\u4E49\u522B\u540D\u3002\u7CBE\u786E\u8303\u56F4\u8FD0\u884C focalapi models get <model> \u67E5\u770B", (v) => Number.parseInt(v, 10)).option("--duration <n>", "\u65F6\u957F\u79D2\u6570\uFF08--seconds \u7684\u522B\u540D\uFF0C\u4E0E API \u5951\u7EA6\u5B57\u6BB5\u540C\u540D\uFF09", (v) => Number.parseInt(v, 10)).option("--size <size>", "\u5206\u8FA8\u7387\uFF0C\u5982 1280x720").option("--resolution <resolution>", "\u539F\u751F\u8F93\u51FA\u5206\u8FA8\u7387\uFF0C\u5982 480p\u3001720p\u30011080p\u30014k").option("--ratio <ratio>", "\u539F\u751F\u5BBD\u9AD8\u6BD4\uFF0C\u5982 16:9\u30019:16\u3001adaptive").option("--aspect-ratio <ratio>", "\u6A21\u578B\u539F\u751F\u753B\u9762\u6BD4\u4F8B\uFF0C\u5982 16:9\u30019:16\u3001auto").option("--seed <n>", "\u6A21\u578B\u968F\u673A\u79CD\u5B50\uFF08\u975E\u8D1F\u6574\u6570\uFF09", (v) => Number.parseInt(v, 10)).option("--fps <n>", "\u8F93\u51FA\u5E27\u7387\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-tolerance <n>", "\u5B89\u5168\u5BB9\u5FCD\u5EA6\uFF08\u4EC5\u652F\u6301\u8BE5\u53C2\u6570\u7684\u6A21\u578B\u751F\u6548\uFF09", (v) => Number.parseInt(v, 10)).option("--image <url...>", "\u53C2\u8003\u56FE URL \u6216\u672C\u5730\u8DEF\u5F84\uFF08@C:/path/x.jpg\uFF09\uFF0CGrok \u89C6\u9891\u4E3A reference-to-video \u6A21\u5F0F").option("--first-frame <url>", "\u56FE\u751F\u89C6\u9891\u9996\u5E27\u56FE URL\uFF08image-to-video \u6A21\u5F0F\uFF1B\u4E0E --image \u4E92\u65A5\uFF09").option("--generate-audio <boolean>", "\u662F\u5426\u751F\u6210\u97F3\u9891\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "generate-audio")).option("--watermark <boolean>", "\u662F\u5426\u6DFB\u52A0\u6C34\u5370\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "watermark")).option("--service-tier <tier>", "\u670D\u52A1\u5C42\u7EA7\uFF08Seedance 2.0 \u9ED8\u8BA4 default\uFF09").option("--priority <n>", "\u4EFB\u52A1\u4F18\u5148\u7EA7\uFF08\u4EC5 Seedance 2.0 \u7CFB\u5217\uFF09", (v) => Number.parseInt(v, 10)).option("--callback-url <url>", "\u4EFB\u52A1\u5B8C\u6210\u56DE\u8C03 URL").option("--return-last-frame <boolean>", "\u662F\u5426\u8FD4\u56DE\u6700\u540E\u4E00\u5E27\uFF08\u53EA\u63A5\u53D7 true \u6216 false\uFF09", (v) => parseBooleanOption(v, "return-last-frame")).option("--execution-expires-after <seconds>", "\u4EFB\u52A1\u8FC7\u671F\u79D2\u6570\uFF083600\u2013259200\uFF09", (v) => Number.parseInt(v, 10)).option("--safety-identifier <identifier>", "Seedance \u5B89\u5168\u6807\u8BC6\u7B26\uFF081\u201364 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF09").option("--no-wait", "\u63D0\u4EA4\u540E\u7ACB\u5373\u8FD4\u56DE task_id\uFF0C\u4E0D\u7B49\u5F85\u5B8C\u6210").option("--idempotency-key <key>", "\u5E42\u7B49\u952E\uFF088\u2013128 \u4E2A\u53EF\u6253\u5370 ASCII \u5B57\u7B26\uFF09\u3002\u540C\u4E00 key \u7684\u91CD\u590D\u63D0\u4EA4\u62FF\u56DE\u539F\u4EFB\u52A1\u800C\u4E0D\u91CD\u590D\u8BA1\u8D39\uFF1B\u7701\u7565\u65F6\u81EA\u52A8\u751F\u6210\u3002\u91CD\u8BD5\u4E0D\u786E\u5B9A\u7684\u63D0\u4EA4\u65F6\u52A1\u5FC5\u590D\u7528\u539F key").option("--poll-interval <ms>", "\u8F6E\u8BE2\u95F4\u9694\u6BEB\u79D2", (v) => Number.parseInt(v, 10), 5e3).option("--timeout <minutes>", "\u6700\u957F\u7B49\u5F85\u5206\u949F", (v) => Number.parseInt(v, 10), 30).option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", DEFAULT_OUT_DIR).option("--content <json>", "Ark content JSON \u6570\u7EC4\uFF1B\u652F\u6301\u5185\u8054 JSON\u3001@\u6587\u4EF6\u8DEF\u5F84\uFF08\u591A\u56FE base64 \u5FC5\u987B\u8D70\u6587\u4EF6\uFF09\u6216 - \uFF08stdin\uFF09\uFF1B\u8986\u76D6 prompt/image \u95E8\u9762\u5B57\u6BB5").action(
     async (promptParts, opts, cmd) => {
       const g = cmd.optsWithGlobals();
       const auth = resolveAuth(g);
@@ -1975,8 +2162,10 @@ function registerGen(program) {
         body.duration = secondsValue;
       }
       if (opts.size) body.size = opts.size;
-      if (opts.image) body.images = opts.image;
-      if (opts.firstFrame) body.image = opts.firstFrame;
+      const videoReferenceImages = await resolveMediaInputs(opts.image ?? []);
+      const firstFrameImage = (await resolveMediaInputs(opts.firstFrame ? [opts.firstFrame] : []))[0];
+      if (videoReferenceImages.length > 0) body.images = videoReferenceImages;
+      if (firstFrameImage) body.image = firstFrameImage;
       if (opts.resolution) metadata.resolution = opts.resolution.toLowerCase();
       if (opts.ratio) metadata.ratio = opts.ratio;
       if (opts.aspectRatio) metadata.ratio = opts.aspectRatio;
@@ -1991,8 +2180,9 @@ function registerGen(program) {
       if (opts.returnLastFrame !== void 0) metadata.return_last_frame = opts.returnLastFrame;
       if (opts.executionExpiresAfter !== void 0) metadata.execution_expires_after = opts.executionExpiresAfter;
       if (opts.safetyIdentifier) metadata.safety_identifier = opts.safetyIdentifier;
-      if (opts.content) metadata.content = parseJsonArray(opts.content, "content");
+      if (opts.content) metadata.content = parseJsonArray(await readContentArgument(opts.content), "content");
       validateVideoGeneration(model, {
+        promptRunes: [...promptParts.join(" ")].length,
         seconds,
         resolution: opts.resolution,
         ratio: opts.ratio,
@@ -2004,17 +2194,20 @@ function registerGen(program) {
         priority: opts.priority,
         executionExpiresAfter: opts.executionExpiresAfter,
         safetyIdentifier: opts.safetyIdentifier,
-        imageCount: opts.image?.length,
-        firstFrameCount: opts.firstFrame ? 1 : 0,
+        imageCount: videoReferenceImages.length,
+        firstFrameCount: firstFrameImage ? 1 : 0,
         generateAudio: opts.generateAudio,
         watermark: opts.watermark
       });
       if (Object.keys(metadata).length > 0) body.metadata = metadata;
+      const idempotencyKey = resolveIdempotencyKey(opts.idempotencyKey);
+      warnDoubleEncodedReferenceURLs("--image/--first-frame", [...videoReferenceImages, firstFrameImage]);
       const created = await withProgress("\u6B63\u5728\u63D0\u4EA4\u89C6\u9891\u4EFB\u52A1", () => request({
         baseUrl: auth.baseUrl,
         path: "/v1/video/generations",
         apiKey: auth.apiKey,
         body,
+        headers: { "Idempotency-Key": idempotencyKey },
         timeoutMs: 12e4
       }));
       const taskId = extractTaskId(created);
@@ -2023,8 +2216,10 @@ function registerGen(program) {
       }
       if (opts.wait === false) {
         info(`task_id=${taskId}`);
+        info(`idempotency_key=${idempotencyKey}`);
+        if (created.idempotent_replay) info("\u5DF2\u56DE\u653E\u539F\u4EFB\u52A1\uFF08idempotent_replay\uFF0C\u672A\u91CD\u590D\u8BA1\u8D39\uFF09");
         if (g.json) {
-          printJson({ model, task_id: taskId, submitted: true, next_command: `focalapi task status ${taskId} --json` });
+          printJson({ model, task_id: taskId, submitted: true, ...created.idempotent_replay ? { idempotent_replay: true } : {}, next_command: `focalapi task status ${taskId} --json` });
         } else {
           process.stdout.write(taskId + "\n");
           info(`\u4EFB\u52A1\u5DF2\u63D0\u4EA4\u3002\u7EED\u53D6\uFF1Afocalapi task status ${taskId} / focalapi task download ${taskId}\uFF1B\u6392\u961F\u4E2D\u53EF\u53D6\u6D88\uFF1Afocalapi task cancel ${taskId}`);
@@ -2052,42 +2247,102 @@ function registerGen(program) {
 }
 
 // src/commands/task.ts
-var TASK_ID_HINT = "task_id \u533A\u5206\u5927\u5C0F\u5199\u4E14\u6DF7\u6709\u5C0F\u5199 l / \u6570\u5B57 1 / \u5927\u5199 I\uFF08O \u4E0E 0 \u540C\u7406\uFF09\uFF0C\u5FC5\u987B\u9010\u5B57\u590D\u5236\u3002\u82E5\u63D0\u4EA4\u65F6\u7684\u8F93\u51FA\u5DF2\u4E22\u5931\uFF0C\u5148\u56DE\u67E5\u5F53\u65F6\u7684 stderr \u9762\u5305\u5C51\uFF08task_id=...\uFF09\uFF0C\u4E0D\u8981\u76F2\u76EE\u91CD\u65B0\u63D0\u4EA4\u2014\u2014\u91CD\u590D\u63D0\u4EA4\u4F1A\u91CD\u590D\u6263\u8D39\u3002";
+var TASK_ID_HINT = "task_id \u533A\u5206\u5927\u5C0F\u5199\u4E14\u6DF7\u6709\u5C0F\u5199 l / \u6570\u5B57 1 / \u5927\u5199 I\uFF08O \u4E0E 0 \u540C\u7406\uFF09\uFF0C\u5FC5\u987B\u9010\u5B57\u590D\u5236\u3002\u82E5\u63D0\u4EA4\u65F6\u7684\u8F93\u51FA\u5DF2\u4E22\u5931\uFF0C\u5148\u8FD0\u884C focalapi task list \u627E\u56DE\u6700\u8FD1\u7684\u4EFB\u52A1\uFF0C\u4E0D\u8981\u76F2\u76EE\u91CD\u65B0\u63D0\u4EA4\u2014\u2014\u91CD\u590D\u63D0\u4EA4\u4F1A\u91CD\u590D\u6263\u8D39\u3002";
 function withTaskIdHint(err) {
   if (err instanceof ApiError && err.status === 404) {
     return new ApiError(err.code, err.message, { status: err.status, hint: TASK_ID_HINT, body: err.body, upstreamCode: err.upstreamCode, requestId: err.requestId });
   }
   return err;
 }
+function formatElapsed(seconds) {
+  if (!seconds || seconds < 0) return "-";
+  if (seconds < 90) return `${seconds} \u79D2`;
+  return `${Math.floor(seconds / 60)} \u5206 ${seconds % 60} \u79D2`;
+}
+function taskAgeSeconds(createdAt) {
+  if (!createdAt) return void 0;
+  return Math.max(0, Math.floor(Date.now() / 1e3 - createdAt));
+}
 function registerTask(program) {
   const task = program.command("task").description("\u4EFB\u52A1\u67E5\u8BE2\u3001\u53D6\u6D88\u4E0E\u4EA7\u7269\u4E0B\u8F7D\uFF08\u89C6\u9891\u7B49\u4EFB\u52A1\u5236\u80FD\u529B\uFF09");
-  task.command("status").description("\u67E5\u8BE2\u4EFB\u52A1\u72B6\u6001").argument("<task_id>", "\u4EFB\u52A1 ID").action(async (taskId, _opts, cmd) => {
+  task.command("status").description("\u67E5\u8BE2\u4EFB\u52A1\u72B6\u6001\uFF1B--wait \u5185\u7F6E\u8F6E\u8BE2\u7B49\u5F85\u7EC8\u6001\uFF0C\u65E0\u9700\u81EA\u5199\u8F6E\u8BE2\u811A\u672C").argument("<task_id>", "\u4EFB\u52A1 ID").option("--wait", "\u7B49\u5F85\u4EFB\u52A1\u5230\u8FBE\u7EC8\u6001\uFF08\u6210\u529F / \u5931\u8D25 / \u53D6\u6D88\uFF09\u540E\u518D\u8FD4\u56DE").option("--timeout <minutes>", "--wait \u7684\u6700\u957F\u7B49\u5F85\u5206\u949F", (v) => Number.parseInt(v, 10), 30).option("--poll-interval <ms>", "--wait \u7684\u8F6E\u8BE2\u95F4\u9694\u6BEB\u79D2", (v) => Number.parseInt(v, 10), 5e3).option("--download", "--wait \u6210\u529F\u540E\u81EA\u52A8\u4E0B\u8F7D\u4EA7\u7269\uFF08\u7B49\u4EF7\u4E8E\u63A5\u7740\u6267\u884C task download\uFF09").option("-o, --out <dir>", "--download \u7684\u8F93\u51FA\u76EE\u5F55", "focalapi-out").action(async (taskId, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
     try {
-      const info_ = await fetchTask(auth.baseUrl, auth.apiKey, taskId);
+      let info_ = await fetchTask(auth.baseUrl, auth.apiKey, taskId);
+      if (opts.wait && info_.status !== "success" && info_.status !== "failed" && info_.status !== "cancelled") {
+        info_ = await pollTask(auth.baseUrl, auth.apiKey, taskId, {
+          intervalMs: opts.pollInterval,
+          timeoutMs: opts.timeout * 6e4,
+          onUpdate: (t) => {
+            if (!g.json) {
+              const elapsed2 = formatElapsed(taskAgeSeconds(t.createdAt));
+              info(`  \u72B6\u6001\uFF1A${t.rawStatus || t.status}${t.progress !== void 0 ? `\uFF08${t.progress}%\uFF09` : ""}\uFF0C\u5DF2\u8017\u65F6 ${elapsed2}`);
+            }
+          }
+        });
+      }
+      const elapsed = taskAgeSeconds(info_.createdAt);
+      let file;
+      if (opts.download && info_.status === "success") {
+        file = (await downloadTaskArtifact(auth.baseUrl, auth.apiKey, taskId, opts.out)).file;
+      }
       if (g.json) {
-        printJson({ task_id: taskId, status: info_.status, raw_status: info_.rawStatus, progress: info_.progress, raw: info_.raw });
+        printJson({
+          task_id: taskId,
+          status: info_.status,
+          raw_status: info_.rawStatus,
+          progress: info_.progress,
+          ...elapsed !== void 0 ? { elapsed_seconds: elapsed } : {},
+          ...file ? { file } : {},
+          raw: info_.raw
+        });
       } else {
         printTable(
           ["\u5B57\u6BB5", "\u503C"],
           [
             ["\u4EFB\u52A1 ID", taskId],
             ["\u72B6\u6001", `${info_.status}${info_.rawStatus && info_.rawStatus !== info_.status ? `\uFF08\u4E0A\u6E38\uFF1A${info_.rawStatus}\uFF09` : ""}`],
-            ["\u8FDB\u5EA6", info_.progress !== void 0 ? `${info_.progress}%` : "-"]
+            ["\u8FDB\u5EA6", info_.progress !== void 0 ? `${info_.progress}%` : "-"],
+            ["\u5DF2\u8017\u65F6", formatElapsed(elapsed)]
           ]
         );
-        if (info_.status === "success") {
+        if (file) {
+          info(`\u2713 ${file}`);
+        } else if (info_.status === "success") {
           info(`\u4EA7\u7269\u4E0B\u8F7D\uFF1Afocalapi task download ${taskId}`);
         }
         if (info_.status === "pending" || info_.status === "running") {
-          info(`\u5982\u9700\u505C\u6B62\u6392\u961F\u4E2D\u7684\u4EFB\u52A1\uFF1Afocalapi task cancel ${taskId}`);
+          info(`\u7B49\u5F85\u5B8C\u6210\uFF1Afocalapi task status ${taskId} --wait\uFF1B\u6392\u961F\u4E2D\u53EF\u53D6\u6D88\uFF1Afocalapi task cancel ${taskId}`);
         }
       }
     } catch (err) {
       throw withTaskIdHint(err);
     }
   });
+  task.command("list").description("\u5217\u51FA\u5F53\u524D Key \u7684\u8FD1\u671F\u4EFB\u52A1\uFF08\u63D0\u4EA4\u8F93\u51FA\u4E22\u5931\u65F6\u7528\u5B83\u627E\u56DE task_id\uFF09").option("--status <status>", "\u6309\u72B6\u6001\u8FC7\u6EE4\uFF1Aqueued\u3001in_progress\u3001completed\u3001failed\u3001cancelled").option("--action <action>", "\u6309\u4EFB\u52A1\u7C7B\u578B\u8FC7\u6EE4\uFF0C\u5982 generate\u3001image_generation").option("--limit <n>", "\u6BCF\u9875\u6570\u91CF\uFF081\u2013100\uFF09", (v) => Number.parseInt(v, 10), 20).option("--offset <n>", "\u504F\u79FB\u91CF", (v) => Number.parseInt(v, 10), 0).action(async (opts, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const auth = resolveAuth(g);
+    const items = await listTasks(auth.baseUrl, auth.apiKey, opts);
+    if (g.json) {
+      printJson({ object: "list", data: items });
+    } else if (items.length === 0) {
+      info("\u5F53\u524D Key \u6682\u65E0\u4EFB\u52A1\u8BB0\u5F55\u3002");
+    } else {
+      printTable(
+        ["\u4EFB\u52A1 ID", "\u6A21\u578B", "\u72B6\u6001", "\u8FDB\u5EA6", "\u5DF2\u8017\u65F6", "\u989D\u5EA6"],
+        items.map((item) => [
+          item.task_id,
+          item.model ?? "-",
+          item.status ?? "-",
+          item.progress !== void 0 ? `${item.progress}%` : "-",
+          formatElapsed(item.created_at ? Math.max(0, Math.floor(Date.now() / 1e3 - item.created_at)) : void 0),
+          item.quota !== void 0 ? String(item.quota) : "-"
+        ])
+      );
+      info("\u7EED\u53D6\uFF1Afocalapi task status <task_id> --wait");
+    }
+  });
   task.command("cancel").description("\u53D6\u6D88\u6392\u961F\u4E2D\u7684\u4EFB\u52A1\uFF08\u8FD0\u884C\u4E2D\u7684\u4EFB\u52A1\u4E0D\u53EF\u53D6\u6D88\uFF1B\u53D6\u6D88\u540E\u8D39\u7528\u81EA\u52A8\u9000\u8FD8\uFF09").argument("<task_id>", "\u4EFB\u52A1 ID").action(async (taskId, _opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
@@ -2098,14 +2353,14 @@ function registerTask(program) {
       info(`\u2713 \u4EFB\u52A1 ${taskId} \u5DF2\u53D6\u6D88`);
     }
   });
-  task.command("download").description("\u4E0B\u8F7D\u4EFB\u52A1\u4EA7\u7269\uFF08\u7ECF focalapi \u5185\u5BB9\u4EE3\u7406\uFF0C\u65E0\u9700\u4E0A\u6E38\u7B7E\u540D URL\uFF09").argument("<task_id>", "\u4EFB\u52A1 ID").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", "focalapi-out").action(async (taskId, opts, cmd) => {
+  task.command("download").description("\u4E0B\u8F7D\u4EFB\u52A1\u4EA7\u7269\uFF08\u9ED8\u8BA4\u7ECF focalapi \u5185\u5BB9\u4EE3\u7406\uFF1B--direct \u4F18\u5148\u76F4\u8FDE\u4EA7\u7269 URL\uFF0C\u5931\u8D25\u81EA\u52A8\u56DE\u9000\u4EE3\u7406\uFF09").argument("<task_id>", "\u4EFB\u52A1 ID").option("-o, --out <dir>", "\u8F93\u51FA\u76EE\u5F55", "focalapi-out").option("--direct", "\u4F18\u5148\u76F4\u8FDE\u4EFB\u52A1\u7684\u4EA7\u7269 URL \u4E0B\u8F7D\uFF08\u8DE8\u5883\u94FE\u8DEF\u4E0B\u901A\u5E38\u663E\u8457\u5FEB\u4E8E\u4EE3\u7406\uFF09\uFF0C\u5931\u8D25\u81EA\u52A8\u56DE\u9000").action(async (taskId, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
-    const filePath = await downloadTaskContent(auth.baseUrl, auth.apiKey, taskId, opts.out);
+    const { file: filePath, source } = await downloadTaskArtifact(auth.baseUrl, auth.apiKey, taskId, opts.out, { direct: opts.direct });
     if (g.json) {
-      printJson({ task_id: taskId, file: filePath });
+      printJson({ task_id: taskId, file: filePath, files: [filePath], source });
     } else {
-      info(`\u2713 ${filePath}`);
+      info(`\u2713 ${filePath}${source === "upstream" ? "\uFF08\u76F4\u8FDE\u4EA7\u7269 URL\uFF09" : ""}`);
     }
   });
 }
@@ -2210,7 +2465,7 @@ function registerUsage(program) {
 }
 
 // src/commands/connect.ts
-import { createHash, randomUUID } from "crypto";
+import { createHash, randomUUID as randomUUID2 } from "crypto";
 import {
   cpSync,
   existsSync as existsSync2,
@@ -2369,7 +2624,7 @@ function installTo(skillsDir, agents, skills, srcDir) {
   }
   mkdirSync2(skillsDir, { recursive: true });
   const oldManifest = readManifest(skillsDir);
-  const transactionRoot = join4(skillsDir, `.focalapi-install-${randomUUID()}`);
+  const transactionRoot = join4(skillsDir, `.focalapi-install-${randomUUID2()}`);
   const stageRoot = join4(transactionRoot, "stage");
   const backupRoot = join4(transactionRoot, "backup");
   mkdirSync2(stageRoot, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focalapi-cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "让任意 AI Agent 直接调用 focalapi 创作模型的命令行工具",
   "type": "module",
   "bin": {

package/skills/focalapi/SKILL.md

@@ -26,8 +26,8 @@ focalapi gen image "<user prompt>" -o ./focalapi-out --json
 focalapi gen video "<user prompt>" --no-wait -o ./focalapi-out --json
 
 # Continue an asynchronous video task.
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task status <task-id> --wait --json    # built-in polling; never write your own poll script
+focalapi task list --json                       # recover recent task IDs after a lost output
 focalapi task cancel <task-id> --json   # queued tasks only; cancelled tasks are refunded
 ```
 
@@ -38,7 +38,7 @@ focalapi task cancel <task-id> --json   # queued tasks only; cancelled tasks are
 | Generate or edit images; create from reference images | `focalapi gen image` | focalapi-gen |
 | Generate video; animate images or reference media | `focalapi gen video` | focalapi-gen |
 | Select, compare, or inspect model parameters | `focalapi models resolve/get/search` | focalapi-models |
-| Inspect progress or failures; cancel queued tasks; download results | `focalapi task status/cancel/download` | focalapi-task |
+| Inspect progress or failures; wait, list, cancel queued tasks; download results | `focalapi task status/wait/list/cancel/download` | focalapi-task |
 | Resolve key, sign-in, or 401 issues | `focalapi auth status/login` | focalapi-auth |
 | Inspect quota, usage, or service failures | `focalapi usage/doctor` | focalapi-usage |
 | Provide text assistance explicitly requested by the user | `focalapi chat` | focalapi-chat |

package/skills/focalapi-gen/SKILL.md

@@ -31,7 +31,7 @@ focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./fo
 focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
 ```
 
-- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
+- Use `--image <url...>` for image editing and reference images. Local files work directly with the `@` prefix (`--image @C:/path/ref.jpg`, inlined as a data URI; per-file ≤8MB, per-command ≤12MB — larger sets must be hosted as URLs first). Pass `--mask` only when the contract lists it.
 - Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
 - For video inputs, `--image <url...>` means reference images (Grok 1.5 reference-to-video, capped at 720p and 7 images) and `--first-frame <url>` means image-to-video from a single starting frame. The two flags are mutually exclusive and both are validated against the live contract before submission.
 - Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.

package/skills/focalapi-task/SKILL.md

@@ -13,8 +13,10 @@ metadata:
 After a generation command returns `task_id`, prefer the response's `next_command`:
 
 ```bash
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
+focalapi task status <task-id> --json          # one-shot status check
+focalapi task status <task-id> --wait          # built-in polling until a terminal state — do not write your own poller
+focalapi task status <task-id> --wait --download -o ./focalapi-out --json
+focalapi task list --status in_progress --json # reconcile recent tasks after losing a submission output
 focalapi task cancel <task-id> --json
 ```
 
@@ -24,7 +26,9 @@ focalapi task cancel <task-id> --json
 - `cancelled`: the task was stopped; a cancelled queued task is refunded. Do not download or resubmit unless the user asks for a new attempt.
 - `unknown`: preserve the raw response and run `focalapi doctor --json`; never fabricate a success state.
 
-Task IDs are case-sensitive and mix `l`/`1`/`I` and `O`/`0`. Copy them exactly from the submission output — stdout JSON or the stderr `task_id=` breadcrumb — instead of retyping.
+Task IDs are case-sensitive and mix `l`/`1`/`I` and `O`/`0`. Copy them exactly from the submission output — stdout JSON or the stderr `task_id=` breadcrumb — instead of retyping. If a submission output is lost entirely, run `task list` to recover recent task IDs before considering any resubmission.
+
+Generation commands print the submission's `idempotency_key=` on stderr. When retrying a submission whose outcome is uncertain (timeout, crash, lost output), reuse that same key via `--idempotency-key` so the retry replays the original task instead of double-charging; a fresh key means a deliberate new generation.
 
 `task cancel` only works while a task is still queued (`pending`). A 409 `task_already_running` means generation already started and cannot be stopped — keep tracking with `task status`. Cancellation failures return explicit codes (`task_already_finished`, `task_cancel_failed`); follow `error.hint` instead of retrying blindly.