@nodaro/shared 2.18.0 → 2.20.0

package/src/index.ts

@@ -18,6 +18,7 @@ export { usdToCredits, creditsToUsd, CREDIT_ROUNDING_RESOLUTION } from "./credit
 export {
   CREDIT_BASE_USD,
   IMAGE_PROMPT_MAX,
+  IMAGE_ASPECT_RATIO_VALUES,
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   getMaxImagePromptChars,
   PROMPT_HARD_CEILING,
@@ -35,6 +36,7 @@ export {
   getMaxSunoStyleChars,
   VIDEO_PROMPT_MAX,
   SUNO_TEXT_MAX,
+  SUNO_HARD_CEILING,
   NATIVE_NEGATIVE_PROMPT_MODELS,
   NATIVE_NEGATIVE_VIDEO_PROVIDERS,
   applyVideoNegativePrompt,
@@ -117,6 +119,12 @@ export {
   isMinimaxH3Provider,
   MINIMAX_H3_DEFAULT_RESOLUTION,
   normalizeMinimaxH3Resolution,
+  WAN_3_PROVIDERS,
+  isWan3Provider,
+  WAN_3_DEFAULT_RESOLUTION,
+  normalizeWan3Resolution,
+  GEMINI_OMNI_PROVIDERS,
+  isGeminiOmniProvider,
   VIDEO_PROVIDERS_WITHOUT_DISPATCH,
   GVP_DEFAULT_PROVIDER,
   GVP_SUPPORTED_PROVIDERS,
@@ -167,6 +175,7 @@ export { FEATURED_ENTITIES, getFeaturedEntities } from "./featured-entities.js"
 export type { FeaturedEntity } from "./featured-entities.js"
 
 export type {
+  ImageAspectRatio,
   ImageGenProvider,
   ImageMaskMode,
   ImageI2IProvider,
@@ -228,9 +237,14 @@ export type {
 export {
   buildCreditModelIdentifier,
   resolveImageGenCreditIdentifier,
+  resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
   buildMotionCreditModelIdentifier,
+  sunoCreditType,
+  SUNO_VERSION_PRICED_OPERATIONS,
+  SUNO_SELECT_OPERATIONS,
 } from "./credit-identifiers.js"
+export type { NormalizedImageGen } from "./credit-identifiers.js"
 
 export * from "./credit-estimators/index.js"
 export { extractVideoDurationFromNode } from "./video-duration.js"
@@ -988,6 +1002,9 @@ export * from "./video-analysis.js"
 // buildVideoAuditCreditId / videoAuditCreditsForBucket / bucketSecondsFromAuditCreditId).
 export * from "./video-analysis-pricing.js"
 
+// --- Unified video node UI-default fills (panel snap == strip == DAG payload) ---
+export * from "./video-ui-defaults.js"
+
 // --- Smart-cut best-pair search windows (shared bound + clamp) ---
 export * from "./smart-cut-windows.js"
 

package/src/model-catalog.ts

@@ -228,6 +228,12 @@ const VIDEO_RATIOS_SEEDANCE_2 = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "a
 // portrait-social and 21:9/9:21 cinematic (docs.kie.ai/market/happyhorse-1-1).
 // Kept separate so the wider set can't leak to models that don't support it.
 const VIDEO_RATIOS_HAPPYHORSE_11 = ["16:9", "9:16", "1:1", "4:3", "3:4", "4:5", "5:4", "21:9", "9:21"] as const
+// Wan 3.0 (standard + Prime) — the model's own six-ratio enum, `adaptive` first
+// because that is the KIE default ("automatically selects the ratio based on the
+// input media and intent"). Deliberately NO 21:9 — the Wan 3.0 enum rejects it,
+// so VIDEO_RATIOS_SEEDANCE_2 must NOT be reused here
+// (docs.kie.ai/market/wan/3-0-video and /3-0-video-prime — identical schemas).
+const VIDEO_RATIOS_WAN_3 = ["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16"] as const
 
 // =============================================================================
 // IMAGE MODELS
@@ -1179,6 +1185,41 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "gemini-omni-video:4k:vref", credits: 900, note: "video-edit 4K" },
     ],
   },
+  // Gemini Omni Flash 1.1 — the faster/cheaper Omni SKU (KIE
+  // `google/gemini-omni-flash-1-1`). Identical request surface to
+  // gemini-omni-video, so every capability below is deliberate PARITY with the
+  // sibling: same 4/6/8/10s ladder, same 720p/1080p + 4K bands, same
+  // features (the KIE schema also exposes first/last frame, but the pro
+  // sibling's frame path is unwired here too — no "end-frame" until it is).
+  // 360p is on the KIE enum but NOT exposed: it sits in the same credit band as
+  // 720p/1080p, so it could only hand the user a worse render at the same price.
+  "gemini-omni-flash": {
+    id: "gemini-omni-flash",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,   // V2V is served via the i2v handle, not a catalog mode
+    family: "Google",
+    label: "Gemini Omni Flash",
+    series: "Gemini",
+    description: "Google Gemini Omni Flash — faster/cheaper Omni tier: multimodal video with native audio, text/image-to-video + video-edit.",
+    useCases: ["cinematic", "fast"],
+    features: ["audio", "reference-image"],
+    aspectRatios: VIDEO_RATIOS_HV,
+    resolutions: ["720p", "1080p", "4k"],
+    durations: [4, 6, 8, 10],
+    pricing: [
+      { identifier: "gemini-omni-flash", credits: 270, note: "default — 8s 720p/1080p (the credit builder's duration fallback)" },
+      { identifier: "gemini-omni-flash:4", credits: 160, note: "720p/1080p 4s" },
+      { identifier: "gemini-omni-flash:6", credits: 210, note: "720p/1080p 6s" },
+      { identifier: "gemini-omni-flash:8", credits: 270, note: "720p/1080p 8s" },
+      { identifier: "gemini-omni-flash:10", credits: 320, note: "720p/1080p 10s" },
+      { identifier: "gemini-omni-flash:4k:4", credits: 370, note: "4K 4s" },
+      { identifier: "gemini-omni-flash:4k:6", credits: 420, note: "4K 6s" },
+      { identifier: "gemini-omni-flash:4k:8", credits: 480, note: "4K 8s" },
+      { identifier: "gemini-omni-flash:4k:10", credits: 530, note: "4K 10s" },
+      { identifier: "gemini-omni-flash:vref", credits: 420, note: "video-edit 720p/1080p" },
+      { identifier: "gemini-omni-flash:4k:vref", credits: 630, note: "video-edit 4K" },
+    ],
+  },
 
   // ── Kling ──
   "kling": {
@@ -1450,6 +1491,66 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   },
 
   // ── Wan ──
+  // Wan 3.0 (standard + Prime) — a NEW generation, not a tier of the 2.x ladder.
+  // One id per SKU serves BOTH modes (no t2v twin, no alias): first/last frame
+  // OR an all-purpose reference mode (images/videos/audio, bound in the prompt
+  // as Image1/Video1/Audio1 — no space, unlike Wan 2.x), native audio behind a
+  // boolean `audio` lever, 2-30s at 480p/720p/1080p.
+  // `video-reference` is deliberately NOT declared: KIE accepts reference videos,
+  // but the extend chain is unwired and KIE caps input-video + output at 30s,
+  // which the segment bounds cannot express. Precedent: gemini-omni-video carries
+  // ref limits without the feature. The ref CAPS still live in
+  // VIDEO_REF_LIMITS_BY_PROVIDER (model-constants).
+  // `resolutions` is ascending (repo convention); the DEFAULT tier (720p) is
+  // declared explicitly in PRICING_DEFAULT_RESOLUTION, never by array position.
+  "wan-3": {
+    id: "wan-3",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Alibaba",
+    label: "Wan 3.0",
+    series: "Wan",
+    description: "Wan 3.0 — multimodal: first/last frame or image/video/audio references, native audio, 2-30s at 480p/720p/1080p.",
+    useCases: ["motion", "narrative", "long-form"],
+    features: ["end-frame", "audio", "reference-image"],
+    aspectRatios: VIDEO_RATIOS_WAN_3,
+    durations: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30],
+    resolutions: ["480p", "720p", "1080p"],
+    pricing: [
+      { identifier: "wan-3", credits: 200, note: "default 5s 720p — see :Ns:res variants for exact" },
+      { identifier: "wan-3:5s:720p", credits: 200, note: "5s 720p (the default tier)" },
+      { identifier: "wan-3:8s:480p", credits: 160, note: "8s 480p" },
+      { identifier: "wan-3:8s:720p", credits: 320, note: "8s 720p" },
+      { identifier: "wan-3:8s:1080p", credits: 640, note: "8s 1080p" },
+      { identifier: "wan-3:30s:480p", credits: 600, note: "30s 480p (max)" },
+      { identifier: "wan-3:30s:720p", credits: 1200, note: "30s 720p (max)" },
+      { identifier: "wan-3:30s:1080p", credits: 2400, note: "30s 1080p (max)" },
+    ],
+  },
+  "wan-3-prime": {
+    id: "wan-3-prime",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Alibaba",
+    label: "Wan 3.0 Prime",
+    series: "Wan",
+    description: "Wan 3.0 Prime — Alibaba's high-speed Wan 3.0 tier: same multimodal surface and 2-30s range, faster turnaround at a higher per-second rate.",
+    useCases: ["fast", "motion", "narrative"],
+    features: ["end-frame", "audio", "reference-image"],
+    aspectRatios: VIDEO_RATIOS_WAN_3,
+    durations: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30],
+    resolutions: ["480p", "720p", "1080p"],
+    pricing: [
+      { identifier: "wan-3-prime", credits: 320, note: "default 5s 720p — see :Ns:res variants for exact" },
+      { identifier: "wan-3-prime:5s:720p", credits: 320, note: "5s 720p (the default tier)" },
+      { identifier: "wan-3-prime:8s:480p", credits: 250, note: "8s 480p" },
+      { identifier: "wan-3-prime:8s:720p", credits: 510, note: "8s 720p" },
+      { identifier: "wan-3-prime:8s:1080p", credits: 1010, note: "8s 1080p" },
+      { identifier: "wan-3-prime:30s:480p", credits: 920, note: "30s 480p (max)" },
+      { identifier: "wan-3-prime:30s:720p", credits: 1890, note: "30s 720p (max)" },
+      { identifier: "wan-3-prime:30s:1080p", credits: 3780, note: "30s 1080p (max)" },
+    ],
+  },
   "wan-i2v": {
     id: "wan-i2v",
     kind: "video",

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)
@@ -139,6 +197,13 @@ export const MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER: Record<string, number> = {
   // (docs.kie.ai/market/bytedance/seedance-2-5).
   "seedance-2-5": 30000,
   "gemini-omni-video": 20000,
+  // Gemini Omni Flash 1.1 — same 20000-char prompt surface as the pro sibling
+  // (docs.kie.ai/market/google/gemini-omni-flash-1-1).
+  "gemini-omni-flash": 20000,
+  // Wan 3.0 / 3.0 Prime — 20000 chars, excess truncated by the provider
+  // (docs.kie.ai/market/wan/3-0-video and /3-0-video-prime).
+  "wan-3": 20000,
+  "wan-3-prime": 20000,
   "bytedance-lite": 10000,
   "bytedance-pro": 10000,
   "bytedance-pro-fast": 10000,
@@ -231,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+.
@@ -750,6 +817,11 @@ export const IMAGE_TO_VIDEO_PROVIDERS = [
   "runway-kie",
   "kling-3-omni",
   "gemini-omni-video",
+  "gemini-omni-flash",
+  // Wan 3.0 family — one id per SKU serves BOTH modes (no t2v twin, no alias),
+  // so each id is listed in this array AND in TEXT_TO_VIDEO_PROVIDERS.
+  "wan-3",
+  "wan-3-prime",
   "ltx-2.3-pro",
   "ltx-2.3-fast",
   // xAI Grok Imagine Video 1.5 — KIE i2v (image_urls required). Also listed in
@@ -788,6 +860,12 @@ export const TEXT_TO_VIDEO_PROVIDERS = [
   "happyhorse",
   "runway-kie",
   "gemini-omni-video",
+  "gemini-omni-flash",
+  // Wan 3.0 family — REAL t2v (prompt-only runs are the documented default
+  // mode), so they belong in this main section and must NOT be gated by
+  // VIDEO_PROVIDERS_REQUIRING_IMAGE.
+  "wan-3",
+  "wan-3-prime",
   "ltx-2.3-pro",
   "ltx-2.3-fast",
   // ── i2v-only providers (image required) ──────────────────────────────────
@@ -1245,6 +1323,12 @@ export const DURATION_PRICED_PROVIDERS = new Set([
   "happyhorse",
   "happyhorse-i2v",
   "happyhorse-ref2v",
+  // Wan 3.0 family — per-second billing at three resolution rates. NOTE:
+  // gemini-omni-flash is deliberately ABSENT (like gemini-omni-video): the
+  // Gemini Omni branch in buildVideoCreditModelIdentifier early-returns before
+  // this gate is consulted.
+  "wan-3",
+  "wan-3-prime",
 ])
 
 /**
@@ -1302,6 +1386,75 @@ export function normalizeMinimaxH3Resolution(resolution: string | undefined): "7
   return resolution?.trim().toLowerCase() === "768p" ? "768P" : MINIMAX_H3_DEFAULT_RESOLUTION
 }
 
+/**
+ * Wan 3.0 family — the KIE "wan/3-0-video" market model and its high-speed
+ * "wan/3-0-video-prime" sibling. The two share a BYTE-IDENTICAL input schema
+ * (first/last frame OR an all-purpose reference mode with images/videos/audio,
+ * native `audio` boolean, 2-30s, 480P/720P/1080P, six aspect ratios with
+ * `adaptive` as the default); only the per-second rate differs. Prime is the
+ * FASTER tier at a higher rate — never describe it as "higher quality".
+ *
+ * Exact-membership set — NEVER match on a "wan" prefix: "wan", "wan-i2v",
+ * "wan-turbo", "wan-flash", "wan-videoedit" and the "wan-2.7-*" ids are
+ * unrelated 2.x models with a different surface (and a different reference
+ * token format — see WAN_3_DOCTRINE in @nodaro/prompts).
+ */
+export const WAN_3_PROVIDERS = new Set<string>([
+  "wan-3",
+  "wan-3-prime",
+])
+
+export function isWan3Provider(provider: string | undefined): boolean {
+  return !!provider && WAN_3_PROVIDERS.has(provider)
+}
+
+/** Wan 3.0 resolution the PLATFORM renders when the param is omitted or unknown.
+ *  Deliberately NOT KIE's own default (1080P): 720p is the tier the bare credit
+ *  identifier prices, so the provider layer pins it to keep render == billed. */
+export const WAN_3_DEFAULT_RESOLUTION = "720P"
+
+/**
+ * SINGLE normalization for the Wan 3.0 resolution lever (KIE wire enum
+ * "480P" | "720P" | "1080P"). Everything INTERNAL — the catalog, QUALITY_MAP,
+ * dropdowns, RESOLUTION_DURATION_PRICING keys and every emitted credit
+ * identifier — stays LOWERCASE; this helper is the ONE place the uppercase wire
+ * form is produced (backend KIE payload build), the twin of
+ * {@link normalizeMinimaxH3Resolution}.
+ *
+ * Case-insensitive. Anything else (undefined, garbage, a stale "4k") collapses
+ * to {@link WAN_3_DEFAULT_RESOLUTION} — the tier the default credit identifier
+ * reserves — so the billed tier can never undercut the rendered one.
+ */
+export function normalizeWan3Resolution(resolution: string | undefined): "480P" | "720P" | "1080P" {
+  switch (resolution?.trim().toLowerCase()) {
+    case "480p": return "480P"
+    case "1080p": return "1080P"
+    case "720p": return "720P"
+    default: return WAN_3_DEFAULT_RESOLUTION
+  }
+}
+
+/**
+ * Google Gemini Omni family — the KIE "gemini-omni-video" market model and its
+ * faster/cheaper "google/gemini-omni-flash-1-1" sibling. Both take the SAME
+ * request shape (prompt + image_urls references, video-edit through the i2v
+ * handle, 4/6/8/10s, 720p/1080p or a 4K band) and are dispatched through the
+ * same runner, so every behavioural branch that used to compare against the
+ * literal "gemini-omni-video" must ask this predicate instead — V2V routing,
+ * the 7-slot reference quota, the mode swap and the aspect-ratio panels.
+ *
+ * Exact-membership set — NEVER match on a "gemini" prefix (the Gemini LLM ids
+ * would collide).
+ */
+export const GEMINI_OMNI_PROVIDERS = new Set<string>([
+  "gemini-omni-video",
+  "gemini-omni-flash",
+])
+
+export function isGeminiOmniProvider(provider: string | undefined): boolean {
+  return !!provider && GEMINI_OMNI_PROVIDERS.has(provider)
+}
+
 /**
  * Video models that are CATALOGUED and priced but have NO working dispatch
  * path today — selecting one fails at the router, not at validation.
@@ -1553,9 +1706,15 @@ export function maxSegmentsFor(provider: string | undefined, capSec: number): nu
  * param at all (inferred from the frame). Only the pure-t2v endpoint requires
  * a concrete ratio — the KIE provider layer coerces `adaptive` → `16:9` there
  * (see applyMinimaxH3Params in backend kie/video.ts).
+ *
+ * Wan 3.0 also defaults to `adaptive` — it is the model's own KIE default and
+ * the first value in its aspect enum, so an un-set node must not silently run
+ * at 16:9 while the panel displays Adaptive.
  */
 export function defaultVideoAspectRatio(provider: string | undefined): string {
-  return isSeedance2Provider(provider) || isMinimaxH3Provider(provider) ? "adaptive" : "16:9"
+  return isSeedance2Provider(provider) || isMinimaxH3Provider(provider) || isWan3Provider(provider)
+    ? "adaptive"
+    : "16:9"
 }
 
 /**
@@ -1656,6 +1815,10 @@ export const SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER: Record<string, number> =
   // MiniMax Hailuo 3 — documented hard limit: each reference audio segment
   // 2-15s, ≤15s total (docs.kie.ai/market/minimax-h3/reference-to-video).
   "minimax-h3": 15,
+  // Wan 3.0 family — documented hard limit: each reference audio clip 1-15s,
+  // ≤15s combined (docs.kie.ai/market/wan/3-0-video).
+  "wan-3": 15,
+  "wan-3-prime": 15,
 }
 
 /** The verified r2v reference-audio cap (seconds) for a provider, or null when
@@ -1711,8 +1874,17 @@ export const VIDEO_REF_LIMITS_BY_PROVIDER: Record<
   // bills input images beyond the first 5 (11 KIE cr each) — see the
   // minimax-h3 credit helper in backend ee/billing.
   "minimax-h3": { ...SEEDANCE_2_REF_LIMITS },
+  // Wan 3.0 family — all-purpose reference mode: up to 10 images / 5 videos
+  // (each 1-15s, ≤15s combined) / 5 audio clips (each 1-15s, ≤15s combined).
+  // The reference arrays are mutually EXCLUSIVE with first/last frame at the
+  // provider (docs.kie.ai/market/wan/3-0-video).
+  "wan-3": { images: 10, videos: 5, audio: 5 },
+  "wan-3-prime": { images: 10, videos: 5, audio: 5 },
   // Multi-image reference providers.
   "gemini-omni-video": { images: 7, videos: 1 },
+  // Gemini Omni Flash 1.1 — identical quota to the pro sibling
+  // (images + 2×videos + character_ids ≤ 7).
+  "gemini-omni-flash": { images: 7, videos: 1 },
   "kling-3-omni": { images: 7 },     // catalog/docs: "end frame + up to 7 reference images"
   "grok-i2v": { images: 7 },         // backend kie/models.ts maxRefImages: 7
   "happyhorse-ref2v": { images: 9 }, // backend kie/models.ts maxRefImages: 9
@@ -1738,10 +1910,15 @@ export const RESOLUTION_VIDEO_REF_PRICING = SEEDANCE_2_PROVIDERS
 /**
  * Video models priced by (duration × resolution) WITHOUT a video-ref dimension.
  * Identifier suffix: `:{resolution}`, appended after the duration tier; value =
- * the provider's PRICED resolution tiers. Any resolution outside the list
- * (or undefined) collapses to the FIRST entry — the provider's default tier —
- * so the builder can never emit an unpriced composite (the hard-fail guard
- * fuzzes the full resolution space). Distinct from
+ * the provider's PRICED resolution tiers.
+ *
+ * Any resolution outside the list (or undefined) collapses to the provider's
+ * DEFAULT tier, so the builder can never emit an unpriced composite (the
+ * hard-fail guard fuzzes the full resolution space). That default is
+ * {@link PRICING_DEFAULT_RESOLUTION} when the provider declares one, and
+ * otherwise the FIRST entry here — so a member with a declared default (wan-3)
+ * can list its tiers in the repo-standard ascending order without index 0
+ * silently becoming the billed default. Distinct from
  * RESOLUTION_VIDEO_REF_PRICING (Seedance gen), which also adds `-ref` variants.
  */
 export const RESOLUTION_DURATION_PRICING: Record<string, readonly string[]> = {
@@ -1757,6 +1934,12 @@ export const RESOLUTION_DURATION_PRICING: Record<string, readonly string[]> = {
   "happyhorse": ["720p", "1080p"],
   "happyhorse-i2v": ["720p", "1080p"],
   "happyhorse-ref2v": ["720p", "1080p"],
+  // Wan 3.0 / Prime — per-second billing at three published resolution rates.
+  // Ascending, matching the catalog; the BILLED default is declared explicitly
+  // in PRICING_DEFAULT_RESOLUTION ("720p") rather than carried by index 0, and
+  // the provider layer pins the same 720P so render == billed.
+  "wan-3": ["480p", "720p", "1080p"],
+  "wan-3-prime": ["480p", "720p", "1080p"],
 }
 
 /**
@@ -1779,6 +1962,13 @@ export const NATIVE_ADAPTIVE_ASPECT: Record<string, string> = {
   "seedance-2-fast": "adaptive",
   "seedance-2-mini": "adaptive",
   "seedance-2-5": "adaptive",
+  // Wan 3.0 family: `adaptive` is the enum DEFAULT and KIE documents it as
+  // "automatically selects the ratio based on the input media and intent"
+  // (docs.kie.ai/market/wan/3-0-video) — i.e. match-the-input, not merely
+  // "provider default" (the grok `auto` trap). DOC-verified only; re-confirm
+  // with a live job before relying on it for off-catalog ratios.
+  "wan-3": "adaptive",
+  "wan-3-prime": "adaptive",
 }
 
 /**
@@ -1877,8 +2067,9 @@ export type VideoAudioMode = "none" | "ambient" | "native_speech" | "audio_drive
 
 export interface VideoAudioCapability {
   mode: VideoAudioMode
-  /** Provider-option field carrying the on/off toggle, when user-controllable. */
-  field?: "generateAudio" | "sound"
+  /** Provider-option field carrying the on/off toggle, when user-controllable.
+   *  `audio` is Wan 3.0's own boolean lever (KIE `input.audio`, default true). */
+  field?: "generateAudio" | "sound" | "audio"
   /** Audio is always produced and can't be turned off by the user (VEO 3.x). */
   alwaysOn?: boolean
   /** Enabling audio raises the credit cost (Kling — see AUDIO_ADDON_PROVIDERS). */
@@ -1937,6 +2128,19 @@ export const VIDEO_AUDIO_CAPABILITY: Record<string, VideoAudioCapability> = {
   // KIE API exposes NO audio on/off parameter (audio is always produced), so
   // there is no toggle field — alwaysOn, like VEO.
   "minimax-h3": { mode: "audio_driven", alwaysOn: true },
+  // Wan 3.0 family — a single boolean `audio` lever (KIE default true) produces
+  // an ambient/SFX track with the clip. Classified "ambient", NOT
+  // "native_speech" or "audio_driven": the schema documents no dialogue
+  // guarantee, and reference audio is a generic conditioning array, not a
+  // verified lip-sync transport. Upgrade only on a live probe (the kling-3.0
+  // standard) — `audio_driven` would reroute the Story→Video dialogue pipeline
+  // 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 },
 }
 
 const VIDEO_AUDIO_NONE: VideoAudioCapability = { mode: "none" }
@@ -2008,6 +2212,7 @@ export function applyVideoAudioToggle(
   const enabled = cap.affectsCost ? opts?.sound : (opts?.sound ?? opts?.generateAudio)
   if (enabled === undefined) return // no intent — keep the model's own default
   if (cap.field === "generateAudio") input.generate_audio = enabled
+  else if (cap.field === "audio") input.audio = enabled
   else input.sound = enabled
 }
 
@@ -2063,6 +2268,11 @@ export const VIDEO_VARIABLE_PRICING: Record<string, "duration" | "duration+audio
   "minimax-h3": "duration+resolution",
   // Grok Imagine Video 1.5 — per-second billing split 480p/720p (no video-ref dimension).
   "grok-imagine-video-1.5": "duration+resolution",
+  // Wan 3.0 family — per-second billing at three resolution rates (no video-ref
+  // dimension: reference runs bill output seconds only). No gemini-omni-flash
+  // entry, mirroring gemini-omni-video which has none either.
+  "wan-3": "duration+resolution",
+  "wan-3-prime": "duration+resolution",
 }
 
 /**
@@ -2098,6 +2308,14 @@ export const PRICING_DEFAULT_DURATION_SEC: Record<string, number> = {
 export const PRICING_DEFAULT_RESOLUTION: Record<string, string> = {
   // KIE renders 720p when `resolution` is omitted (kie/models.ts extraParams).
   "seedance-2-5": "720p",
+  // Wan 3.0 family — KIE's OWN default is 1080P, but the provider layer pins
+  // 720P (normalizeWan3Resolution / WAN_3_DEFAULT_RESOLUTION) so the rendered
+  // tier equals the tier the bare identifier bills. This declaration is what
+  // makes the billed default explicit instead of an array ordering: the
+  // RESOLUTION_DURATION_PRICING branch consults it before falling back to the
+  // first tier, so the catalog can stay ascending without repricing anything.
+  "wan-3": "720p",
+  "wan-3-prime": "720p",
 }
 
 /** HappyHorse 1.1 per-second tiers — one per allowed duration (3–15s), shared
@@ -2122,6 +2340,21 @@ const SEEDANCE_2_5_DURATION_TIERS: Array<{ maxSeconds: number; suffix: string }>
   (_, i) => ({ maxSeconds: i + 4, suffix: `${i + 4}s` }),
 )
 
+/**
+ * Wan 3.0 per-second tiers — one per allowed duration (2-30s), shared by both
+ * SKUs (the ladder shape is identical; only the seeded rates differ).
+ *
+ * Per-second is REQUIRED, not a nicety: the ladder snaps a request UP to the
+ * first tier whose `maxSeconds` covers it and falls back to the LAST tier when
+ * none does, so a coarse ladder over a 29-value range would reserve a
+ * short-clip price for a 30s render. `commit_credits` only ever refunds a
+ * surplus and can never collect an upward delta.
+ */
+const WAN_3_DURATION_TIERS: Array<{ maxSeconds: number; suffix: string }> = Array.from(
+  { length: 29 },
+  (_, i) => ({ maxSeconds: i + 2, suffix: `${i + 2}s` }),
+)
+
 /**
  * Duration tier breakpoints for variable-priced video models.
  * Maps provider → array of { maxSeconds, suffix } in ascending order.
@@ -2202,6 +2435,8 @@ export const VIDEO_DURATION_TIERS: Record<string, Array<{ maxSeconds: number; su
     { maxSeconds: 15, suffix: "15s" },
   ],
   "seedance-2-5": SEEDANCE_2_5_DURATION_TIERS,
+  "wan-3": WAN_3_DURATION_TIERS,
+  "wan-3-prime": WAN_3_DURATION_TIERS,
   // MiniMax Hailuo 3 — true per-second billing (KIE 36.5 cr/s @2K, 22.5 cr/s
   // @768P). One tier per allowed second (4-15s) so the composite identifier
   // maps 1:1 to the seeded price — no rounding/overcharge for any on-menu

package/src/node-default-mappings.ts

@@ -187,6 +187,10 @@ const QUALITY_MAP: Record<string, QualityMapping> = {
   // Seedance 2.5 spans 480p/720p/1080p on KIE (1080p accepted since the
   // 2026-08-17 re-probe; 4k still rejected), so each quality rung gets its own tier.
   "seedance-2-5":        { field: "resolution", values: { low: "480p", mid: "720p", high: "1080p" } },
+  // Wan 3.0 family — 480p / 720p / 1080p (lowercase catalog spellings; the
+  // uppercase KIE wire form is produced only by normalizeWan3Resolution).
+  "wan-3":               { field: "resolution", values: { low: "480p", mid: "720p", high: "1080p" } },
+  "wan-3-prime":         { field: "resolution", values: { low: "480p", mid: "720p", high: "1080p" } },
   "wan-2.7-i2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
   "wan-2.7-t2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
   "happyhorse":          { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
@@ -200,6 +204,7 @@ const QUALITY_MAP: Record<string, QualityMapping> = {
   "ltx-2.3-pro":         { field: "resolution", values: { low: "1080p", mid: "2k", high: "4k" } },
   "ltx-2.3-fast":        { field: "resolution", values: { low: "1080p", mid: "2k", high: "4k" } },
   "gemini-omni-video":   { field: "resolution", values: { low: "720p", mid: "1080p", high: "4k" } },
+  "gemini-omni-flash":   { field: "resolution", values: { low: "720p", mid: "1080p", high: "4k" } },
   // Grok Imagine Video 1.5 — only 480p/720p (no 1080p tier); high clamps to 720p.
   "grok-imagine-video-1.5": { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
   // Replicate Flux 2 family — MP-based resolution (matching IMAGE_RESOLUTION_OPTIONS["flux-2-*"]).

package/src/normalize-node-params.ts

@@ -30,10 +30,18 @@ import { normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.
  * through mode-dependent defaults (`"adaptive"` for Seedance/Hailuo, duration
  * composites tied to pricing) that this flat normalizer would flatten wrongly;
  * they get their own pass once those defaults are catalog-derived too.
+ *
+ * `modify-image` carries the same provider/aspectRatio/resolution/quality trio
+ * as `image-to-image` (it routes through the same worker), and `edit-image`
+ * carries provider + aspectRatio. `edit-image`'s `targetResolution` is an
+ * UPSCALE target, a different field this module never reads — so listing the
+ * type here heals its ratio without touching what it is priced on.
  */
 export const MODEL_PARAM_NODE_TYPES: ReadonlySet<string> = new Set([
   "generate-image",
   "image-to-image",
+  "modify-image",
+  "edit-image",
 ])
 
 export interface NodeParamAdjustment extends ModelInputAdjustment {