@nodaro/shared 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/credit-identifiers.test.ts

@@ -17,6 +17,8 @@ describe("buildCreditModelIdentifier", () => {
       "seedream-edit",
       "seedream-5-lite",
       "seedream-5-lite-i2i",
+      "seedream-5-pro",
+      "seedream-5-pro-i2i",
     ]
 
     it.each(highQualityProviders)(
@@ -311,31 +313,31 @@ describe("buildVideoCreditModelIdentifier", () => {
   // --- Duration tiers for kling-3.0 ---
   describe("kling-3.0 duration tiers", () => {
     it("5s duration returns :5s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 5)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 5, false)).toBe("kling-3.0:5s")
     })
 
     it("3s duration falls into 5s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 3)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 3, false)).toBe("kling-3.0:5s")
     })
 
     it("10s duration returns :10s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 10)).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 10, false)).toBe("kling-3.0:10s")
     })
 
     it("7s duration falls into 10s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 7)).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 7, false)).toBe("kling-3.0:10s")
     })
 
     it("15s duration returns :15s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 15)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 15, false)).toBe("kling-3.0:15s")
     })
 
     it("duration exceeding max tier clamps to last tier (20s -> 15s)", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 20)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 20, false)).toBe("kling-3.0:15s")
     })
 
     it("duration exceeding max tier clamps to last tier (100s -> 15s)", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 100)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 100, false)).toBe("kling-3.0:15s")
     })
   })
 
@@ -349,6 +351,18 @@ describe("buildVideoCreditModelIdentifier", () => {
       expect(buildVideoCreditModelIdentifier("kling", 5, true)).toBe("kling:5s:audio")
     })
 
+    it("kling-3.0 + sound UNDEFINED appends :audio (model default is audio ON)", () => {
+      // The provider layer generates audio when the caller expressed no intent
+      // (models.ts extraParams.sound: true + kling3-client `?? true`). Billing
+      // must mirror that via capability defaultOn — reserving the no-audio
+      // tier against an audio-on generation was a silent under-bill.
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 5, undefined)).toBe("kling-3.0:5s:audio")
+    })
+
+    it("kling (2.6) + sound UNDEFINED does not append :audio (model default is OFF)", () => {
+      expect(buildVideoCreditModelIdentifier("kling", 5, undefined)).toBe("kling:5s")
+    })
+
     it("kling-3.0 + sound=false does not append :audio", () => {
       expect(buildVideoCreditModelIdentifier("kling-3.0", 5, false)).toBe("kling-3.0:5s")
     })
@@ -405,7 +419,7 @@ describe("buildVideoCreditModelIdentifier", () => {
   // --- String duration parsing ---
   describe("duration parsing", () => {
     it('string duration "10" is parsed as number 10', () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", "10")).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", "10", false)).toBe("kling-3.0:10s")
     })
 
     it('string duration "5" works', () => {
@@ -413,19 +427,19 @@ describe("buildVideoCreditModelIdentifier", () => {
     })
 
     it("NaN duration defaults to 5", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", "abc")).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", "abc", false)).toBe("kling-3.0:5s")
     })
 
     it("undefined duration defaults to 5", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0")).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", undefined, false)).toBe("kling-3.0:5s")
     })
 
     it("0 duration falls into first tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 0)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 0, false)).toBe("kling-3.0:5s")
     })
 
     it("1 duration falls into first tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 1)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 1, false)).toBe("kling-3.0:5s")
     })
   })
 

package/src/__tests__/image-ref-limit.test.ts

@@ -16,7 +16,9 @@ describe("imageReferenceLimit", () => {
     "flux-2-max": 8,
     "gpt-image-2": 16, // → gpt-image-2-i2i
     "seedream-5-lite": 16, // → seedream-5-lite-i2i
+    "seedream-5-pro": 16, // → seedream-5-pro-i2i
     "nano-banana-2": 4,
+    "nano-banana-2-lite": 10, // schema maxItems (image_urls)
     flux: 4, // → flux-pro-i2i
     "flux-2-klein": 1, // product cap (schema array slices at 5)
     "flux-2-pro": 4, // product cap (BFL schema accepts 8)

package/src/__tests__/llm-models.test.ts

@@ -430,20 +430,27 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "gemini-3.1-pro",
         "claude-sonnet-5",
         "claude-opus-4.8",
+        // responses-format GPTs — KIE text.format json_schema live-verified
+        // 2026-07-14 (text AND vision inputs).
+        "gpt-5.4",
+        "gpt-5.5",
+        "gpt-5.6-luna",
+        "gpt-5.6-terra",
+        "gpt-5.6-sol",
       ].sort(),
     )
   })
 
-  it("includes Anthropic (forced-tool) AND Gemini (response_format) vendors", () => {
+  it("includes Anthropic (forced-tool), Gemini (response_format), and OpenAI (responses text.format) vendors", () => {
     const vendors = new Set(STRUCTURED_VISION_MODELS.map((m) => m.vendor))
     expect(vendors).toContain("anthropic")
     expect(vendors).toContain("google")
+    expect(vendors).toContain("openai")
   })
 
-  it("excludes GPT models — no native structured mode (parse+retry only)", () => {
+  it("excludes chat-completions GPT models — no native structured mode there (parse+retry only)", () => {
     const ids = STRUCTURED_VISION_MODELS.map((m) => m.id)
     expect(ids).not.toContain("gpt-5.2")
-    expect(ids).not.toContain("gpt-5.4")
   })
 
   it("every member is vision-capable and has a structuredOutputMode", () => {

package/src/__tests__/prompt-length-limits.test.ts

@@ -28,6 +28,7 @@ describe("per-model prompt length limits", () => {
   describe("getMaxImagePromptChars", () => {
     it("returns the verified higher caps (provider supports more than 5000)", () => {
       expect(getMaxImagePromptChars("nano-banana-2")).toBe(20000)
+      expect(getMaxImagePromptChars("nano-banana-2-lite")).toBe(20000)
       expect(getMaxImagePromptChars("nano-banana-pro")).toBe(20000)
       expect(getMaxImagePromptChars("gpt-image-2-i2i")).toBe(20000)
     })
@@ -44,6 +45,8 @@ describe("per-model prompt length limits", () => {
     it("falls back to IMAGE_PROMPT_MAX for verified-default + unknown providers", () => {
       expect(getMaxImagePromptChars("flux")).toBe(IMAGE_PROMPT_MAX)
       expect(getMaxImagePromptChars("imagen4")).toBe(IMAGE_PROMPT_MAX)
+      expect(getMaxImagePromptChars("seedream-5-pro")).toBe(IMAGE_PROMPT_MAX) // verified 5000 in KIE schema
+      expect(getMaxImagePromptChars("seedream-5-pro-i2i")).toBe(IMAGE_PROMPT_MAX) // verified 5000 in KIE schema
       expect(getMaxImagePromptChars("grok-i2i")).toBe(IMAGE_PROMPT_MAX) // 390000 doc = sanity-capped
       expect(getMaxImagePromptChars("flux-kontext")).toBe(IMAGE_PROMPT_MAX) // UNVERIFIED
       expect(getMaxImagePromptChars(undefined)).toBe(IMAGE_PROMPT_MAX)

package/src/__tests__/seedance2-continuation-ref.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest"
+import {
+  SEEDANCE_2_CONTINUATION_REF_SEC,
+  SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC,
+  SEEDANCE_2_EXTEND_STITCH,
+} from "../model-constants.js"
+
+/** KIE hard-rejects r2v reference videos below the floor: "the parameter
+ *  video duration (seconds) specified in the request must be greater than or
+ *  equal to 1.8 for model dreamina-seedance-2-0-fast in r2v" (2026-07-13,
+ *  job dbf95612 — the original 1.0s tails made every generate-video-pro
+ *  continuation segment fail deterministically). Everything this platform
+ *  sends as a Seedance-2 video reference cuts SEEDANCE_2_CONTINUATION_REF_SEC
+ *  seconds; do NOT "optimize" it back below the floor. The private-plugin
+ *  twin constants (nodaro-cloud-plugins chain.ts TAIL_SEC / bridge-math.ts
+ *  MIN_REF) are guarded by that repo's r2v-ref-floor.test.ts — keep in sync. */
+describe("seedance-2 continuation-reference floor (do not regress)", () => {
+  it("the platform's continuation-ref length clears KIE's r2v minimum", () => {
+    expect(SEEDANCE_2_CONTINUATION_REF_SEC).toBeGreaterThanOrEqual(SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC)
+  })
+  it("the extend node's tail IS the shared continuation-ref length (single source)", () => {
+    expect(SEEDANCE_2_EXTEND_STITCH.referenceTailSeconds).toBe(SEEDANCE_2_CONTINUATION_REF_SEC)
+  })
+})

package/src/__tests__/video-analysis-pricing.test.ts

@@ -5,13 +5,16 @@ import {
   pickVideoAnalysisBucket, buildVideoAnalysisCreditId, bucketSecondsFromCreditId,
   videoAnalysisNumWindows,
 } from "../video-analysis-pricing.js"
-import { VIDEO_ANALYSIS_LLM_MODELS } from "../llm-models.js"
+import {
+  VIDEO_ANALYSIS_LLM_MODELS, VIDEO_ANALYSIS_TIERS, VIDEO_ANALYSIS_TIER_ORDER,
+  DEFAULT_VIDEO_ANALYSIS_TIER, DEFAULT_VIDEO_ANALYSIS_MODEL, resolveVideoAnalysisModel,
+} from "../llm-models.js"
 
 // The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
-// formula moved to backend/src/lib/pricing/video-analysis-cost.ts (S5) — its
-// tests (including the worked-example bucket-credit values and the
-// cross-check against VIDEO_ANALYSIS_BUCKET_CREDITS below) live in
-// backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts. This file
+// formula are PRIVATE, in @nodaroai/cloud-plugins
+// (src/plugins/video-analysis/cost.ts) — its tests (the worked-example
+// bucket-credit values and the cross-check against VIDEO_ANALYSIS_BUCKET_CREDITS
+// below) live in that private package's __tests__/cost.test.ts. This file
 // covers only the NON-monetary duration-bucketing, window-batching, and
 // credit-id-construction logic that stays in the published package.
 
@@ -40,6 +43,26 @@ describe("video-analysis-pricing", () => {
     expect(VIDEO_ANALYSIS_LLM_MODELS).toEqual(["gemini-3-flash", "gemini-3.1-pro"])
   })
 
+  it("tier layer: every tier maps to a real model AND every model is tier-reachable (no vendor leak)", () => {
+    // Adding a video-analysis model without a tier would silently leave it
+    // unreachable / unnamed — this fails until a tier decision is made.
+    const tierTargets = Object.values(VIDEO_ANALYSIS_TIERS)
+    for (const m of tierTargets) expect(VIDEO_ANALYSIS_LLM_MODELS).toContain(m)
+    for (const m of VIDEO_ANALYSIS_LLM_MODELS) expect(tierTargets).toContain(m)
+    expect(new Set(VIDEO_ANALYSIS_TIER_ORDER)).toEqual(new Set(Object.keys(VIDEO_ANALYSIS_TIERS)))
+  })
+
+  it("resolveVideoAnalysisModel: tier → model, raw model passthrough, default pro on empty/unknown", () => {
+    expect(DEFAULT_VIDEO_ANALYSIS_TIER).toBe("pro")
+    expect(DEFAULT_VIDEO_ANALYSIS_MODEL).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("pro")).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("fast")).toBe("gemini-3-flash")
+    expect(resolveVideoAnalysisModel("gemini-3-flash")).toBe("gemini-3-flash") // raw passthrough
+    expect(resolveVideoAnalysisModel(undefined)).toBe("gemini-3.1-pro") // default → pro
+    expect(resolveVideoAnalysisModel("")).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("nonsense")).toBe("gemini-3.1-pro") // unknown → default, never throws
+  })
+
   // Full drift-detection against the live $-formula lives in
   // backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts (this
   // package cannot see the formula post-S5). This is a lightweight shape

package/src/__tests__/video-analysis.test.ts

@@ -7,7 +7,7 @@ import {
 } from "../video-analysis.js"
 
 const slot: EntitySlot = { slotId: "hero", label: "Protagonist", source: "wired-character", role: "person", description: "tan man, mustache, black tee" }
-const baseScene = { startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} juggles a ball", audio: { mode: "speech" as const, content: "As a kid…", voice: "male, warm" } }
+const baseScene = { startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} juggles a ball", audio: [{ mode: "speech" as const, content: "As a kid…", voice: "male, warm" }] }
 
 describe("windowAnalysisSchema", () => {
   it("accepts a zero-scene window (quiet footage is a VALID result)", () => {

package/src/__tests__/video-audio-capability.test.ts

@@ -22,15 +22,33 @@ describe("getVideoAudioCapability", () => {
     }
   })
 
-  it("returns ambient (sound toggle, cost-affecting) for Kling", () => {
+  it("returns native_speech (sound toggle, cost-affecting) for KIE Kling", () => {
+    // Probe-verified 2026-07-16: scripted quoted dialogue comes back verbatim
+    // with articulated lips on the KIE path for BOTH kling (2.6) and kling-3.0.
     for (const m of ["kling", "kling-3.0"]) {
       const cap = getVideoAudioCapability(m)
-      expect(cap.mode, m).toBe("ambient")
+      expect(cap.mode, m).toBe("native_speech")
       expect(cap.field, m).toBe("sound")
       expect(cap.affectsCost, m).toBe(true)
     }
   })
 
+  it("returns native_speech (generateAudio lever, flat-priced) for kling-3-omni", () => {
+    const cap = getVideoAudioCapability("kling-3-omni")
+    expect(cap.mode).toBe("native_speech")
+    expect(cap.field).toBe("generateAudio")
+    // Audio is priced into the Replicate flat per-duration rate — no :audio composite.
+    expect(cap.affectsCost).toBeUndefined()
+    expect(cap.defaultOn).toBe(true)
+  })
+
+  it("defaultOn mirrors each model's own config default", () => {
+    // kling-3.0 generates audio unless explicitly disabled (models.ts
+    // extraParams.sound: true + kling3-client `?? true`); kling 2.6 defaults off.
+    expect(getVideoAudioCapability("kling-3.0").defaultOn).toBe(true)
+    expect(getVideoAudioCapability("kling").defaultOn).toBeUndefined()
+  })
+
   it("returns audio_driven for Seedance 2.0", () => {
     for (const m of ["seedance-2", "seedance-2-fast"]) {
       const cap = getVideoAudioCapability(m)
@@ -66,6 +84,7 @@ describe("videoModelSupportsAudio", () => {
   it("is true for any model with an audio mode, false for silent", () => {
     expect(videoModelSupportsAudio("veo3")).toBe(true)
     expect(videoModelSupportsAudio("kling-3.0")).toBe(true)
+    expect(videoModelSupportsAudio("kling-3-omni")).toBe(true)
     expect(videoModelSupportsAudio("seedance-2")).toBe(true)
     expect(videoModelSupportsAudio("seedance")).toBe(true)
     expect(videoModelSupportsAudio("minimax")).toBe(false)
@@ -80,9 +99,12 @@ describe("videoModelCanSpeakDialogue", () => {
     expect(videoModelCanSpeakDialogue("seedance-2")).toBe(true)
     expect(videoModelCanSpeakDialogue("seedance-2-fast")).toBe(true)
     expect(videoModelCanSpeakDialogue("seedance-2-mini")).toBe(true)
+    // Kling 2.6 / 3.0 / Omni speak scripted dialogue natively (probe-verified
+    // 2026-07-16) — the Story→Video auto-pick uses in-model speech + revoice.
+    expect(videoModelCanSpeakDialogue("kling")).toBe(true)
+    expect(videoModelCanSpeakDialogue("kling-3.0")).toBe(true)
+    expect(videoModelCanSpeakDialogue("kling-3-omni")).toBe(true)
     // ambient-only models are NOT dialogue-capable — their audio is SFX/ambient
-    expect(videoModelCanSpeakDialogue("kling")).toBe(false)
-    expect(videoModelCanSpeakDialogue("kling-3.0")).toBe(false)
     expect(videoModelCanSpeakDialogue("seedance")).toBe(false)
     expect(videoModelCanSpeakDialogue("minimax")).toBe(false)
     expect(videoModelCanSpeakDialogue(undefined)).toBe(false)
@@ -101,10 +123,16 @@ describe("seedance-2-mini is a full Seedance 2 family member", () => {
 })
 
 describe("VIDEO_AUDIO_CAPABILITY internal consistency", () => {
-  it("every Kling AUDIO_ADDON provider is ambient + affectsCost", () => {
+  it("every AUDIO_ADDON provider is cost-affecting on the canonical `sound` lever", () => {
+    // The billing-critical invariant: the `:audio` surcharge keys off `sound`,
+    // so every surcharged model must declare audio, be marked cost-affecting,
+    // and carry its toggle on that exact field (applyVideoAudioToggle then
+    // refuses the generateAudio alias for these, making a billed/generated
+    // divergence structurally impossible).
     for (const m of AUDIO_ADDON_PROVIDERS) {
       const cap = getVideoAudioCapability(m)
-      expect(cap.mode, m).toBe("ambient")
+      expect(cap.mode, m).not.toBe("none")
+      expect(cap.field, m).toBe("sound")
       expect(cap.affectsCost, m).toBe(true)
     }
   })

package/src/credit-identifiers.ts

@@ -18,6 +18,7 @@ import {
   MOTION_DURATION_TIERS,
   T2I_TO_I2I_VARIANT,
   isVeoProvider,
+  getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model } from "./flux2-pricing.js"
 import { MODEL_CATALOG } from "./model-catalog.js"
@@ -227,8 +228,13 @@ export function buildVideoCreditModelIdentifier(
   const tier = tiers.find(t => durationSec <= t.maxSeconds) ?? tiers[tiers.length - 1]
   let identifier = `${effectiveProvider}:${tier.suffix}`
 
-  // Append audio suffix if applicable
-  if (AUDIO_ADDON_PROVIDERS.has(effectiveProvider) && sound) {
+  // Append audio suffix if applicable. When the caller expressed no intent
+  // (sound === undefined), fall back to the model's own default (capability
+  // `defaultOn` — kling-3.0 generates audio unless explicitly disabled), so an
+  // intent-less request is billed for the audio it actually produces instead
+  // of reserving the cheaper no-audio tier against an audio-on generation.
+  const soundOn = sound ?? (getVideoAudioCapability(effectiveProvider).defaultOn === true)
+  if (AUDIO_ADDON_PROVIDERS.has(effectiveProvider) && soundOn) {
     identifier += ":audio"
   }
 

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   getMaxImagePromptChars,
   PROMPT_HARD_CEILING,
+  LLM_TEXT_INPUT_MAX,
   MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER,
   getMaxVideoPromptChars,
   NEGATIVE_PROMPT_MAX,
@@ -95,6 +96,8 @@ export {
   SEEDANCE_2_PROVIDERS,
   SEEDANCE_2_REF_LIMITS,
   SEEDANCE_2_EXTEND_STITCH,
+  SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC,
+  SEEDANCE_2_CONTINUATION_REF_SEC,
   NATIVE_ADAPTIVE_ASPECT,
   VIDEO_REF_LIMITS_BY_PROVIDER,
   VIDEO_PROVIDERS_REQUIRING_IMAGE,
@@ -250,6 +253,14 @@ export {
   LLM_MODEL_IDS,
   STRUCTURED_VISION_MODELS,
   VIDEO_ANALYSIS_LLM_MODELS,
+  VIDEO_ANALYSIS_TIERS,
+  type VideoAnalysisTier,
+  VIDEO_ANALYSIS_TIER_ORDER,
+  DEFAULT_VIDEO_ANALYSIS_TIER,
+  DEFAULT_VIDEO_ANALYSIS_MODEL,
+  VIDEO_ANALYSIS_TIER_LABELS,
+  isVideoAnalysisTier,
+  resolveVideoAnalysisModel,
   LLM_FEATURE_DEFAULTS,
   LLM_MODALITY_CAPS,
   LLM_REASONING_EFFORTS,

package/src/llm-models.ts

@@ -37,14 +37,18 @@ export interface LlmModelDef {
   maxOutputTokens: number
   /**
    * How this model can be forced into schema-valid structured output.
-   * - "anthropic-tool"       → direct Anthropic SDK forced tool_choice (guaranteed).
-   * - "kie-response-format"  → KIE chat-completions `response_format: json_schema`
-   *                            (verified enforced for Gemini via KIE).
-   * - undefined              → no native structured mode (GPT-via-KIE doesn't honor
-   *                            response_format); callers fall back to parse + retry.
+   * - "anthropic-tool"          → forced tool_choice on the Claude wire (direct SDK
+   *                               guaranteed; KIE's proxy re-serializes the tool call
+   *                               as a `<tool_calls>` text tag — decoded in llm-client).
+   * - "kie-response-format"     → KIE chat-completions `response_format: json_schema`
+   *                               (verified enforced for Gemini via KIE).
+   * - "responses-json-schema"   → KIE codex/v1/responses `text.format: json_schema`
+   *                               (live-verified 2026-07-14 for gpt-5.4/5.5 and the
+   *                               whole GPT-5.6 family, text AND vision inputs).
+   * - undefined                 → no native mode; callers fall back to parse + retry.
    * Capability-driven so `llmCompleteStructured` never hardcodes provider ids.
    */
-  structuredOutputMode?: "anthropic-tool" | "kie-response-format"
+  structuredOutputMode?: "anthropic-tool" | "kie-response-format" | "responses-json-schema"
   /** If set, fallback to direct Anthropic SDK with this model ID when KIE.ai fails */
   directFallbackModel?: string
   /** Effort levels this model accepts (ascending). Absent/empty = no effort lever, picker hidden. */
@@ -142,6 +146,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-4",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
     supportsImages: true,
     maxOutputTokens: 16384,
     reasoningEfforts: ["low", "medium", "high"],
@@ -154,6 +159,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-5",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
     supportsImages: true,
     maxOutputTokens: 16384,
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -167,6 +173,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-6-luna",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
     supportsImages: true,
     maxOutputTokens: 16384,
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -180,6 +187,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-6-terra",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
     supportsImages: true,
     maxOutputTokens: 16384,
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -193,6 +201,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-6-sol",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
     supportsImages: true,
     maxOutputTokens: 16384,
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
@@ -238,9 +247,10 @@ export const LLM_MODEL_IDS = LLM_MODELS.map((m) => m.id)
 /** Vision models that can return GUARANTEED structured output — the
  *  describe-to-picker analyzer forces a schema over an image, so its model
  *  pickers AND the backend route gate offer exactly these: Anthropic (forced
- *  tool) + Gemini (KIE `response_format`). GPT-via-KIE has no native structured
- *  mode (parse+retry only), so it's excluded. Single source of truth so the
- *  picker, the config panel, and the route gate can't drift. */
+ *  tool), Gemini (KIE `response_format`), and GPT responses-format models
+ *  (KIE `text.format` json_schema — vision+schema live-verified 2026-07-14).
+ *  Single source of truth so the picker, the config panel, and the route gate
+ *  can't drift. */
 export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
   (m) => m.supportsImages && m.structuredOutputMode != null,
 )
@@ -376,3 +386,36 @@ export function resolveLlmCreditId(feature: string, body: unknown): string {
 export const VIDEO_ANALYSIS_LLM_MODELS: string[] = LLM_MODELS
   .filter((m) => getLlmModalityCaps(m.id).video && getLlmModalityCaps(m.id).audio)
   .map((m) => m.id)
+
+/**
+ * Video-analysis quality TIERS — the ONLY analyzer identifiers exposed to users
+ * (API, UI, docs). Each maps to an internal analysis model; the underlying
+ * vendor/model name is never surfaced. Default is `pro`. The guard test
+ * (video-analysis-pricing.test.ts) asserts every tier target is a real
+ * VIDEO_ANALYSIS_LLM_MODELS member AND every such model is reachable by a tier,
+ * so adding a video model forces a tier decision instead of silently leaking.
+ */
+export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3-flash", pro: "gemini-3.1-pro" } as const
+export type VideoAnalysisTier = keyof typeof VIDEO_ANALYSIS_TIERS
+/** UI/listing order — recommended (pro) first. */
+export const VIDEO_ANALYSIS_TIER_ORDER = ["pro", "fast"] as const
+export const DEFAULT_VIDEO_ANALYSIS_TIER: VideoAnalysisTier = "pro"
+export const DEFAULT_VIDEO_ANALYSIS_MODEL: string = VIDEO_ANALYSIS_TIERS[DEFAULT_VIDEO_ANALYSIS_TIER]
+/** Neutral, vendor-free display labels for the UI. */
+export const VIDEO_ANALYSIS_TIER_LABELS: Record<VideoAnalysisTier, string> = { fast: "Fast", pro: "Pro" }
+
+export function isVideoAnalysisTier(v: string): v is VideoAnalysisTier {
+  return Object.prototype.hasOwnProperty.call(VIDEO_ANALYSIS_TIERS, v)
+}
+
+/**
+ * Resolve a user-supplied tier (`"fast"`/`"pro"`) OR a raw internal model id to
+ * the internal analysis model id. Empty/unknown → the default tier's model.
+ * Real model ids pass through (back-compat for existing stored `llmModel`
+ * values); anything else falls back to the default rather than erroring.
+ */
+export function resolveVideoAnalysisModel(input?: string | null): string {
+  if (input && isVideoAnalysisTier(input)) return VIDEO_ANALYSIS_TIERS[input]
+  if (input && VIDEO_ANALYSIS_LLM_MODELS.includes(input)) return input
+  return DEFAULT_VIDEO_ANALYSIS_MODEL
+}

package/src/model-catalog.ts

@@ -146,7 +146,7 @@ export const MODEL_RECOMMENDATIONS: readonly ModelRecommendation[] = [
   { intent: "best for typography / logos / text-heavy", modelIds: ["nano-banana-pro", "gpt-image-2"], note: "Nano Banana Pro for diagrams / complex text; GPT Image 2 for logos and short copy." },
   { intent: "cheapest realistic image", modelIds: ["z-image", "qwen", "imagen4-fast"], note: "Z-Image is the cheapest at 1 credit. 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-lite-i2i"], note: "Flux Kontext preserves identity; Ideogram Remix is character-aware; Seedream 5 Lite for instruction-based edits." },
+  { 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: "background removal / cutout", modelIds: ["recraft-remove-bg"], note: "1 credit, no prompt needed." },
   // video
@@ -165,6 +165,11 @@ export const MODEL_RECOMMENDATIONS: readonly ModelRecommendation[] = [
 // can consume them. Keep in sync when adding a new ratio set.)
 // =============================================================================
 const NANO_BANANA_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9"] as const
+// Nano Banana 2 Lite only — the model's full documented enum incl. `auto`
+// (native default) and extreme banner ratios (docs.kie.ai/market/google/
+// nano-banana-2-lite). Kept separate so the wider set can't leak to the
+// rest of the family.
+const NANO_BANANA_2_LITE_RATIOS = ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "4:1", "1:4", "8:1", "1:8"] as const
 // Note: these arrays are synchronized with the frontend's
 // `model-options.ts` constants of the same names. The frontend now imports
 // them via the `getAspectRatioOptions(modelId)` helper; if you update one
@@ -233,6 +238,22 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "nano-banana-2:4K", credits: 5, note: "4K" },
     ],
   },
+  "nano-banana-2-lite": {
+    id: "nano-banana-2-lite",
+    kind: "image",
+    // Same single-id shape as nano-banana-2: optional input images on the one
+    // endpoint (via image_urls, up to 10), so reachable for both t2i and i2i.
+    modes: ["t2i", "i2i"] as const,
+    family: "Google",
+    label: "Nano Banana 2 Lite",
+    series: "Nano Banana",
+    description: "Lightweight Nano Banana 2 (Gemini 3.1 Flash-Lite) — fast, low-cost 1K generation and editing.",
+    useCases: ["realistic", "drafts", "iteration"],
+    features: ["reference-image"],
+    aspectRatios: NANO_BANANA_2_LITE_RATIOS,
+    // 1K only — no resolution lever, flat pricing.
+    pricing: [{ identifier: "nano-banana-2-lite", credits: 2, note: "1K flat" }],
+  },
   "nano-banana-pro": {
     id: "nano-banana-pro",
     kind: "image",
@@ -691,6 +712,40 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "seedream-5-lite-i2i:high", credits: 5, note: "high quality" },
     ],
   },
+  "seedream-5-pro": {
+    id: "seedream-5-pro",
+    kind: "image",
+    modes: ["t2i"] as const,
+    family: "Bytedance",
+    label: "Seedream 5 Pro",
+    series: "Seedream",
+    description: "Flagship Seedream 5 Pro — strongest instruction following and visual reasoning. Basic = 1K, high = 2K.",
+    useCases: ["realistic", "instruction"],
+    features: ["reference-image"],
+    aspectRatios: SEEDREAM_RATIOS,
+    qualities: ["basic", "high"],
+    pricing: [
+      { identifier: "seedream-5-pro", credits: 3, note: "basic / 1K default" },
+      { identifier: "seedream-5-pro:high", credits: 6, note: "high / 2K" },
+    ],
+  },
+  "seedream-5-pro-i2i": {
+    id: "seedream-5-pro-i2i",
+    kind: "image",
+    modes: ["i2i"] as const,
+    family: "Bytedance",
+    label: "Seedream 5 Pro (I2I)",
+    series: "Seedream",
+    description: "Image-to-image with Seedream 5 Pro — multi-reference instruction edits. Basic = 1K, high = 2K.",
+    useCases: ["edit", "instruction"],
+    features: ["reference-image"],
+    aspectRatios: SEEDREAM_RATIOS,
+    qualities: ["basic", "high"],
+    pricing: [
+      { identifier: "seedream-5-pro-i2i", credits: 3, note: "basic / 1K default" },
+      { identifier: "seedream-5-pro-i2i:high", credits: 6, note: "high / 2K" },
+    ],
+  },
 
   // ── Alibaba Qwen ──
   "qwen": {
@@ -1754,10 +1809,10 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     id: "gemini-3-flash-video-analysis",
     kind: "video",
     modes: ["video-analysis"] as const,
-    family: "Google",
-    label: "Video Analysis (Gemini 3 Flash)",
-    series: "Gemini",
-    description: "Analyze a video into a structured shot list (scenes, camera, audio) — fast Gemini tier. Billed per duration bucket.",
+    family: "Nodaro",
+    label: "Video Analysis (Fast)",
+    series: "Video Analysis",
+    description: "Analyze a video into a structured shot list (scenes, camera, audio) — fast, economy tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
       { identifier: "video-analysis:gemini-3-flash", credits: 3, note: "10-min ceiling (no duration given)" },
@@ -1771,10 +1826,10 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     id: "gemini-3.1-pro-video-analysis",
     kind: "video",
     modes: ["video-analysis"] as const,
-    family: "Google",
-    label: "Video Analysis (Gemini 3.1 Pro)",
-    series: "Gemini",
-    description: "Analyze a video into a structured shot list (scenes, camera, audio) — high-fidelity Gemini tier. Billed per duration bucket.",
+    family: "Nodaro",
+    label: "Video Analysis (Pro)",
+    series: "Video Analysis",
+    description: "Analyze a video into a structured shot list (scenes, camera, audio) — higher-fidelity, default tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "cinematic"],
     pricing: [
       { identifier: "video-analysis:gemini-3.1-pro", credits: 11, note: "10-min ceiling (no duration given)" },