@nodaro/shared 2.19.0 → 2.21.0

package/src/model-catalog.ts

@@ -133,6 +133,24 @@ export interface ModelCatalogEntry {
   features?: readonly string[]
   aspectRatios?: readonly string[]
   resolutions?: readonly string[]
+  /**
+   * What this model actually RENDERS for a resolution outside `resolutions`.
+   *
+   * Most providers honour whatever band they are sent, so an off-list value is
+   * best snapped to the NEAREST supported one — a 4k request on a 1080p-max
+   * model renders 1080p. A few instead COLLAPSE anything unrecognised to a
+   * fixed default (MiniMax H3 → 2K, Wan 3.0 → 720p), and for those the nearest
+   * band is the wrong answer in the most expensive direction: snapping a stale
+   * "720p" to H3's cheap 768P would send a value the provider ignores, so we
+   * would bill the 768P tier against a 2K render, and `commit_credits` never
+   * collects the shortfall.
+   *
+   * Declare it in the catalog's own spelling. `normalizeVideoRequestParams`
+   * uses it in place of the nearest-band snap; `video-collapse-parity.test.ts`
+   * pins each declaration to what the provider normalizer actually returns, so
+   * the two cannot drift.
+   */
+  unlistedResolutionRendersAs?: string
   qualities?: readonly string[]
   durations?: readonly number[]
   pricing: readonly PriceVariant[]
@@ -155,6 +173,12 @@ export interface ModelCatalogEntry {
    * Frontend pickers ignore this flag.
    */
   mcpHidden?: boolean
+  /**
+   * The provider's safety filter is known to be non-deterministic on this
+   * model — the platform retries a blocked request once; `fallback` names
+   * the catalog model to offer when it blocks again.
+   */
+  safetyFilter?: { stochastic: true; fallback?: string }
 }
 
 /**
@@ -177,7 +201,7 @@ export const MODEL_RECOMMENDATIONS: readonly ModelRecommendation[] = [
   { intent: "cheapest realistic image", modelIds: ["z-image", "qwen", "imagen4-fast"], note: "Z-Image is the cheapest. Qwen / Imagen4 Fast for slightly higher quality." },
   { intent: "highest fidelity image", modelIds: ["nano-banana-pro", "imagen4-ultra", "flux-flex"], note: "Pick by family preference; all three are premium tiers." },
   { intent: "image edit / restyle", modelIds: ["flux-kontext", "ideogram-remix", "seedream-5-pro-i2i"], note: "Flux Kontext preserves identity; Ideogram Remix is character-aware; Seedream 5 Pro for instruction-based edits (5 Lite is the budget option)." },
-  { intent: "highest-resolution image (4K / 8K)", modelIds: ["topaz-image-upscale", "nano-banana-pro", "gpt-image-2"], note: "Generate at native then Topaz upscale for 8K." },
+  { intent: "highest-resolution image", modelIds: ["topaz-image-upscale", "nano-banana-pro", "gpt-image-2"], note: "Generate at the model's top tier, then Topaz upscale 4x (Topaz's only lever is the 1x/2x/4x factor)." },
   { intent: "background removal / cutout", modelIds: ["recraft-remove-bg"], note: "Cheap, no prompt needed." },
   // video
   { intent: "best cinematic video", modelIds: ["veo3", "kling-3.0", "seedance-2"], note: "VEO 3.1 Quality for premium narrative; Kling 3.0 for music-synced motion; Seedance 2 for reference-driven consistency." },
@@ -545,6 +569,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "gpt-image-2:2K", credits: 30, note: "2K" },
       { identifier: "gpt-image-2:4K", credits: 60, note: "4K" },
     ],
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
   },
   "gpt-image-2-i2i": {
     id: "gpt-image-2-i2i",
@@ -975,14 +1000,15 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     family: "Topaz",
     label: "Topaz Image Upscale",
     series: "Topaz",
-    description: "High-quality image upscale up to 8K. Best for production-ready output.",
+    description: "High-quality image upscale at 1x (enhance only), 2x or 4x. Best for production-ready output.",
     useCases: ["upscale", "high-res", "premium"],
     features: ["reference-image"],
-    resolutions: ["2K", "4K", "8K"],
+    // No `resolutions`: the provider's only quality lever is `upscale_factor`
+    // (1/2/4) — see resolveTopazUpscale. The 2K/4K/8K menu this used to
+    // advertise had no provider parameter behind it.
     pricing: [
-      { identifier: "topaz-image-upscale", credits: 25, note: "2K default" },
-      { identifier: "topaz-image-upscale:4K", credits: 50, note: "4K" },
-      { identifier: "topaz-image-upscale:8K", credits: 100, note: "8K" },
+      { identifier: "topaz-image-upscale", credits: 25, note: "1x / 2x" },
+      { identifier: "topaz-image-upscale:4K", credits: 50, note: "4x (legacy identifier)" },
     ],
   },
 }
@@ -1017,6 +1043,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   // docs.kie.ai/market/minimax-h3/{text,image,reference}-to-video.
   "minimax-h3": {
     id: "minimax-h3",
+    unlistedResolutionRendersAs: "2K",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "MiniMax",
@@ -1505,6 +1532,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   // declared explicitly in PRICING_DEFAULT_RESOLUTION, never by array position.
   "wan-3": {
     id: "wan-3",
+    unlistedResolutionRendersAs: "720p",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "Alibaba",
@@ -1529,6 +1557,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   },
   "wan-3-prime": {
     id: "wan-3-prime",
+    unlistedResolutionRendersAs: "720p",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "Alibaba",
@@ -1697,6 +1726,76 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "wan-2.7-t2v", credits: 188, note: "5s 720p default" },
     ],
   },
+  // Lightricks LTX 2.3 (Replicate, not KIE). Both variants run one endpoint per
+  // variant and switch behaviour with a `task` discriminator, so t2v and i2v are
+  // the SAME id — no VIDEO_MODE_ALIASES row. `extend` / `retake` are separate
+  // priced ops on the same model (ids below) but are NOT listed in `modes`:
+  // they are driven by the Extend Video / Video Retake nodes' own pickers, and
+  // adding the mode here would duplicate LTX in those menus.
+  // Bands are lowercase to match LTX_DURATION_TIERS' keys in credit-identifiers.ts
+  // and QUALITY_MAP in node-default-mappings.ts.
+  "ltx-2.3-pro": {
+    id: "ltx-2.3-pro",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Lightricks",
+    label: "LTX 2.3 Pro",
+    series: "LTX",
+    description: "Lightricks LTX 2.3 Pro — text/image/audio→video up to 4K, 6/8/10s, end-frame interpolation.",
+    useCases: ["premium", "high-res", "narrative"],
+    features: ["end-frame"],
+    aspectRatios: ["16:9", "9:16"] as const,
+    resolutions: ["1080p", "2k", "4k"] as const,
+    durations: [6, 8, 10],
+    pricing: [
+      { identifier: "ltx-2.3-pro", credits: 240, note: "default 1080p 6s" },
+      { identifier: "ltx-2.3-pro:1080p:6s", credits: 240 },
+      { identifier: "ltx-2.3-pro:1080p:8s", credits: 320 },
+      { identifier: "ltx-2.3-pro:1080p:10s", credits: 400 },
+      { identifier: "ltx-2.3-pro:2k:6s", credits: 480 },
+      { identifier: "ltx-2.3-pro:2k:8s", credits: 640 },
+      { identifier: "ltx-2.3-pro:2k:10s", credits: 800 },
+      { identifier: "ltx-2.3-pro:4k:6s", credits: 960 },
+      { identifier: "ltx-2.3-pro:4k:8s", credits: 1280 },
+      { identifier: "ltx-2.3-pro:4k:10s", credits: 1600 },
+      { identifier: "ltx-2.3-pro-extend:per-second", credits: 40, note: "extend, per second of new footage" },
+      { identifier: "ltx-2.3-pro-retake:per-second", credits: 40, note: "retake, per second re-rendered" },
+    ],
+  },
+  "ltx-2.3-fast": {
+    id: "ltx-2.3-fast",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Lightricks",
+    label: "LTX 2.3 Fast",
+    series: "LTX",
+    description: "Lightricks LTX 2.3 Fast — text/image→video up to 20s at 1080p (6/8/10s at 2K and 4K). No audio input, no extend.",
+    useCases: ["long-form", "fast", "narrative"],
+    features: ["end-frame"],
+    aspectRatios: ["16:9", "9:16"] as const,
+    resolutions: ["1080p", "2k", "4k"] as const,
+    // Flat union across bands — 12–20s exist only at 1080p (LTX_DURATION_TIERS
+    // in credit-identifiers.ts is the per-band authority and snaps a 2k/4k
+    // request back onto 6/8/10s, so the reservation is always a real tier).
+    durations: [6, 8, 10, 12, 14, 16, 18, 20],
+    pricing: [
+      { identifier: "ltx-2.3-fast", credits: 180, note: "default 1080p 6s" },
+      { identifier: "ltx-2.3-fast:1080p:6s", credits: 180 },
+      { identifier: "ltx-2.3-fast:1080p:8s", credits: 240 },
+      { identifier: "ltx-2.3-fast:1080p:10s", credits: 300 },
+      { identifier: "ltx-2.3-fast:1080p:12s", credits: 360 },
+      { identifier: "ltx-2.3-fast:1080p:14s", credits: 420 },
+      { identifier: "ltx-2.3-fast:1080p:16s", credits: 480 },
+      { identifier: "ltx-2.3-fast:1080p:18s", credits: 540 },
+      { identifier: "ltx-2.3-fast:1080p:20s", credits: 600 },
+      { identifier: "ltx-2.3-fast:2k:6s", credits: 360 },
+      { identifier: "ltx-2.3-fast:2k:8s", credits: 480 },
+      { identifier: "ltx-2.3-fast:2k:10s", credits: 600 },
+      { identifier: "ltx-2.3-fast:4k:6s", credits: 720 },
+      { identifier: "ltx-2.3-fast:4k:8s", credits: 960 },
+      { identifier: "ltx-2.3-fast:4k:10s", credits: 1200 },
+    ],
+  },
   // ── HappyHorse (1.1 — ids kept version-less; repointed in place when KIE
   // delisted 1.0, same param surface, so saved workflows keep working) ──
   "happyhorse": {
@@ -2714,6 +2813,187 @@ export function normalizeModelInput(
   return out
 }
 
+/** Aspect tokens that mean "match the input" or "let the provider decide". They
+ *  are NOT concrete ratios, so snapping them onto one is always wrong — the
+ *  provider adapter (applySeedance2Params, applyMinimaxH3Params) resolves them
+ *  once it knows the run's mode. */
+const PASSTHROUGH_ASPECT_TOKENS = new Set(["auto", "adaptive"])
+
+/** Approximate vertical pixel count per band token, for nearest-band matching.
+ *  Anything of the form `<N>p` is parsed directly; these are the named bands
+ *  the catalogs use that do not follow that form. */
+const RESOLUTION_BAND_PIXELS: Record<string, number> = {
+  "2k": 1440,
+  "4k": 2160,
+  "8k": 4320,
+}
+
+function bandPixels(token: string): number | undefined {
+  const t = token.trim().toLowerCase()
+  if (RESOLUTION_BAND_PIXELS[t] !== undefined) return RESOLUTION_BAND_PIXELS[t]
+  const m = /^(\d+)p$/.exec(t)
+  return m ? Number(m[1]) : undefined
+}
+
+/** Nearest member of `allowed` to `token` by vertical pixels. An UNPARSEABLE
+ *  request falls back to the highest declared band — never the cheapest, which
+ *  is what a catalog-order fallback would give (R7). Highest is computed from
+ *  the pixel counts, not from the array position: most video catalogs list
+ *  ascending but not all do (minimax-h3 is `["2K", "768P"]`), and an ordering
+ *  convention is not something a money path should depend on. */
+function nearestResolutionBand(token: string, allowed: readonly string[]): string {
+  let highest = allowed[allowed.length - 1]!
+  let highestPx = -Infinity
+  for (const a of allowed) {
+    const px = bandPixels(a)
+    if (px !== undefined && px > highestPx) { highestPx = px; highest = a }
+  }
+  const want = bandPixels(token)
+  if (want === undefined) return highest
+  let best = highest
+  let bestDist = Infinity
+  for (const a of allowed) {
+    const px = bandPixels(a)
+    if (px === undefined) continue
+    const d = Math.abs(px - want)
+    if (d < bestDist) { bestDist = d; best = a }
+  }
+  return best
+}
+
+/** Nearest aspect ratio in log space. Mirrors
+ *  `backend/src/providers/video/aspect-ratio.ts` exactly — that helper cannot
+ *  be imported here (wrong package), and the totality test in
+ *  `backend/src/lib/mcp/__tests__/video-normalizer-totality.test.ts` pins the
+ *  two implementations to the same answer for every catalogued model. */
+function nearestAspectRatio(token: string, allowed: readonly string[]): string | undefined {
+  const [w, h] = token.split(":").map(Number)
+  if (!w || !h) return undefined
+  const target = Math.log(w / h)
+  let best: string | undefined
+  let bestDist = Infinity
+  for (const c of allowed) {
+    const [cw, ch] = c.split(":").map(Number)
+    if (!cw || !ch) continue
+    const d = Math.abs(Math.log(cw / ch) - target)
+    if (d < bestDist) { bestDist = d; best = c }
+  }
+  return best
+}
+
+/**
+ * Read a catalog lever off an UNVALIDATED input as a trimmed string.
+ *
+ * `normalizeVideoRequestParams` runs in both routes' creditGuard preHandler —
+ * which fires BEFORE the route's Zod parse — and in all four `buildPayload`
+ * branches, whose `data` is persisted workflow JSON that an agent/import/
+ * FieldMapping can write any JSON type into. A bare `.trim()` therefore throws
+ * `TypeError` on `{"resolution": 1080}`: a 500 where the route used to return a
+ * clean Zod 400, and in the DAG a thrown lever takes the WHOLE run down after
+ * sibling nodes have already reserved and generated. So coerce rather than
+ * assume — same posture as `sameOptionValue`, which has always used `String(v)`.
+ *
+ * `null`/`undefined`/blank mean "absent" (there is nothing to snap) and read as
+ * `undefined`, so the priced fill downstream supplies the band the identifier
+ * assumes — price and wire still agree. Everything else is stringified: a
+ * numeric `1080` becomes `"1080"` and snaps like its string form.
+ */
+function readOptionToken(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  const s = (typeof value === "string" ? value : String(value)).trim()
+  return s === "" ? undefined : s
+}
+
+export interface NormalizedVideoRequest {
+  aspectRatio?: string
+  resolution?: string
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * The video lane's LIMITED normalizer: `aspectRatio` + `resolution` only, and
+ * only when the catalog actually declares the option list.
+ *
+ * Three deliberate differences from `normalizeModelInput`:
+ *   1. It never DROPS a lever. `normalizeModelInput` removes a value whose list
+ *      the catalog doesn't declare; on the video lane `resolution` is a pricing
+ *      input, so dropping it would lower the reserved tier and `commit_credits`
+ *      never collects an upward delta — a params fix would become a money bug.
+ *   2. "Auto" / "adaptive" pass through (see PASSTHROUGH_ASPECT_TOKENS).
+ *   3. It snaps to the NEAREST option, not to `allowed[0]`. `normalizeModelInput`
+ *      would turn a portrait 9:21 into landscape 16:9 and a 4k request into the
+ *      cheapest 480p; nearest matches what the provider adapters and the MCP
+ *      normalizer already do, so all three give ONE answer. Its snap policy is
+ *      deliberately left alone — it is shared with the image lane and the
+ *      copilot, and PR 4 defers changing it.
+ *
+ * `duration` is deliberately NOT normalized here: the LTX bands make duration
+ * legality resolution-dependent, which a flat catalog list can't express, and
+ * `buildVideoCreditModelIdentifier` already snaps duration onto a seeded tier.
+ * Carrying THAT tier to the wire is `pricedVideoSelection`'s job
+ * (`credit-identifiers.ts`), which runs after this one, once resolution is known.
+ *
+ * An OMITTED lever stays omitted here — filling it is a pricing decision, not a
+ * catalog one, and likewise belongs to `pricedVideoSelection`.
+ *
+ * Case is canonicalised to the catalog's own spelling — the credit identifiers
+ * key their tables case-SENSITIVELY (LTX_DURATION_TIERS), so this is the single
+ * place a "4K" becomes "4k", and it runs before every identifier site.
+ *
+ * Pure — so the credit-identifier preHandler, `computeCredits`, the reservation
+ * site and the payload build can all call it and cannot disagree (spec §4).
+ */
+export function normalizeVideoRequestParams(
+  modelId: string,
+  input: { aspectRatio?: string; resolution?: string },
+): NormalizedVideoRequest {
+  const m = MODEL_CATALOG[modelId]
+  // Seeded from the COERCED tokens, never the raw input: this function's own
+  // return type promises `string | undefined`, and its callers feed it straight
+  // to the credit identifier and the provider wire. Handing back the caller's
+  // `1080` or `[]` verbatim would break that promise at exactly the sites that
+  // must agree on one value.
+  const aspect = readOptionToken(input.aspectRatio)
+  const res = readOptionToken(input.resolution)
+  const out: NormalizedVideoRequest = { aspectRatio: aspect, resolution: res, adjustments: [] }
+  if (!m) return out
+
+  if (m.aspectRatios?.length && aspect && !PASSTHROUGH_ASPECT_TOKENS.has(aspect.toLowerCase())) {
+    const allowed = m.aspectRatios
+    const exact = allowed.find((a) => a === aspect) ?? allowed.find((a) => a.toLowerCase() === aspect.toLowerCase())
+    if (exact !== undefined) {
+      out.aspectRatio = exact
+    } else {
+      const next = nearestAspectRatio(aspect, allowed.filter((a) => !PASSTHROUGH_ASPECT_TOKENS.has(a.toLowerCase()))) ?? allowed[0]!
+      out.adjustments.push({
+        field: "aspectRatio", from: aspect, to: next,
+        reason: `${m.label} does not support aspect ratio "${aspect}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+      })
+      out.aspectRatio = next
+    }
+  }
+
+  if (m.resolutions?.length && res) {
+    const allowed = m.resolutions
+    const exact = allowed.find((a) => a === res) ?? allowed.find((a) => a.toLowerCase() === res.toLowerCase())
+    if (exact !== undefined) {
+      out.resolution = exact
+    } else {
+      // A provider that COLLAPSES an unrecognised band renders its declared
+      // default no matter what we send, so that default — not the nearest band
+      // — is the value the wire and the price must both carry.
+      const next = m.unlistedResolutionRendersAs ?? nearestResolutionBand(res, allowed)
+      out.adjustments.push({
+        field: "resolution", from: res, to: next,
+        reason: `${m.label} does not support resolution "${res}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+      })
+      out.resolution = next
+    }
+  }
+
+  return out
+}
+
 // =============================================================================
 // Frontend picker helpers — return `{value, label}[]` shapes that the
 // existing config-panel components expect, derived from the catalog so we
@@ -2742,6 +3022,7 @@ const MODEL_VALUE_LABELS: Record<string, string> = {
   "2K": "2K (High)",
   "4K": "4K (Ultra)",
   "4k": "4K",
+  "2k": "2K",
   "8K": "8K (Ultra)",
   // qualities
   "medium": "Medium (Balanced)",

package/src/model-constants.ts

@@ -13,6 +13,42 @@ export const CREDIT_BASE_USD = 0.002
  *  schemas and the factory-preset guard test all read this. Prompt cap ONLY (not negativePrompt). */
 export const IMAGE_PROMPT_MAX = 5000
 
+/**
+ * The ONE aspect-ratio vocabulary the image routes' Zod enums are built from —
+ * `/v1/generate-image`, `/v1/image-to-image` and `/v1/edit-image` all declare
+ * `z.enum(IMAGE_ASPECT_RATIO_VALUES)` instead of keeping three literal lists
+ * that drift.
+ *
+ * It is the UNION of every ratio any `kind: "image"` catalog entry declares, so
+ * a value the picker offers can never 400 at the route. That gap has shipped
+ * twice — Wan 2.7's ultra-wide `8:1`/`1:8` (fixed on generate-image only) and
+ * Nano Banana 2 Lite's banner `4:1`/`1:4` (still open until this tuple landed).
+ * `packages/shared/src/__tests__/image-pricing-catalog-coverage.test.ts` fails
+ * the build if a new model declares a ratio this tuple is missing.
+ *
+ * This enum is a VOCABULARY BOUND, not a per-model gate: it only stops a
+ * free-form string from reaching a provider as `image_size`. The per-model gate
+ * is the catalog snap (`resolveNormalizedImageGen` → `normalizeModelInput`),
+ * which CORRECTS an unsupported ratio and discloses it in the response's
+ * `adjustments` — never rejects. So widening this tuple is always safe: it
+ * defers a rejection to the correcting snap, which is the desired behaviour.
+ *
+ * `auto` is model-specific (GPT Image 2 / Nano Banana 2 Lite treat it as
+ * "native"); it lives here for the same reason as the rest — the snap drops or
+ * replaces it for models that do not declare it.
+ */
+export const IMAGE_ASPECT_RATIO_VALUES = [
+  "auto",
+  "1:1", "16:9", "9:16", "4:3", "3:4",
+  "3:2", "2:3", "5:4", "4:5", "21:9",
+  // Ultra-wide / ultra-tall banner ratios: Wan 2.7 + Wan 2.7 Pro (8:1, 1:8)
+  // and Nano Banana 2 Lite (4:1, 1:4, 8:1, 1:8).
+  "4:1", "1:4", "8:1", "1:8",
+] as const
+
+/** A ratio string the image routes accept (pre-snap vocabulary, not a per-model guarantee). */
+export type ImageAspectRatio = typeof IMAGE_ASPECT_RATIO_VALUES[number]
+
 /**
  * Per-provider maximum ASSEMBLED image-prompt length (chars), VERIFIED against
  * each model's official docs.kie.ai schema (2026-06). Providers absent here use
@@ -75,15 +111,37 @@ export const VIDEO_PROMPT_MAX = 8000
 
 /**
  * Suno prompt / lyrics / content ceiling — the LARGEST any Suno version accepts
- * in custom mode (V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 = 5000). The route Zod
- * uses this as a generous ceiling; the handler clamps to the per-version cap via
- * {@link getMaxSunoPromptChars} (V4/V3.5 = 3000, non-custom = 500). Shared with
- * the editor `maxLength` / counter (warn-don't-block at the per-version cap).
- * `style` and `title` have their own caps ({@link getMaxSunoStyleChars} /
- * {@link SUNO_TITLE_MAX}).
+ * in custom mode (V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 = 5000). NOT the route
+ * Zod bound — the routes bind at {@link SUNO_HARD_CEILING} and clamp to the
+ * per-version cap via {@link getMaxSunoPromptChars} (3000 non-custom for every
+ * version; in custom mode 3000 for V4/V3.5, 5000 for V4.5+/V5) before the job
+ * is built. This constant is shared with the editor `maxLength` / counter
+ * (warn-don't-block at the per-version cap). `style` and `title` have their
+ * own caps ({@link getMaxSunoStyleChars} / {@link SUNO_TITLE_MAX}).
  */
 export const SUNO_TEXT_MAX = 5000
 
+/**
+ * Absolute ceiling for every Suno text field on the route Zod schemas
+ * (`prompt`, `lyrics`, `fullLyrics`, `content`, `userPrompt`).
+ *
+ * WARN-DON'T-BLOCK. The per-version caps ({@link getMaxSunoPromptChars} /
+ * {@link getMaxSunoStyleChars}) do the real work — the routes CLAMP to them
+ * before building the job. The Zod bound only exists to stop abuse, so it must
+ * stay generous: until 2026-09 the routes bounded these fields at
+ * {@link SUNO_TEXT_MAX} (5000), which meant a programmatically-set prompt (an
+ * agent, an app run, a FieldMapping) was hard-REJECTED with a 400 before the
+ * clamp could trim it — three app-report rows on 2026-08-19..31.
+ *
+ * DISTINCT FROM {@link PROMPT_HARD_CEILING} on purpose: that one is an
+ * image/video budget pinned to MAX_IMAGE/VIDEO_PROMPT_CHARS_BY_PROVIDER by its
+ * own drift guard. Coupling them would let one modality's limits move the
+ * other's. This one has a single invariant, enforced in
+ * `__tests__/prompt-length-limits.test.ts`: it MUST stay >= every value
+ * getMaxSunoPromptChars / getMaxSunoStyleChars can return.
+ */
+export const SUNO_HARD_CEILING = 30000
+
 /**
  * Absolute ceiling for the `prompt` / `negativePrompt` fields on the image and
  * video routes' Zod schemas. The PER-MODEL limits below (and the editor warning)
@@ -238,9 +296,11 @@ export function getMaxTtsChars(provider: string | undefined): number {
 }
 
 /**
- * Suno per-version field caps (from docs.kie.ai/suno-api/generate-music). The old
- * flat {@link SUNO_TEXT_MAX} (3000) was simultaneously too low for V4.5+/V5
- * prompts (5000) and too high for `style` (1000) and `title` (80).
+ * Suno per-version field caps (from docs.kie.ai/suno-api/generate-music). The
+ * original flat 3000 cap was simultaneously too low for V4.5+/V5 prompts
+ * (5000) and too high for `style` (1000) and `title` (80). ({@link
+ * SUNO_TEXT_MAX} is 5000 today — the largest per-version prompt cap; the
+ * route Zod bound is {@link SUNO_HARD_CEILING}.)
  *   - prompt / lyrics: 3000 in non-custom mode (all versions); in custom mode
  *     3000 for V4/V3.5 and 5000 for V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5.
  *   - style: 200 for V4/V3.5, 1000 for V4.5+.
@@ -1840,6 +1900,89 @@ export const VIDEO_REF_LIMITS_BY_PROVIDER: Record<
   // verified provider path + the catalog `reference-image` feature.
 }
 
+/** Per-reference-video duration bounds, in seconds. */
+export interface RefVideoDurationLimit {
+  minSec: number
+  maxSec: number
+  /** Cap on the SUM of all reference-video durations, when the provider has one. */
+  maxTotalSec?: number
+}
+
+/**
+ * Reference-video duration limits, provider-declared.
+ *
+ * `VIDEO_REF_LIMITS_BY_PROVIDER` above caps the reference COUNT; these cap the
+ * duration of each clip. Both routes already ffprobe every reference video to
+ * price the run (ee/billing/seedance2-ref-video-credits.ts and
+ * minimax-h3-credits.ts), so the numbers are in hand before the job exists —
+ * and until 2026-09-02 they were discarded, which is why "Each reference video
+ * must be between 2 and 30 seconds" and "video duration 52838 ms, expected
+ * [2000, 15000] ms" were reaching users as post-payment provider rejects
+ * (app-reports §11.3).
+ *
+ * Data-driven, exactly like SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER above:
+ * only providers with a VERIFIED documented limit are listed, so an unknown
+ * provider is never false-rejected.
+ *
+ * Sources: docs.kie.ai/market/bytedance/seedance-2-5 ("Single video duration:
+ * [2, 30] seconds"; "Total duration of reference videos must not exceed 30
+ * seconds") and docs.kie.ai/market/minimax-h3/reference-to-video (reference
+ * videos are "2 to 15 seconds" each and "the total duration of all reference
+ * videos cannot exceed 15 seconds", up to 3 videos) — both fetched 2026-09-02.
+ */
+export const VIDEO_REF_VIDEO_DURATION_LIMITS: Record<string, RefVideoDurationLimit | undefined> = {
+  "seedance-2-5": { minSec: 2, maxSec: 30, maxTotalSec: 30 },
+  // MiniMax Hailuo 3 — the provider states the per-clip bound in its own reject
+  // text: "content[1].video_url: invalid param: video duration 52838 ms,
+  // expected [2000, 15000] ms" (app-reports P4, 2 rows, the same clip retried).
+  // The KIE reference-to-video doc adds the COMBINED cap — the same shape the
+  // audio side already declares in SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER
+  // above, whose h3 row cites the same page.
+  "minimax-h3": { minSec: 2, maxSec: 15, maxTotalSec: 15 },
+}
+
+/**
+ * Validate probed reference-video durations against the provider's limits.
+ *
+ * Non-finite / non-positive entries are IGNORED, never rejected: the probe
+ * helpers treat an unreadable clip as a worst-case duration for pricing, and
+ * turning a failed ffprobe into a user-facing 400 would block legitimate runs
+ * on a transient probe failure. Callers therefore pass the RAW per-URL probe
+ * outcomes (a rejected ffprobe arrives here as NaN) — an ignored entry also
+ * contributes nothing to the `maxTotalSec` sum, so a probe blip can never push
+ * an otherwise-legal set over the total cap either.
+ */
+export function checkRefVideoDurations(
+  provider: string,
+  durationsSec: readonly number[],
+): { ok: true } | { ok: false; message: string } {
+  const limit = VIDEO_REF_VIDEO_DURATION_LIMITS[provider]
+  if (!limit) return { ok: true }
+
+  const usable = durationsSec.filter((d) => Number.isFinite(d) && d > 0)
+  if (usable.length === 0) return { ok: true }
+
+  const offender = usable.find((d) => d < limit.minSec || d > limit.maxSec)
+  if (offender !== undefined) {
+    return {
+      ok: false,
+      message: `Each reference video must be between ${limit.minSec} and ${limit.maxSec} seconds — one is ${offender.toFixed(1)}s. Trim it (a Trim Video node upstream works) and run again.`,
+    }
+  }
+
+  if (limit.maxTotalSec !== undefined) {
+    const total = usable.reduce((a, b) => a + b, 0)
+    if (total > limit.maxTotalSec) {
+      return {
+        ok: false,
+        message: `Reference videos must not exceed ${limit.maxTotalSec} seconds in total — these add up to ${total.toFixed(1)}s. Remove one or trim them and run again.`,
+      }
+    }
+  }
+
+  return { ok: true }
+}
+
 /**
  * Video models where credit cost depends on resolution AND whether a video
  * reference is connected. Identifier suffix: `:{resolution}[-ref]`.
@@ -2027,8 +2170,8 @@ export interface VideoAudioCapability {
 /**
  * Per-model audio capability. Only models that produce SOME audio are listed;
  * anything absent defaults to `{ mode: "none" }` via `getVideoAudioCapability`,
- * so silent models (minimax, hailuo, wan, grok-i2v, gemini-omni-video, runway,
- * pika, …) need no entry. New audio-capable models MUST be added here — the
+ * so silent models (minimax, hailuo, wan-i2v, grok-i2v, runway, pika, …) need
+ * no entry. New audio-capable models MUST be added here — the
  * `video-audio-capability` guard test cross-checks this map against the model
  * configs' `extraParams.sound` / `generate_audio` + VEO/Seedance-2 sets so a
  * forgotten entry fails CI rather than silently disabling audio.
@@ -2077,10 +2220,39 @@ export const VIDEO_AUDIO_CAPABILITY: Record<string, VideoAudioCapability> = {
   // and skip the lip-sync pass. `defaultOn` mirrors the KIE default so an
   // intent-less request is described honestly; audio is priced into the uniform
   // per-second rate, so NOT cost-affecting (no `:audio` composite).
-  // gemini-omni-flash is deliberately ABSENT — gemini-omni-video is absent too
-  // (mode "none"), and the siblings must not disagree.
   "wan-3": { mode: "ambient", field: "audio", defaultOn: true },
   "wan-3-prime": { mode: "ambient", field: "audio", defaultOn: true },
+  // Gemini Omni (both SKUs — the pro `gemini-omni-video` and the faster
+  // `gemini-omni-flash`; one model at two speeds, so their rows are identical
+  // and a test pins that). Settled 2026-09-03 from Google's own documentation
+  // at https://ai.google.dev/gemini-api/docs/omni, having been unlisted — and
+  // therefore reported as SILENT — while the catalog described both as "native
+  // audio".
+  //
+  // "ambient", and alwaysOn with no toggle field, on three sentences from that
+  // page:
+  //   - "By default the model will try to generate an appropriate audio track
+  //     for a video." Audio on every render, and the KIE input schema
+  //     (prompt / image_urls / first+last_frame_url / audio_ids / video_list /
+  //     character_ids / duration / aspect_ratio / seed / resolution — see
+  //     docs.kie.ai/market/gemini-omni-video and
+  //     docs.kie.ai/market/google/gemini-omni-flash-1-1) carries no on/off
+  //     lever, so there is nothing for applyVideoAudioToggle to write.
+  //   - NOT native_speech: "Multi-turn voice extension: Generating spoken
+  //     dialogue or speech is supported when extending previously generated
+  //     videos via multi-turn (`previous_interaction_id`)" — a field KIE's
+  //     createTask schema does not expose, so the dialogue path is unreachable
+  //     on our transport. Held to the Wan 3.0 bar: no documented dialogue
+  //     guarantee on the path we actually drive ⇒ ambient, and upgrade only on
+  //     a live probe (the kling-3.0 standard). Classifying it native_speech
+  //     would reroute the Story→Video dialogue pipeline past the lip-sync pass.
+  //   - NOT audio_driven either: "Uploading audio references is unsupported in
+  //     the current version of the API", and "any audio in a video reference is
+  //     ignored" — there is no reference-audio transport to be driven by, and
+  //     runGeminiOmni never sends `audio_ids`.
+  // Audio is priced into the per-tier rate, so NOT cost-affecting.
+  "gemini-omni-video": { mode: "ambient", alwaysOn: true },
+  "gemini-omni-flash": { mode: "ambient", alwaysOn: true },
 }
 
 const VIDEO_AUDIO_NONE: VideoAudioCapability = { mode: "none" }