focalapi-cli 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.1 - 2026-08-26
+
+- Added `@file` support to `--style-references` and `--moodboards`: the JSON array can now be read from a file instead of inline argv. Windows `cmd` mangles embedded double quotes in JSON arguments (matrix-run evidence 2026-08-25), and the file source sidesteps shell quoting entirely.
+
+## 0.5.0 - 2026-08-25
+
+- Fixed `krea-2-medium/-turbo/large` reference-image validation: the local table said 0 while the platform contract accepts up to 10 reference images (each maps to a Krea style reference), so every `gen image --image` edit was rejected locally without reaching the server (2026-08-25 live audit P01).
+- Added local constraints for the August image wave so invalid parameters are intercepted before submission: `topaz-image-reimagine`/`-bloom-2`/`-wonder-3-5`, `wavespeed-seedvr2-upscale`/`-ultimate-upscale`, `quiver-text-to-svg`/`-image-to-svg`, `hitpaw-image-enhance`/`-portrait-enhance`, `beeble-switchx-image-720p`/`-1080p`, `recraft-v4`/`-v4-pro`.
+- Enforce the exact-one-input-image requirement locally for the enhance/upscale/vectorize/switch families instead of surfacing the server 400.
+- Map `--resolution` to the `target_resolution` wire field for WaveSpeed upscales (the generic `resolution` field is silently ignored by that family).
+- Send Topaz `--creativity` as an integer 1-9 (the platform contract takes a number; the Krea string modes are unchanged).
+- Validate Recraft sizes against the official V4 tables (non-pro caps at ~1.5K, pro at ~3K) and reject reference images locally (the channel is text-to-image only).
+- Intercept `gen image` on Gemini image models with a direct pointer to `gen gemini-image` (native generateContent endpoint) instead of an opaque upstream failure (audit P07).
+
 ## 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.

package/dist/cli.js

@@ -176,7 +176,7 @@ function displayWidth(s) {
 }
 
 // src/lib/version.ts
-var VERSION = true ? "0.4.1" : "0.0.0-dev";
+var VERSION = true ? "0.5.1" : "0.0.0-dev";
 
 // src/commands/auth.ts
 import { createInterface } from "readline/promises";
@@ -1050,7 +1050,7 @@ var IMAGE_CONSTRAINTS = {
   },
   "krea-2-medium": {
     maxN: 1,
-    maxReferenceImages: 0,
+    maxReferenceImages: 10,
     aspectRatios: KREA_IMAGE_ASPECT_RATIOS,
     resolutions: ["1k"],
     supportsSeed: true,
@@ -1061,7 +1061,7 @@ var IMAGE_CONSTRAINTS = {
   },
   "krea-2-medium-turbo": {
     maxN: 1,
-    maxReferenceImages: 0,
+    maxReferenceImages: 10,
     aspectRatios: KREA_IMAGE_ASPECT_RATIOS,
     resolutions: ["1k"],
     supportsSeed: true,
@@ -1072,7 +1072,7 @@ var IMAGE_CONSTRAINTS = {
   },
   "krea-2-large": {
     maxN: 1,
-    maxReferenceImages: 0,
+    maxReferenceImages: 10,
     aspectRatios: KREA_IMAGE_ASPECT_RATIOS,
     resolutions: ["1k"],
     supportsSeed: true,
@@ -1106,8 +1106,112 @@ var IMAGE_CONSTRAINTS = {
     supportsNegativePrompt: true,
     supportsPromptExtend: true,
     supportsWatermark: true
+  },
+  "topaz-image-reimagine": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1,
+    integerCreativity: [1, 9]
+  },
+  "topaz-image-bloom-2": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1
+  },
+  "topaz-image-wonder-3-5": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1
+  },
+  "wavespeed-seedvr2-upscale": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1,
+    resolutions: ["2k", "4k", "8k"],
+    resolutionParam: "target_resolution"
+  },
+  "wavespeed-ultimate-upscale": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1,
+    resolutions: ["2k", "4k", "8k"],
+    resolutionParam: "target_resolution"
+  },
+  "quiver-text-to-svg": {
+    maxN: 1,
+    maxReferenceImages: 4
+  },
+  "quiver-image-to-svg": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1
+  },
+  "hitpaw-image-enhance": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1
+  },
+  "hitpaw-image-portrait-enhance": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 1
+  },
+  "beeble-switchx-image-720p": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 2
+  },
+  "beeble-switchx-image-1080p": {
+    maxN: 1,
+    minImageCount: 1,
+    maxReferenceImages: 2
+  },
+  "recraft-v4": {
+    defaultSize: "1024x1024",
+    maxN: 6,
+    maxReferenceImages: 0,
+    allowedSizes: [
+      "1024x1024",
+      "1280x832",
+      "832x1280",
+      "1216x896",
+      "896x1216",
+      "1152x896",
+      "896x1152",
+      "1536x768",
+      "768x1536",
+      "1344x768",
+      "768x1344",
+      "832x1344",
+      "1280x896",
+      "896x1280"
+    ]
+  },
+  "recraft-v4-pro": {
+    defaultSize: "2048x2048",
+    maxN: 6,
+    maxReferenceImages: 0,
+    allowedSizes: [
+      "2048x2048",
+      "2560x1664",
+      "1664x2560",
+      "2432x1792",
+      "1792x2432",
+      "2304x1792",
+      "1792x2304",
+      "3072x1536",
+      "1536x3072",
+      "2688x1536",
+      "1536x2688",
+      "1664x2688",
+      "2560x1792",
+      "1792x2560"
+    ]
   }
 };
+function getImageConstraint(model) {
+  return IMAGE_CONSTRAINTS[model.trim()];
+}
 var SEEDANCE_RATIOS = ["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"];
 var GROK_VIDEO_ASPECT_RATIOS = ["auto", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16"];
 var KLING_VIDEO_ASPECT_RATIOS = ["16:9", "9:16", "1:1"];
@@ -1285,11 +1389,18 @@ function validateImageGeneration(model, input) {
   if (input.responseFormat && input.responseFormat !== "url" && input.responseFormat !== "b64_json") {
     throw new ApiError("invalid_request", `response_format must be url or b64_json (received: ${input.responseFormat})`);
   }
-  const constraint = IMAGE_CONSTRAINTS[model.trim()];
+  const trimmedModel = model.trim();
+  if (GEMINI_IMAGE_CONSTRAINTS[trimmedModel]) {
+    throw new ApiError("invalid_request", `${model} is a Gemini image model; use \`focalapi gen gemini-image\` (native generateContent endpoint) instead of \`gen image\``);
+  }
+  const constraint = IMAGE_CONSTRAINTS[trimmedModel];
   if (!constraint) return;
   if (input.n < 1 || input.n > constraint.maxN) {
     throw new ApiError("invalid_request", `${model} n must be 1-${constraint.maxN} (received: ${input.n})`);
   }
+  if (input.imageCount !== void 0 && constraint.minImageCount !== void 0 && input.imageCount < constraint.minImageCount) {
+    throw new ApiError("invalid_request", `${model} requires at least ${constraint.minImageCount} input image${constraint.minImageCount === 1 ? "" : "s"}`);
+  }
   if (input.imageCount !== void 0 && constraint.maxReferenceImages !== void 0 && input.imageCount > constraint.maxReferenceImages) {
     throw new ApiError("invalid_request", `${model} supports at most ${constraint.maxReferenceImages} reference images`);
   }
@@ -1305,7 +1416,16 @@ function validateImageGeneration(model, input) {
   validateOptionalChoice(model, "resolution", input.resolution, constraint.resolutions);
   validateOptionalChoice(model, "output_format", input.outputFormat, constraint.outputFormats);
   validateOptionalChoice(model, "optimize_prompt", input.optimizePrompt, constraint.optimizePromptModes);
-  validateOptionalChoice(model, "creativity", input.creativity, constraint.creativityModes);
+  if (!constraint.integerCreativity) {
+    validateOptionalChoice(model, "creativity", input.creativity, constraint.creativityModes);
+  }
+  if (input.creativity !== void 0 && constraint.integerCreativity) {
+    const [minimum, maximum] = constraint.integerCreativity;
+    const creativity = Number(input.creativity);
+    if (!Number.isInteger(creativity) || creativity < minimum || creativity > maximum) {
+      throw new ApiError("invalid_request", `${model} creativity must be an integer ${minimum}-${maximum} (received: ${input.creativity})`);
+    }
+  }
   if (input.negativePrompt !== void 0 && !constraint.supportsNegativePrompt) {
     throw new ApiError("invalid_request", `${model} does not support negative_prompt`);
   }
@@ -1340,6 +1460,12 @@ function validateImageGeneration(model, input) {
     return;
   }
   const suppliedSize = input.size ?? constraint.defaultSize;
+  if (constraint.allowedSizes) {
+    if (!constraint.allowedSizes.includes(suppliedSize.toLowerCase())) {
+      throw new ApiError("invalid_request", `${model} size must be one of ${constraint.allowedSizes.join(", ")} (received: ${suppliedSize})`);
+    }
+    return;
+  }
   if (constraint.sizeTiers?.includes(suppliedSize.toLowerCase())) return;
   if (constraint.sizeTiers && !/^\d+x\d+$/i.test(suppliedSize)) {
     throw new ApiError("invalid_request", `${model} size must be one of ${constraint.sizeTiers.join(", ")} or WIDTHxHEIGHT (received: ${suppliedSize})`);
@@ -1817,6 +1943,15 @@ function parseJsonArray(raw, option) {
     throw new ApiError("invalid_request", `--${option} must be a JSON array`);
   }
 }
+async function readJsonArrayArgument(raw, option) {
+  if (!raw.startsWith("@")) return parseJsonArray(raw, option);
+  try {
+    return parseJsonArray((await readFile(normalizeHomePath(raw.slice(1)), "utf8")).trim(), option);
+  } catch (error) {
+    if (error instanceof ApiError) throw error;
+    throw new ApiError("invalid_request", `--${option} @file \u65E0\u6CD5\u8BFB\u53D6\uFF1A${raw.slice(1, 120)}`);
+  }
+}
 var MAX_CONTENT_FILE_BYTES = 64 * 1024 * 1024;
 async function readContentArgument(raw) {
   if (raw === "-") {
@@ -1953,8 +2088,8 @@ function registerGen(program) {
     const model = opts.model ?? (await resolveCreativeModel(auth, "image")).model.id;
     if (!opts.model && !g.json) info(`\u5DF2\u81EA\u52A8\u9009\u62E9\u56FE\u50CF\u6A21\u578B\uFF1A${model}`);
     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 styleReferences = opts.styleReferences ? await readJsonArrayArgument(opts.styleReferences, "style-references") : void 0;
+    const moodboards = opts.moodboards ? await readJsonArrayArgument(opts.moodboards, "moodboards") : void 0;
     const referenceImages = await resolveMediaInputs(opts.image ?? []);
     const maskImage = (await resolveMediaInputs(opts.mask ? [opts.mask] : []))[0];
     validateImageGeneration(model, {
@@ -1981,14 +2116,17 @@ function registerGen(program) {
       throw new ApiError("invalid_request", "--response-format b64_json cannot be used with --no-wait; use url");
     }
     const body = { model, prompt: promptParts.join(" "), n };
+    const constraint = getImageConstraint(model);
     if (opts.size) body.size = opts.size;
     if (opts.aspectRatio) body.aspect_ratio = opts.aspectRatio;
-    if (opts.resolution) body.resolution = opts.resolution.toLowerCase();
+    if (opts.resolution) body[constraint?.resolutionParam ?? "resolution"] = opts.resolution.toLowerCase();
     if (opts.seed !== void 0) body.seed = opts.seed;
     if (opts.quality) body.quality = opts.quality;
     if (opts.background) body.background = opts.background;
     if (opts.negativePrompt) body.negative_prompt = opts.negativePrompt;
-    if (opts.creativity) body.creativity = opts.creativity.toLowerCase();
+    if (opts.creativity) {
+      body.creativity = constraint?.integerCreativity ? Number(opts.creativity) : opts.creativity.toLowerCase();
+    }
     if (opts.promptExtend !== void 0) body.prompt_extend = opts.promptExtend;
     if (styleReferences) body.image_style_references = styleReferences;
     if (moodboards) body.moodboards = moodboards;

package/package.json

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