@koda-sl/baker-cli 0.148.0 → 0.149.0

package/README.md

@@ -1643,6 +1643,8 @@ baker images stock "office reaction" --people only
 
 Free tier exists but watermarks previews — pass `--license freemium` to filter to clean free assets explicitly.
 
+An empty result comes back with `hints` naming the filters that narrowed the search plus the fallbacks (`baker images find --sources …`, `baker images generate`); a provider failure returns an `error.fix` pointing at the same exits. `baker images google` does the same, minus the cross-provider fallback (it is the last-resort provider).
+
 **Flags:**
 
 | Flag             | Description                                                                                |
@@ -1724,13 +1726,15 @@ baker images generate "flat geometric mascot, brand palette" \
 | Model | Best for | Aspect ratios | Sizes |
 |---|---|---|---|
 | `google/gemini-3.1-flash-image-preview` **(default)** | Fast iteration, reference editing, extreme aspect ratios (Nano Banana flash) | standard **+** `1:4` `4:1` `1:8` `8:1` | `0.5K`–`4K` |
-| `google/gemini-3.5-flash` | Fast; extreme aspect ratios | standard **+** `1:4` `4:1` `1:8` `8:1` | `0.5K`–`4K` |
 | `google/gemini-3-pro-image-preview` | Highest fidelity (Nano Banana Pro) — strong prompt adherence and reference grounding | standard set | `1K` `2K` `4K` |
-| `openai/gpt-5.4-image-2` | Photoreal + cleanest in-image text — ad/landing reproduction | standard set | `1K` `2K` `4K` |
+| `openai/gpt-image-2` | Photoreal + cleanest in-image text — ad/landing reproduction | standard set **minus** `4:5` `5:4` | *(none — derived from the ratio)* |
+| `openai/gpt-5.4-image-2` | **Legacy** — accepted so canvases authored before the gpt-image-2 switch still re-run. Don't pick it for new work. | standard set | `1K` `2K` `4K` (ignored upstream) |
 | `recraft/recraft-v4.1-pro-vector` | Vector/flat/SVG-style with palette control | standard set | `1K` `2K` `4K` |
 
 Standard aspect ratios: `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`.
 
+`openai/gpt-image-2` accepts neither `image_size` nor the `4:5` / `5:4` portrait ratios — OpenAI picks the pixel dimensions from the ratio. To ship a 4:5 Meta feed ad from it, render the hero at `3:4` and adapt with `image_aspect_adapt`; the scaffolders do this for you.
+
 **Flags:**
 
 | Flag | Description |
@@ -2747,7 +2751,7 @@ A re-run with no changes hits the cache for every node — total runtime drops t
       "type": "text_generate",
       "inputs": { "topic": "$ref:topic.text" },
       "params": {
-        "model": "google/gemini-3.5-flash",
+        "model": "google/gemini-3.1-flash-image-preview",
         "prompt": "Write a 6-word tagline for {{topic}}."
       }
     }
@@ -3046,37 +3050,31 @@ Aspect-ratio sets used below:
 
 ---
 
-###### Model: `openai/gpt-5.4-image-2`
+###### Model: `openai/gpt-image-2`
 
-Photorealistic generalist. Optional `reference` image.
+Photorealistic generalist, and the cleanest at rendering text inside the image. Optional `reference` image (up to 16).
 
 | Name | Type | Required | Notes |
 |---|---|---|---|
-| `model` | literal | yes | `"openai/gpt-5.4-image-2"` |
+| `model` | literal | yes | `"openai/gpt-image-2"` |
 | `prompt` | string | yes | non-empty |
-| `aspect_ratio` | enum | no | STD AR |
-| `image_size` | enum | no | `1K \| 2K \| 4K` |
+| `aspect_ratio` | enum | no | GPT AR = `1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9` — **no `4:5` / `5:4`** |
 | `quality` | enum | no | `auto \| low \| medium \| high` — rendering quality; the scaffolder sets `high` for photoreal frames. (Do **not** pass `input_fidelity`: gpt-image-2 forces high fidelity automatically and the param can fail the request.) |
 
+No `image_size`: OpenAI derives the pixel dimensions from the ratio, so a size is ignored. For a portrait ad format, render at `3:4` and adapt.
+
 ```json
 { "id": "hero", "type": "image_generate",
-  "params": { "model": "openai/gpt-5.4-image-2", "prompt": "Photorealistic photo of …", "aspect_ratio": "16:9", "image_size": "2K", "quality": "high" } }
+  "params": { "model": "openai/gpt-image-2", "prompt": "Photorealistic photo of …", "aspect_ratio": "16:9", "quality": "high" } }
 ```
 
-###### Model: `google/gemini-3.5-flash`
-
-Newest Gemini Flash image model. Always returns an image output. Best for fast iteration; supports extreme aspect ratios and the `0.5K` size for cheap previews.
+###### Model: `openai/gpt-5.4-image-2` (legacy)
 
-| Name | Type | Required | Notes |
-|---|---|---|---|
-| `model` | literal | yes | `"google/gemini-3.5-flash"` |
-| `prompt` | string | yes | non-empty |
-| `aspect_ratio` | enum | no | EXTREME AR |
-| `image_size` | enum | no | `0.5K \| 1K \| 2K \| 4K` |
+Kept only so canvases authored before the gpt-image-2 switch still validate and re-run unchanged — `baker canvas rerun` replays a recorded canvas verbatim. It keeps the full standard ratio set (including `4:5` / `5:4`) and still accepts `image_size`, which the provider ignores. Prefer `openai/gpt-image-2` for anything new.
 
 ###### Model: `google/gemini-3.1-flash-image-preview`
 
-Preview-channel Gemini flash. Same param surface as `3.5-flash`.
+Gemini flash image model — the default. Fast iteration, reference editing, extreme aspect ratios, and the `0.5K` size for cheap previews.
 
 | Name | Type | Required | Notes |
 |---|---|---|---|
@@ -3293,7 +3291,7 @@ There is no `prompt` param — the extraction schema is the node. Use `focus` to
       "params": { "model": "~google/gemini-pro-latest" } },
     { "id": "remix", "type": "image_generate",
       "inputs": { "blueprint": "$ref:blueprint.description" },
-      "params": { "model": "openai/gpt-5.4-image-2",
+      "params": { "model": "openai/gpt-image-2",
                   "prompt": "Recreate an image matching this exact blueprint, but swap the product for a ceramic mug:\n{{blueprint}}" } }
   ],
   "output": { "node": "remix", "output": "images" }
@@ -3374,9 +3372,9 @@ Fail-fast: an invalid model selection (wrong count, duplicate or out-of-range pi
 {
   "schema": "baker-canvas/1",
   "nodes": [
-    { "id": "a", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, warm morning light" } },
-    { "id": "b", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, studio softbox" } },
-    { "id": "c", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, dramatic side light" } },
+    { "id": "a", "type": "image_generate", "params": { "model": "google/gemini-3.1-flash-image-preview", "prompt": "hero shot of a ceramic mug, warm morning light" } },
+    { "id": "b", "type": "image_generate", "params": { "model": "google/gemini-3.1-flash-image-preview", "prompt": "hero shot of a ceramic mug, studio softbox" } },
+    { "id": "c", "type": "image_generate", "params": { "model": "google/gemini-3.1-flash-image-preview", "prompt": "hero shot of a ceramic mug, dramatic side light" } },
     { "id": "best", "type": "image_select",
       "inputs": { "images": ["$ref:a.images#0", "$ref:b.images#0", "$ref:c.images#0"] },
       "params": { "model": "~google/gemini-pro-latest", "prompt": "most premium-feeling lighting, no harsh shadows" } }
@@ -4078,7 +4076,7 @@ baker canvas run ./reference-ad.video.canvas.json
 | `--focus <text>` | — | Known provenance/emphasis to ground the deconstruct. |
 | `--deconstruct-model <id>` | `~google/gemini-pro-latest` | Override the `video_deconstruct` model. |
 | `--select-model <id>` | `~google/gemini-flash-latest` | Override the element-selection `text_generate` model. |
-| `--image-model <id>` | `openai/gpt-5.4-image-2` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
+| `--image-model <id>` | `openai/gpt-image-2` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
 | `--video-model <id>` | scored router | Override the `video_generate` model **and skip the router**. Curated roster: `bytedance/seedance-2.0` (workhorse), `google/veo-3.1` (cine ceiling + real-face), `google/veo-3.1-fast` (cheap Veo), `kwaivgi/kling-v3.0-pro` (motion-transfer). |
 | `--real-face` | auto-detected | Force the Veo route for a photoreal human presenter (dodges the ByteDance real-person filter). **Usually unnecessary** — the scaffold auto-detects a photoreal on-camera person/animal cast from the deconstruct and routes it to Veo on its own; set this only to force it when the cast isn't detected. Covers AI-generated photoreal faces too, not just real ones. |
 | `--motion-transfer` | off | Motion driven from a reference / hyper-dynamic → the router picks Kling. |
@@ -4135,7 +4133,7 @@ baker canvas run ./static-ad.canvas.json
 | `--describe-model <id>` | registry default (`~google/gemini-pro-latest`) | Override the `image_describe` model. |
 | `--select-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the element-selection `text_generate` model. |
 | `--layout-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the global-layout `text_generate` model. |
-| `--gen-model <id>` | registry default (`openai/gpt-5.4-image-2`) | Override the `image_generate` model. |
+| `--gen-model <id>` | registry default (`openai/gpt-image-2`) | Override the `image_generate` model. |
 | `--platform <channel>` | `meta` | `_definition.md` channel **and** the default placement set the hero fans out to (`meta`\|`google`\|`linkedin`\|`tiktok`\|`youtube`\|`x`\|`other`; `x`/`other` fan out to nothing). |
 | `--placements <preset\|none>` | derived from `--platform` | Override the fan-out set: `meta_feed`\|`meta_feed_stories`\|`meta_all`\|`linkedin`\|`google_demandgen`\|`tiktok`\|`youtube`, or `none` for a single base ad. |
 | `--aspect <ratio>` | inferred from the image, else `9:16` | Force the hero's aspect ratio (clamped into the placement set so it stays a free pass-through). |

package/dist/{chunk-2F5SCTNS.js → chunk-OO5BDH3J.js}

@@ -1114,6 +1114,7 @@ function normalizeForCanonical(value) {
 // ../canvas-contract/src/registry.ts
 var OPENROUTER_IMAGE_AR = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
 var OPENROUTER_IMAGE_AR_EXTREME = [...OPENROUTER_IMAGE_AR, "1:4", "4:1", "1:8", "8:1"];
+var OPENROUTER_IMAGE_AR_GPT = ["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9", "21:9"];
 var OPENROUTER_IMAGE_SIZE = ["1K", "2K", "4K"];
 var OPENROUTER_IMAGE_SIZE_EXTENDED = ["0.5K", ...OPENROUTER_IMAGE_SIZE];
 var OPENROUTER_IMAGE_QUALITY = ["auto", "low", "medium", "high"];
@@ -1134,8 +1135,8 @@ var REPLICATE_VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"];
 var DECONSTRUCT_VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"];
 var REPLICATE_AUDIO_MIMES = ["audio/wav", "audio/mpeg", "audio/mp3"];
 var IMAGE_GENERATE_MODELS = [
+  "openai/gpt-image-2",
   "openai/gpt-5.4-image-2",
-  "google/gemini-3.5-flash",
   "google/gemini-3.1-flash-image-preview",
   "google/gemini-3-pro-image-preview",
   "recraft/recraft-v4.1-pro-vector"
@@ -1234,28 +1235,37 @@ var MODEL_REGISTRY = {
     // `seed` is omitted on every entry — OpenRouter's `image_config` schema
     // has no `seed` slot for image-gen (different from video-gen), so passing
     // it would be a silent no-op.
-    "openai/gpt-5.4-image-2": {
-      label: "OpenAI GPT-5.4 Image 2",
+    // The direct image model, not the `gpt-5.4-image-2` chat model that emitted
+    // images as a side effect. Notable capability gaps vs the Gemini entries:
+    // no `image_size` (OpenAI picks the pixel dimensions from the ratio, and a
+    // `resolution` is silently ignored) and the narrower `..._AR_GPT` ratio set.
+    "openai/gpt-image-2": {
+      label: "OpenAI GPT Image 2",
       inputs: [],
       optional_inputs: [{ kind: "image", mimes: OPENROUTER_IMAGE_MIMES }],
       required: ["prompt"],
       params: {
         prompt: { kind: "string" },
-        aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR },
-        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE },
+        aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR_GPT },
         quality: { kind: "string", enum: OPENROUTER_IMAGE_QUALITY }
       }
     },
-    "google/gemini-3.5-flash": {
-      // Newer Gemini flash image model. Always returns an image output.
-      label: "Google Gemini 3.5 Flash (Image)",
+    // LEGACY — kept so canvases authored before the gpt-image-2 switch still
+    // validate and re-run unchanged (`baker canvas rerun` restores a recorded
+    // canvas verbatim, so dropping this model would break every stored creative
+    // that used it). Its param surface is the ORIGINAL one on purpose: unlike
+    // gpt-image-2 it still honors 4:5/5:4, and `image_size` is accepted-then-
+    // ignored upstream rather than rejected. Verified live on /api/v1/images.
+    // Don't reach for it in new work — the scaffolders default to gpt-image-2.
+    "openai/gpt-5.4-image-2": {
+      label: "OpenAI GPT-5.4 Image 2 (legacy)",
       inputs: [],
       optional_inputs: [{ kind: "image", mimes: OPENROUTER_IMAGE_MIMES }],
       required: ["prompt"],
       params: {
         prompt: { kind: "string" },
-        aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR_EXTREME },
-        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE_EXTENDED },
+        aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR },
+        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE },
         quality: { kind: "string", enum: OPENROUTER_IMAGE_QUALITY }
       }
     },
@@ -1607,6 +1617,36 @@ var MODEL_REGISTRY = {
     }
   }
 };
+function supportsParam(kind, model, param) {
+  return MODEL_REGISTRY[kind]?.[model]?.params[param] !== void 0;
+}
+function supportedAspectRatios(kind, model) {
+  const schema = MODEL_REGISTRY[kind]?.[model]?.params.aspect_ratio;
+  return schema?.kind === "string" ? schema.enum : void 0;
+}
+function ratioValue(ratio) {
+  const [w, h] = ratio.split(":").map(Number);
+  if (!w || !h || !Number.isFinite(w) || !Number.isFinite(h)) return null;
+  return w / h;
+}
+function nearestSupportedAspectRatio(kind, model, target) {
+  const supported = supportedAspectRatios(kind, model);
+  if (!supported || supported.includes(target)) return target;
+  const wanted = ratioValue(target);
+  if (wanted === null) return target;
+  let best = target;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of supported) {
+    const value = ratioValue(candidate);
+    if (value === null) continue;
+    const distance2 = Math.abs(Math.log(value / wanted));
+    if (distance2 < bestDistance) {
+      bestDistance = distance2;
+      best = candidate;
+    }
+  }
+  return best;
+}
 
 // ../canvas-contract/src/validateParams.ts
 function isManagedNodeKind(nodeType) {
@@ -6991,8 +7031,9 @@ var dialogueNode = delegated({
 // src/engine/nodes/remote/image.ts
 import { z as z17 } from "zod";
 var IMAGE_GENERATE_MODELS2 = [
+  "openai/gpt-image-2",
+  // Legacy — see the registry entry; kept so pre-switch canvases still run.
   "openai/gpt-5.4-image-2",
-  "google/gemini-3.5-flash",
   "google/gemini-3.1-flash-image-preview",
   "google/gemini-3-pro-image-preview",
   "recraft/recraft-v4.1-pro-vector"
@@ -7002,11 +7043,11 @@ var ImageGenerateParams = z17.object({
   prompt: z17.string().min(1),
   aspect_ratio: z17.enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "1:4", "4:1", "1:8", "8:1"]).optional(),
   image_size: z17.enum(["0.5K", "1K", "2K", "4K"]).optional(),
-  // Rendering quality — forwarded into `image_config`. OpenRouter models without a
-  // quality knob ignore it; the registry gates which models accept it (gpt-image, Gemini).
+  // Rendering quality. OpenRouter models without a quality knob ignore it; the
+  // registry gates which models accept it (gpt-image, Gemini).
   quality: z17.enum(["auto", "low", "medium", "high"]).optional(),
-  // Recraft v4 vector controls — forwarded into `image_config`. Registry
-  // rejects them on non-Recraft models.
+  // Recraft v4 vector controls, sent as the provider's own `controls` block.
+  // Registry rejects them on non-Recraft models.
   strength: z17.number().min(0).max(1).optional(),
   rgb_colors: z17.array(z17.array(z17.number().int().min(0).max(255))).optional(),
   background_rgb_color: z17.array(z17.number().int().min(0).max(255)).optional()
@@ -7015,8 +7056,8 @@ var imageGenerateNode = delegated({
   id: "image_generate",
   version: "2.2.0",
   category: "image",
-  summary: "Generate images for ad creatives. Curated model set: GPT-5.4 Image, Gemini 3.5 Flash, Gemini 3.1 Flash Image Preview, Gemini 3 Pro Image, Recraft v4.1 Pro Vector. Per-model param support comes from the canvas-engine model registry.",
-  when_to_use: "Use for hero shots, product photography, illustrations, and vector logos. `recraft/recraft-v4.1-pro-vector` for crisp vector / logo work; `openai/gpt-5.4-image-2` for photorealistic; Gemini variants for fast iteration and editing via the `reference` input. `reference` accepts ONE image or an ARRAY of images \u2014 wire several to combine references in a single generation (e.g. a subject sheet + a font specimen + the original ad). Every reference is forwarded to the model in array order.",
+  summary: "Generate images for ad creatives. Curated model set: GPT Image 2, Gemini 3.1 Flash Image Preview, Gemini 3 Pro Image, Recraft v4.1 Pro Vector. Per-model param support comes from the canvas-engine model registry.",
+  when_to_use: "Use for hero shots, product photography, illustrations, and vector logos. `recraft/recraft-v4.1-pro-vector` for crisp vector / logo work; `openai/gpt-image-2` for photorealistic and in-image text (NOTE: it has no `image_size`, and no 4:5 / 5:4 \u2014 route portrait ad formats through Gemini or `image_aspect_adapt`); Gemini variants for fast iteration, extreme ratios, and editing via the `reference` input. `reference` accepts ONE image or an ARRAY of images \u2014 wire several to combine references in a single generation (e.g. a subject sheet + a font specimen + the original ad). Every reference is forwarded to the model in array order.",
   // `reference` is one image or an ordered array of images. The backend forwards
   // each as a separate `image_url` to the provider (OpenRouter accepts many).
   inputs: z17.object({ reference: z17.union([ImageRef, z17.array(ImageRef).min(1)]).optional() }).loose(),
@@ -7872,6 +7913,8 @@ export {
   IMAGE_GENERATE_MODELS,
   DEFAULT_VIDEO_GENERATE_MODEL,
   MODEL_REGISTRY,
+  supportsParam,
+  nearestSupportedAspectRatio,
   resolveConcurrency,
   ulid,
   isPersistedAssetRef,
@@ -7898,4 +7941,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-2F5SCTNS.js.map
+//# sourceMappingURL=chunk-OO5BDH3J.js.map