@slatesvideo/shared 0.5.10 → 0.6.1

package/dist/operations/index.d.ts

@@ -29,7 +29,7 @@ export declare const getCreditBalance: Operation<Record<string, never>>;
 export declare const listAvailableModels: Operation<{
     filter?: string;
 }>;
-export declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2", "seedance-2.5", "omni-flash"];
+export declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2", "seedance-2.5", "omni-flash", "minimax-h3", "minimax-h3-max"];
 type VideoModel = (typeof VIDEO_MODELS)[number];
 /** The exact `model` ids `slates_edit_video` accepts. Edit rows are deliberately
  *  NOT in VIDEO_MODELS — they take a source clip, not frames. */
@@ -39,12 +39,15 @@ export declare const estimateGenerationCost: Operation<{
     model: string;
     quantity?: number;
     duration?: number;
-    videoResolution?: '480p' | '720p' | '1080p' | '4k';
+    /** The FULL union — the runtime Zod enum is generated from MODEL_CAPABILITIES
+     *  and `assertVideoCapabilities` is the per-model narrowing authority. */
+    videoResolution?: VideoResolution;
     resolution?: '1k' | '2k' | '3k' | '4k';
     quality?: 'medium' | 'high';
     sound?: boolean;
     seedanceFace?: boolean;
     seedanceRealFace?: boolean;
+    referenceImages?: number;
 }>;
 export declare const listProjects: Operation<Record<string, never>>;
 export declare const createProject: Operation<{
@@ -193,7 +196,9 @@ export declare const editImage: Operation<{
 export declare function videoCostKey(input: {
     model: VideoModel;
     duration: number;
-    videoResolution?: '480p' | '720p' | '1080p' | '4k';
+    /** Widened to the full union because the Zod enum is GENERATED from
+     *  MODEL_CAPABILITIES; the runtime schema is the narrowing authority. */
+    videoResolution?: VideoResolution;
     sound?: boolean;
     seedanceFace?: boolean;
     seedanceRealFace?: boolean;
@@ -201,6 +206,11 @@ export declare function videoCostKey(input: {
      *  transfer / lip-sync on video / relocate). >0 bills the vref key on TOTAL
      *  (input+output) seconds — the server re-derives this by probing the refs. */
     videoRefSeconds?: number;
+    /** MiniMax H3 base only: how many reference IMAGES the request carries. Past
+     *  the fifth, fal charges per image, so it is a KEY DIMENSION — omit it on a
+     *  reference-heavy call and the quote under-reports what the proxy bills
+     *  (which it re-derives from the request itself). */
+    referenceImages?: number;
 }): string;
 export declare function klingEditCostKey(model: 'kling-v3.0-omni-edit' | 'kling-v3.0-omni-pro-edit', duration: number): string;
 export declare function omniFlashEditCostKey(duration: number): string;
@@ -211,7 +221,9 @@ export declare const SEEDANCE_25_EDIT_MIN_SECONDS: number;
 export declare const SEEDANCE_25_EDIT_MAX_SECONDS: number;
 export declare function seedanceEditCostKey(input: {
     duration: number;
-    videoResolution?: '480p' | '720p';
+    /** Widened to the full union because the Zod enum is GENERATED from
+     *  MODEL_CAPABILITIES; the runtime schema is the narrowing authority. */
+    videoResolution?: VideoResolution;
     seedanceFace?: boolean;
     seedanceRealFace?: boolean;
 }): string;

package/dist/operations/index.js

@@ -172,11 +172,24 @@ export const VIDEO_MODELS = [
     'veo-3.1-standard',
     'seedance-2',
     // Seedance 2.5 is a SECOND SEAT, not a replacement: 30s takes, 30 image
-    // references, audio-only references — and 480p/720p ONLY. 2.0 keeps the
-    // ladder to native 4K and stays the default. Its EDIT row is not here; edit
-    // models live on slates_edit_video, same as the Kling and Omni Flash ones.
+    // references, audio-only references, up to 1080p (2026-08-24) — but no 4K,
+    // and dearer than 2.0 at every shared tier, so 2.0 stays the default. Its
+    // EDIT row is not here; edit models live on slates_edit_video, same as the
+    // Kling and Omni Flash ones.
     'seedance-2.5',
     'omni-flash',
+    // MiniMax H3, two seats in one family (2026-08-27). Base H3 is the AUTHORED-
+    // AUDIO seat — three directable sound layers in one pass, declared reference
+    // relationships, 480p to 4K, and the cheapest 768-class second we sell.
+    // H3 Max is fal's self-hosted post-train: faster, capped at 768p, takes NO
+    // references, and costs MORE than base H3 at the tier they share — a
+    // premium-speed seat, never a cheap H3.
+    //
+    // NEVER PREFIX-MATCH: 'minimax-h3-max' starts with 'minimax-h3'. Every
+    // branch keyed on these ids matches EXACTLY; a prefix test silently bills
+    // the Max row at base rates and offers it 2K/4K it cannot render.
+    'minimax-h3',
+    'minimax-h3-max',
 ];
 // ── Capability-derived param vocabulary + guard ─────────────────
 //
@@ -193,6 +206,51 @@ const VIDEO_RESOLUTIONS = videoResolutionUnion(VIDEO_MODELS);
 const VIDEO_DURATION_BOUNDS = durationBounds(VIDEO_MODELS);
 /** Omni Flash's combined reference-image cap, read from the SSOT (7). */
 const omniFlashRefCap = getModelCapability('omni-flash')?.maxIngredientImages ?? 0;
+/** Every resolution token any video model speaks, for the forgiving cost-key
+ *  parser. Derived, so 768p and 2k arrived with the models rather than with a
+ *  later bug report. */
+const VIDEO_RESOLUTION_VOCAB = VIDEO_RESOLUTIONS;
+// ── MiniMax H3: the reference-image surcharge, as a KEY DIMENSION ────────────
+//
+// fal charges $0.080 per reference image PAST THE FIRST FIVE on
+// `minimax/h3/reference-to-video`, and nowhere else — not on image-to-video
+// start/end frames (those are FL2VA inputs, not Ref2VA references), and not on
+// h3-max, which has no reference endpoint at all. Left unmodelled it inverts
+// the margin: a 10s 768p clip earns $0.30 and four extra images cost $0.32.
+//
+// `/proxy/generate` resolves ONE key to ONE integer, so a surcharge has to live
+// IN the key — exactly the shape Kling's `-audio` suffix uses. The bare key
+// stays identical to every other model's; the suffix appears only when the
+// option costs money.
+//
+// The rounding is EXACT and worth knowing before anyone changes the rate:
+// $0.080 x 1.5 x 100 = 12 cents, and 12 is divisible by CENTS_PER_CREDIT (3),
+// so every extra image is 4 credits at every resolution and every duration with
+// zero drift. A rate that is not a multiple of 2 cents breaks that property.
+const MINIMAX_MODELS = new Set(['minimax-h3', 'minimax-h3-max']);
+/** Reference images fal does not charge for. */
+const MINIMAX_FREE_REF_IMAGES = 5;
+/** K for the `-ref{K}` suffix: images past the free five, capped by the model's
+ *  own declared ceiling. 0 for h3-max (no reference transport) and for anything
+ *  that is not a MiniMax row. Mirrors refImageSurchargeCount() in
+ *  slate/src/shared/pricing.ts. */
+/** Reference IMAGES a generate_video call carries — the four free-reference
+ *  arrays, combined, exactly as the desktop composer counts them. */
+function minimaxRefImageCount(input) {
+    return ((input.ingredientAssetIds?.length ?? 0) +
+        (input.characterAssetIds?.length ?? 0) +
+        (input.environmentAssetIds?.length ?? 0) +
+        (input.styleAssetIds?.length ?? 0));
+}
+function minimaxRefSurchargeCount(model, referenceImages) {
+    if (!MINIMAX_MODELS.has(model))
+        return 0;
+    const cap = getModelCapability(model)?.maxIngredientImages ?? 0;
+    const n = Math.floor(referenceImages ?? 0);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.max(0, Math.min(n, cap) - MINIMAX_FREE_REF_IMAGES);
+}
 /** The exact `model` ids `slates_edit_video` accepts. Edit rows are deliberately
  *  NOT in VIDEO_MODELS — they take a source clip, not frames. */
 export const EDIT_VIDEO_MODELS = [
@@ -236,6 +294,7 @@ export const estimateGenerationCost = {
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
         seedanceRealFace: z.boolean().optional().describe('Seedance consented real-face route (premium key).'),
+        referenceImages: z.number().int().min(0).optional().describe(`minimax-h3 only — how many reference IMAGES the generation will carry. The first ${MINIMAX_FREE_REF_IMAGES} are free and each one after that is a paid dimension of the cost key, so a quote that omits this UNDER-REPORTS a reference-heavy job. Ignored by every other model — including minimax-h3-max, which has no reference endpoint (its start/end frames are free and are not reference images).`),
     }),
     async run(input, ctx) {
         const registry = await ctx.cloud().get('/api/agent/models');
@@ -324,13 +383,15 @@ export const estimateGenerationCost = {
                     videoResolution: input.videoResolution ??
                         resolved.videoResolution ??
                         // Seedance quotes are resolution-scaled, so a missing resolution has
-                        // to fall back to the model's OWN default — 2.5 has no 1080p at all,
-                        // and a blanket '1080p' here quoted a key that does not exist. Read
-                        // from the SSOT; this used to be a hand-typed model-id ternary.
+                        // to fall back to the model's OWN default — the ladders differ per
+                        // row (2.5 has no 4K) and a blanket literal quotes a key that does
+                        // not exist. Read from the SSOT; this used to be a hand-typed
+                        // model-id ternary.
                         defaultVideoResolutionFor(resolved.model),
                     sound: input.sound ?? resolved.sound,
                     seedanceFace: input.seedanceFace ?? resolved.seedanceFace,
                     seedanceRealFace: input.seedanceRealFace,
+                    referenceImages: input.referenceImages ?? resolved.referenceImages,
                 });
             }
         }
@@ -1500,6 +1561,13 @@ const KLING_TIER_MAP = {
 // Exported for scripts/pricing-consistency-check.mjs (slates-api repo), which
 // asserts this builder byte-matches the desktop's klingCreditKey/seedanceCreditKey.
 export function videoCostKey(input) {
+    // EXACT-ID MAP, NEVER A PREFIX: 'minimax-h3-max' starts with 'minimax-h3'.
+    // Mirrors minimaxCreditKey() in slate/src/shared/pricing.ts.
+    if (MINIMAX_MODELS.has(input.model)) {
+        const res = input.videoResolution ?? defaultVideoResolutionFor(input.model);
+        const k = minimaxRefSurchargeCount(input.model, input.referenceImages);
+        return `${input.model}-${res}-${input.duration}s${k > 0 ? `-ref${k}` : ''}`;
+    }
     if (input.model.startsWith('seedance')) {
         // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (version × face
         // × vref × res × duration). AI-face route bills the `-face-` key (~45% over
@@ -1507,10 +1575,11 @@ export function videoCostKey(input) {
         // (fal partner endpoint). A reference video flips to `-vref-{res}-{T}s`,
         // T = in + out.
         //
-        // ⚠️ EVERY BOUND HERE IS VERSION-SCOPED. 2.5 is 480p/720p only, runs to 30s,
-        // and takes references to 30s combined — so its vref total reaches 60, DOUBLE
-        // 2.0's ceiling of 30. Clamping a 2.5 quote at 30 would quote a real key at a
-        // fraction of the real bill.
+        // ⚠️ EVERY BOUND HERE IS VERSION-SCOPED. 2.5 runs 480p/720p/1080p (no 4K),
+        // reaches 30s, and takes references to 30s combined — so its vref total
+        // reaches 60, DOUBLE 2.0's ceiling of 30. Clamping a 2.5 quote at 30 would
+        // quote a real key at a fraction of the real bill. The ladder itself lives in
+        // MODEL_CAPABILITIES; only the per-version DEFAULT is stated below.
         const v25 = input.model.startsWith('seedance-2.5');
         const res = input.videoResolution ?? (v25 ? '720p' : '1080p');
         const face = input.seedanceRealFace ? '-realface' : input.seedanceFace ? '-face' : '';
@@ -1670,10 +1739,22 @@ function resolveVideoModel(raw) {
         out.duration = parseInt(dur[1], 10);
         s = s.replace(/-(\d+)s\b/, '');
     }
-    const res = /-(480p|720p|1080p|4k)\b/.exec(s);
+    // MiniMax H3's paid-reference suffix, stripped like every other key dimension
+    // so a pasted `minimax-h3-768p-10s-ref2` resolves instead of erroring. The
+    // number it carries is K (images PAST the free five), so it is converted back
+    // to a TOTAL before anything can re-surcharge it.
+    const ref = /-ref(\d+)\b/.exec(s);
+    if (ref) {
+        out.referenceImages = MINIMAX_FREE_REF_IMAGES + parseInt(ref[1], 10);
+        s = s.replace(/-ref(\d+)\b/, '');
+    }
+    // The RESOLUTION vocabulary is GENERATED from MODEL_CAPABILITIES — the
+    // hand-typed list that stood here went stale the day 768p and 2k shipped.
+    const resRe = new RegExp(`-(${VIDEO_RESOLUTION_VOCAB.join('|')})\\b`);
+    const res = resRe.exec(s);
     if (res) {
         out.videoResolution = res[1];
-        s = s.replace(/-(480p|720p|1080p|4k)\b/, '');
+        s = s.replace(resRe, '');
     }
     if (/-audio\b/.test(s)) {
         out.sound = true;
@@ -1712,6 +1793,19 @@ function resolveVideoModel(raw) {
         'gemini-omni-flash': 'omni-flash',
         'gemini-omni-flash-preview': 'omni-flash',
         'omni-flash-preview': 'omni-flash',
+        // The MAX spellings must come out as MAX. Bare `minimax`, `h3` and
+        // `hailuo-3` all mean the BASE row — it holds the full ladder and the
+        // references, and it is cheaper at the tier they share.
+        'minimax-h3-max': 'minimax-h3-max',
+        'minimax-h3max': 'minimax-h3-max',
+        'h3-max': 'minimax-h3-max',
+        'hailuo-3-max': 'minimax-h3-max',
+        minimax: 'minimax-h3',
+        'minimax-h3': 'minimax-h3',
+        h3: 'minimax-h3',
+        'hailuo-3': 'minimax-h3',
+        'hailuo-3.0': 'minimax-h3',
+        hailuo: 'minimax-h3',
     };
     if (aliases[s]) {
         out.model = aliases[s];
@@ -1737,19 +1831,24 @@ function promptingSkillFor(model) {
         return 'slates-prompting-seedance';
     if (model.startsWith('omni-flash'))
         return 'slates-prompting-omni-flash';
+    // ONE skill covers both H3 seats — the prompt grammar is identical and only
+    // the ladder and the reference transport differ — so a prefix is right here.
+    if (model.startsWith('minimax-h3'))
+        return 'slates-prompting-minimax-h3';
     return 'slates-cost-discipline';
 }
 export const generateVideo = {
     id: 'slates_generate_video',
-    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (slates-prompting-seedance / slates-prompting-seedance-2-5 / slates-prompting-kling-v3 / slates-prompting-veo-3) — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8").',
+    description: 'Generate video via Slates credits. REQUIRED before calling: read slates-model-selection (the routing doctrine), slates-cost-discipline, and the matching per-model prompting skill (slates-prompting-seedance / slates-prompting-seedance-2-5 / slates-prompting-kling-v3 / slates-prompting-veo-3 / slates-prompting-minimax-h3) — video models prompt very differently; load them via slates_get_prompting_guide if no skill files are installed. Read slates-content-policy when the scene involves conflict, creatures, crowds, destruction, weapons, or young characters. projectId, aspectRatio, and duration are required (requires_clarification otherwise). Cost > $0.50 returns requires_confirm — pass confirm=true after explicit user OK. Image-to-video via firstFrameAssetId; first+last frames = Veo/Seedance only; ingredients via ingredientAssetIds (Kling Omni / Seedance). Asset params take UUIDs or badge codes ("IMG-A8").',
     input: z.object({
         prompt: z.string().min(1).max(4000),
         // ROUTING doctrine only. Every capability number was stripped on 2026-08-16
         // and now lives in the aspectRatio / duration / videoResolution descriptions
         // below, generated from MODEL_CAPABILITIES. "Veo = 16:9 only" and
         // "seedance-2.5 480p/720p" were both stated here AND there, and the two
-        // copies disagreed.
-        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate params (registry cost keys like "kling-v3-standard-8s" auto-resolve). Route per the slates-model-selection skill: Kling std = general-purpose DEFAULT, Seedance 2 = premium physics/effects/hero tier, seedance-2.5 = a SECOND SEAT beside it (longer takes, far more references, audio-only refs — but no 1080p or 4K, so stay on seedance-2 whenever resolution matters), Veo = native-synced-audio niche only, never the default, omni-flash = cheap tier with audio included (t2v, single-start-frame i2v, or reference images; no last frame, no video/audio refs). All are VIDEO-only. Each model's legal aspect ratios, durations and resolutions are in those params' own descriptions — read them there, not from memory. For per-call cost, call slates_estimate_generation_cost.`),
+        // copies disagreed — and the second of those went stale on 2026-08-24 when
+        // 2.5 gained 1080p, which is exactly the failure mode generating it fixes.
+        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate params (registry cost keys like "kling-v3-standard-8s" auto-resolve). Route per the slates-model-selection skill: Kling std = general-purpose DEFAULT, Seedance 2 = premium physics/effects/hero tier, seedance-2.5 = a SECOND SEAT beside it (longer takes, far more references, audio-only refs — but no 4K, and dearer than seedance-2 at every shared resolution, so stay on seedance-2 unless length or reference count is the point), Veo = native-synced-audio niche only, never the default, omni-flash = cheap tier with audio included (t2v, single-start-frame i2v, or reference images; no last frame, no video/audio refs), minimax-h3 = the AUTHORED-AUDIO seat (dialogue, scene sound and score directed as three separate layers in one pass, plus declared reference relationships; reference images past the fifth are a PAID key dimension — pass referenceImages when quoting), minimax-h3-max = the same model post-trained by fal for SPEED, capped at 768p, and DEARER than minimax-h3 at the tier they share — a deliberate pick, never a default and never the cheap H3; it still takes firstFrameAssetId/lastFrameAssetId, but has no reference endpoint, so the reference set is minimax-h3 only. All are VIDEO-only. Each model's legal aspect ratios, durations and resolutions are in those params' own descriptions — read them there, not from memory. For per-call cost, call slates_estimate_generation_cost.`),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Strongly recommended — the desktop UI shows a progress card live and the asset appears when complete.'),
         // 🚨 THESE THREE DESCRIPTIONS ARE GENERATED FROM `MODEL_CAPABILITIES`.
         // Never hand-write a ratio, resolution or duration into them again — every
@@ -1874,6 +1973,78 @@ export const generateVideo = {
                 });
             }
         }
+        // MiniMax H3's SHAPE constraints. Counts and caps are read from the
+        // capability SSOT; only the endpoint SHAPE is stated here, because it is
+        // not a number the registry models: fal publishes text-to-video,
+        // image-to-video and reference-to-video for `minimax/h3`, and only the
+        // first two for `minimax/h3-max` (its reference-to-video 404s). The
+        // reference endpoint has no frame parameters at all, so frames and
+        // references are mutually exclusive — a shape mismatch, not a preference.
+        if (MINIMAX_MODELS.has(input.model)) {
+            const cap = getModelCapability(input.model);
+            const refImages = minimaxRefImageCount(input);
+            const refMedia = (input.videoReferenceAssetIds?.length ?? 0) +
+                (input.audioReferenceAssetIds?.length ?? 0) +
+                (input.videoReferenceAssetId ? 1 : 0) +
+                (input.audioReferenceAssetId ? 1 : 0);
+            const maxImages = cap?.maxIngredientImages ?? 0;
+            const maxVideos = cap?.maxReferenceVideos ?? 0;
+            const maxAudio = cap?.maxReferenceAudio ?? 0;
+            const maxTotal = cap?.maxReferenceFilesTotal ?? 0;
+            if (maxImages === 0 && (refImages > 0 || refMedia > 0)) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes a prompt and up to two frames (start and/or end) — it has no reference endpoint at all, so reference images, video and audio cannot be sent. Drop them, or switch to minimax-h3, which reads ${getModelCapability('minimax-h3')?.maxIngredientImages ?? 9} images plus reference video and audio.`,
+                });
+            }
+            if ((refImages > 0 || refMedia > 0) && (input.firstFrameAssetId || input.lastFrameAssetId)) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} can use first/last frames OR references, not both — they are different endpoints and the reference one has no frame slots. Drop one side.`,
+                });
+            }
+            if (refImages > maxImages) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxImages} reference images combined (you passed ${refImages}). Trim the list — and note the first ${MINIMAX_FREE_REF_IMAGES} are free while each one after that adds a paid dimension to the cost key.`,
+                });
+            }
+            if ((input.videoReferenceAssetIds?.length ?? 0) + (input.videoReferenceAssetId ? 1 : 0) > maxVideos) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxVideos} reference videos.`,
+                });
+            }
+            if ((input.audioReferenceAssetIds?.length ?? 0) + (input.audioReferenceAssetId ? 1 : 0) > maxAudio) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxAudio} reference audio clips.`,
+                });
+            }
+            if (maxTotal > 0 && refImages + refMedia > maxTotal) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} takes at most ${maxTotal} reference files across all modalities (you passed ${refImages + refMedia}).`,
+                });
+            }
+            // fal: "Audio cannot be the only reference input; provide at least one
+            // reference image or video with it."
+            const audioRefs = (input.audioReferenceAssetIds?.length ?? 0) + (input.audioReferenceAssetId ? 1 : 0);
+            const videoRefs = (input.videoReferenceAssetIds?.length ?? 0) + (input.videoReferenceAssetId ? 1 : 0);
+            if (audioRefs > 0 && refImages === 0 && videoRefs === 0) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `${input.model} rejects an audio-only reference set — add at least one reference image or video alongside it.`,
+                });
+            }
+        }
         // ⛔ The hand-written Veo duration block that stood here is GONE. It read
         // `![4,6,8].includes(duration)` plus "4K only at 8s" — and the registry
         // forces 8s at 1080p TOO, so it happily quoted a 4s 1080p Veo the provider
@@ -1985,6 +2156,10 @@ export const generateVideo = {
             sound: input.sound,
             seedanceFace: input.seedanceFace,
             seedanceRealFace: input.seedanceRealFace,
+            // MiniMax H3 base: reference images past the fifth are a PAID key
+            // dimension. Counted from the same four arrays the request sends, so the
+            // quote and the server's own re-derivation see the same number.
+            referenceImages: minimaxRefImageCount(input),
             // Σ ceil(d - 0.05) over every reference clip, both shapes — the same
             // expression the desktop's estimateCost and the handler's key builder
             // use. Quoting only the singular would understate a multi-clip call.
@@ -2005,7 +2180,9 @@ export const generateVideo = {
         const entry = registry.models.find((m) => m.model === costKey);
         if (!entry) {
             throw new Error(`Model variant not in registry: ${costKey}. ` +
-                `Available video models: ${registry.models.filter((m) => m.model.startsWith('kling') || m.model.startsWith('veo') || m.model.startsWith('seedance') || m.model.startsWith('omni-flash')).map((m) => m.model).slice(0, 20).join(', ')}`);
+                // Prefixes DERIVED from the model list, so a new family cannot be
+                // missing from the hint the way minimax-h3 was on day one.
+                `Available video models: ${registry.models.filter((m) => VIDEO_MODELS.some((v) => m.model.startsWith(v.split('.')[0]))).map((m) => m.model).slice(0, 20).join(', ')}`);
         }
         const totalCents = creditCost(entry);
         // Pre-flight confirm gate. Fires when:
@@ -2510,7 +2687,7 @@ export const generateMotionTransfer = {
 // ── Edit video (Kling O3 video-to-video) ────────────────────────
 export const editVideo = {
     id: 'slates_edit_video',
-    description: 'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default; 3–15s clips, 720–3840px, subject/style refs via elements), omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat), or seedance-2.5-edit (4–30s clips — the ONLY engine that takes a clip over 15s; 480p/720p, seedanceFace:true for AI-character faces). Cost = per second of OUTPUT (≈ clip length, rounded UP to the next second): omni-flash-edit ≈ 19¢/s ≈ kling-v3.0-omni-edit ≈ 19¢/s, kling-v3.0-omni-pro-edit ≈ 25¢/s. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. seedance-2.5-edit is priced per second of output on the video-reference tier and bills roughly double a plain 2.5 generation of the same length, because every provider charges an edit on input + output seconds — always read the quote from the confirm gate rather than assuming. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default edit tool (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; prefer Seedance edit/relocate only for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
+    description: 'Edit an EXISTING video clip with one instruction — character swap, environment change, style transfer — in one pass, no masking. Original motion, camera, and audio are preserved; only what the prompt names changes. Use when a clip is ~90% right (fix it, don\'t re-roll it) or to AI-edit the user\'s own footage. Engines: Kling O3 edit (default; 3–15s clips, 720–3840px, subject/style refs via elements), omni-flash-edit (Gemini Omni Flash; 3–10s clips, 720p output, PROMPT-ONLY — no refs, cheapest seat), or seedance-2.5-edit (4–30s clips — the ONLY engine that takes a clip over 15s; up to 1080p, seedanceFace:true for AI-character faces). Cost = per second of OUTPUT (≈ clip length, rounded UP to the next second): omni-flash-edit ≈ 19¢/s ≈ kling-v3.0-omni-edit ≈ 19¢/s, kling-v3.0-omni-pro-edit ≈ 25¢/s. Subjects to swap IN go as characterAssetIds (frontal + angle images become Kling elements — Kling models only); style refs as styleAssetIds; max 4 combined. seedance-2.5-edit is priced per second of output on the video-reference tier and bills roughly double a plain 2.5 generation of the same length, because every provider charges an edit on input + output seconds — always read the quote from the confirm gate rather than assuming. The edited clip saves as a NEW asset linked to its parent (chain edits freely). Routing: Kling edit is the default edit tool (element lock + audio intact); omni-flash-edit for cheap prompt-only footage-synced swaps; prefer Seedance edit/relocate only for style-transfer-heavy jobs — see slates-model-selection. Prompting: slates-prompting-kling-v3 §Edit / slates-prompting-omni-flash.',
     input: z.object({
         projectId: z.string().uuid().describe('Project the source clip lives in.'),
         sourceVideoAssetId: z.string().describe('The VIDEO asset to edit — UUID or badge code ("VID-V3", bare "V3"); codes resolve against the project at call time. Kling: 3–15s clips; omni-flash-edit: 3–10s.'),
@@ -2579,6 +2756,9 @@ export const editVideo = {
         const costKey = isSeedanceEdit
             ? seedanceEditCostKey({
                 duration: billedSeconds,
+                // Cast to the full union, never to the row's current two-or-three
+                // values: MODEL_CAPABILITIES is the narrowing authority and that list
+                // moves (1080p landed on the 2.5 edit row 2026-08-24).
                 videoResolution: (input.videoResolution ?? defaultVideoResolutionFor('seedance-2.5-edit')),
                 seedanceFace: input.seedanceFace === true,
             })
@@ -3312,6 +3492,15 @@ function resolveGuideTopic(topic) {
         return 'slates-prompting-veo-3';
     if (t.startsWith('omni-flash') || t.startsWith('gemini-omni') || t === 'omni flash')
         return 'slates-prompting-omni-flash';
+    // MiniMax H3 — both seats share one skill. Placed BEFORE the seed/seedance
+    // block for the same reason seed-audio is: no prefix collision exists today,
+    // but a `minimax-*` id must never fall through to a Seedance guide.
+    if (t.startsWith('minimax') ||
+        t.startsWith('hailuo') ||
+        t === 'h3' ||
+        t.startsWith('h3-')) {
+        return 'slates-prompting-minimax-h3';
+    }
     if (t.startsWith('kling-mc'))
         return 'slates-prompting-motion-transfer';
     if (t === 'edit-video' || t === 'video-edit' || t === 'edit video' || t === 'video edit')

package/dist/prompts/model-capabilities.d.ts

@@ -1,6 +1,13 @@
 /** Every aspect ratio any Slates model accepts. There is no `9:21`. */
 export type AspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9';
-export type VideoResolution = '480p' | '720p' | '1080p' | '4k';
+/**
+ * 🚨 `768p` and `2k` entered this vocabulary with MiniMax H3 (2026-08-27) and
+ * are NOT aliases of anything already here. 768p is H3's native generation tier
+ * and prices between 480p and 2K ($0.060/s vs 720p Seedance's $0.15/s — a
+ * different tier of a different model, not a rename); 2K is H3's upscaled tier.
+ * Aliasing either onto 720p/1080p would build a cost key that does not exist.
+ */
+export type VideoResolution = '480p' | '720p' | '768p' | '1080p' | '2k' | '4k';
 /**
  * The full ten, in display order. `9:21` was in the MCP op's enum and in NO
  * model — it was invented downstream. Do not add a ratio here that no model

package/dist/prompts/model-capabilities.js

@@ -73,6 +73,21 @@ const VEO_FAL_ASPECT_RATIOS = ['16:9', '9:16'];
 const OMNI_FLASH_ASPECT_RATIOS = ['16:9', '9:16'];
 /** Seedance (both seats, and the edit row): six — notably NO `4:5`. */
 const SEEDANCE_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
+/**
+ * MiniMax H3, both seats: six. Read off fal's live OpenAPI 2026-08-27 for
+ * `minimax/h3/text-to-video` and `minimax/h3-max/text-to-video` — identical
+ * enums. It happens to be the same six Seedance takes; kept as its OWN constant
+ * because a provider that adds a ratio adds it to ITS family, and sharing the
+ * Seedance constant would silently move H3 the next time ByteDance moves.
+ *
+ * Two endpoint quirks the registry deliberately does not model:
+ *   · `image-to-video` has NO `aspect_ratio` param at all — the output follows
+ *     the start frame. The handler simply omits it there.
+ *   · `reference-to-video` adds an `adaptive` value on top of these six. We
+ *     never send it: the composer always has an explicit ratio, and `adaptive`
+ *     is not an AspectRatio in this vocabulary.
+ */
+const MINIMAX_H3_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
 /**
  * The provider every AGENT generation actually lands on for Kling and Veo.
  *
@@ -254,8 +269,16 @@ export const MODEL_CAPABILITIES = {
     },
     'seedance-2.5': {
         aspectRatios: SEEDANCE_ASPECT_RATIOS,
-        // 🚨 480p/720p ONLY, on BytePlus, EvoLink AND fal. No 1080p, no 4K.
-        videoResolution: { options: ['480p', '720p'], default: '720p' },
+        // 1080p landed 2026-08-24 on ALL THREE rails — BytePlus and EvoLink publish
+        // 1080p rate rows and fal's live OpenAPI enum reads
+        // ['480p','720p','1080p']. There is still NO 4K on 2.5 (2.0 is the only
+        // Seedance with one), which is what keeps `is4kVideoKey` version-blind.
+        //
+        // DEFAULT STAYS 720p, deliberately: a 30s take at 1080p is ~614 credits
+        // against a 1,000-credit welcome grant, and that is at the promotional
+        // 1080p rate — it rises when the promo lapses. Reaching a tier and
+        // defaulting to it are different decisions.
+        videoResolution: { options: ['480p', '720p', '1080p'], default: '720p' },
         duration: { min: 4, max: 30, mode: 'continuous' },
         maxIngredientImages: 30,
         maxReferenceVideos: 10,
@@ -267,7 +290,10 @@ export const MODEL_CAPABILITIES = {
     },
     'seedance-2.5-edit': {
         aspectRatios: SEEDANCE_ASPECT_RATIOS,
-        videoResolution: { options: ['480p', '720p'], default: '720p' },
+        // Same ladder as the generation row (1080p added 2026-08-24). EvoLink's
+        // rate card carries 1080p on the edit/extend row and BytePlus's video-input
+        // column runs the full tier list; an edit bills that tier × 2.
+        videoResolution: { options: ['480p', '720p', '1080p'], default: '720p' },
         duration: { min: 4, max: 30, mode: 'continuous' },
         // 🚨 ZERO, AND IT MUST MATCH WHAT THE HANDLER SENDS. The model's edit task
         // type does accept reference images, but slate's
@@ -285,6 +311,66 @@ export const MODEL_CAPABILITIES = {
         // NO multimodal reference caps, deliberately: on an edit row the clip IS the
         // canvas and arrives through `sourceVideo`, not as a reference.
     },
+    // ── MiniMax H3 (both seats on fal — added 2026-08-27) ──────────────────────
+    //
+    // Every value below is READ OFF fal's live OpenAPI, fetched 2026-08-27:
+    //   minimax/h3/{text-to-video,image-to-video,reference-to-video}
+    //   minimax/h3-max/{text-to-video,image-to-video}
+    // `minimax/h3-max/reference-to-video` returns 404 — it does not exist, which
+    // is why the Max row declares no reference capacity at all.
+    //
+    // 🚨 NEVER PREFIX-MATCH THESE TWO IDS. `minimax-h3-max` starts with
+    // `minimax-h3`, so any `startsWith('minimax-h3')` swallows the Max row into
+    // the base row's branch — a different ladder AND a different price at the one
+    // tier they share. Every lookup downstream is an exact-id map, not a prefix.
+    'minimax-h3': {
+        aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
+        // The full ladder. 480p/768p are NATIVE generation modes; 2K and 4K upscale
+        // a 768p base result through H3-Regenerate-2K, which is API-only and not in
+        // the open weights — that is why fal can undercut list at the bottom two
+        // tiers and matches it exactly at the top two.
+        //
+        // DEFAULT 768p, NOT fal's own default of 2K. 768p is the tier the model was
+        // trained to output and the one every benchmark quotes; 2K is a 2.2x price
+        // step and 4K a 2.7x step, and reaching a tier is a different decision from
+        // defaulting to it (same reasoning that keeps Seedance 2.5 on 720p).
+        videoResolution: { options: ['480p', '768p', '2k', '4k'], default: '768p' },
+        // 5, not 4. MiniMax's own model card says 4-15s; fal's schema — which is
+        // what our request actually hits — says `minimum: 5`. The endpoint wins.
+        duration: { min: 5, max: 15, mode: 'continuous' },
+        // Ref2VA omni-reference caps, verbatim from the reference-to-video schema:
+        // reference_image_urls maxItems 9, reference_video_urls maxItems 3,
+        // reference_audio_urls maxItems 3, and in every one of the three
+        // descriptions: "Reference images, videos, and audio clips must add up to
+        // at most 12 files."
+        maxIngredientImages: 9,
+        maxReferenceVideos: 3,
+        maxReferenceAudio: 3,
+        maxReferenceFilesTotal: 12,
+        // COMBINED, not per clip. fal states "2-15 seconds each, combined duration
+        // at most 15 seconds" for both media arms — so the per-clip floor of 2s is
+        // the shared reference-video minimum already enforced by the composer, and
+        // 15 is the sum these fields have always meant.
+        maxReferenceVideoSeconds: 15,
+        maxReferenceAudioSeconds: 15,
+    },
+    'minimax-h3-max': {
+        aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
+        // 480p/768p ONLY — fal's post-train of the open weights, and the 2K
+        // upscaler was never open-sourced. Declaring the shorter ladder here IS the
+        // whole Max-seat mechanism: `assertVideoCapabilities` refuses 2K/4K on this
+        // id, the desktop picker renders only what this entry declares, and the
+        // agent's Zod enum stays the union while the per-model guard narrows.
+        // Anything shaped like "disable the higher tiers when Max is selected" is
+        // re-implementing a guard that already exists.
+        videoResolution: { options: ['480p', '768p'], default: '768p' },
+        duration: { min: 5, max: 15, mode: 'continuous' },
+        // NO reference caps, deliberately: fal publishes text-to-video and
+        // image-to-video for h3-max and NOTHING else (reference-to-video 404s), so
+        // there is no transport for a reference of any modality. A cap declared
+        // above what the handler sends is a SILENT DROP — the exact failure
+        // `seedance-2.5-edit` shipped with. Absent means the composer refuses.
+    },
     // ── Audio ──────────────────────────────────────────────────────────────────
     //
     // `aspectRatios: []` is deliberate, not an oversight: audio has no frame, and
@@ -374,7 +460,9 @@ export function aspectRatioUnion(models, provider) {
 }
 /** Union of every resolution the given models accept. */
 export function videoResolutionUnion(models) {
-    const order = ['480p', '720p', '1080p', '4k'];
+    // Ascending by output height, so an enum reads as a ladder. 768p sits between
+    // 720p and 1080p; 2k (≈2560×1440) between 1080p and 4k.
+    const order = ['480p', '720p', '768p', '1080p', '2k', '4k'];
     const seen = new Set();
     for (const m of models)
         for (const r of videoResolutionsFor(m))