@shop-os/modelkit 0.2.20 → 0.2.22

package/dist/catalog.d.cts

@@ -295,6 +295,8 @@ interface CatalogCapabilities {
     acceptsSourceVideo?: boolean;
     /** Video rows: first/last frames and reference images are mutually exclusive inputs. */
     framesExcludeReferences?: boolean;
+    /** Video rows: a last frame is accepted only together with a first frame. */
+    lastFrameRequiresFirstFrame?: boolean;
     /** Text rows. `reasoning`: the model streams reasoning the UI should surface. */
     reasoning?: boolean;
     vision?: boolean;
@@ -848,6 +850,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
     capabilities: z.ZodOptional<z.ZodObject<{
         acceptsSourceVideo: z.ZodOptional<z.ZodBoolean>;
         framesExcludeReferences: z.ZodOptional<z.ZodBoolean>;
+        lastFrameRequiresFirstFrame: z.ZodOptional<z.ZodBoolean>;
         reasoning: z.ZodOptional<z.ZodBoolean>;
         vision: z.ZodOptional<z.ZodBoolean>;
         contextWindow: z.ZodOptional<z.ZodNumber>;

package/dist/catalog.d.ts

@@ -295,6 +295,8 @@ interface CatalogCapabilities {
     acceptsSourceVideo?: boolean;
     /** Video rows: first/last frames and reference images are mutually exclusive inputs. */
     framesExcludeReferences?: boolean;
+    /** Video rows: a last frame is accepted only together with a first frame. */
+    lastFrameRequiresFirstFrame?: boolean;
     /** Text rows. `reasoning`: the model streams reasoning the UI should surface. */
     reasoning?: boolean;
     vision?: boolean;
@@ -848,6 +850,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
     capabilities: z.ZodOptional<z.ZodObject<{
         acceptsSourceVideo: z.ZodOptional<z.ZodBoolean>;
         framesExcludeReferences: z.ZodOptional<z.ZodBoolean>;
+        lastFrameRequiresFirstFrame: z.ZodOptional<z.ZodBoolean>;
         reasoning: z.ZodOptional<z.ZodBoolean>;
         vision: z.ZodOptional<z.ZodBoolean>;
         contextWindow: z.ZodOptional<z.ZodNumber>;

package/dist/catalog.js

@@ -158,13 +158,16 @@ var GEMINI_RATIOS = [
   "5:4",
   "adaptive"
 ];
-function geminiImage(id, label, aliases, sizes, display, exposure, references) {
+var GEMINI_PROMPT_MAX_CHARS = 5e4;
+var GPT_IMAGE_PROMPT = { referenceSyntax: "numbered", maxChars: 32e3 };
+function geminiImage(id, label, aliases, sizes, display, exposure, references, promptMaxChars) {
+  const prompt = { referenceSyntax: "caption" };
+  if (promptMaxChars !== void 0) prompt.maxChars = promptMaxChars;
   const constraints = {
     aspectRatios: [...GEMINI_RATIOS],
     sizes,
     supports: ["safetySettings", "temperature"],
-    // google-image sends MediaRef.label as a text part beside each reference.
-    prompt: { referenceSyntax: "caption" }
+    prompt
   };
   if (references !== void 0) constraints.references = references;
   const model = {
@@ -196,7 +199,8 @@ var IMAGE_MODELS = [
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
     ["cowork", "space_builder"],
-    { images: 14 }
+    { images: 14 },
+    GEMINI_PROMPT_MAX_CHARS
   ),
   geminiImage(
     "gemini-3.1-flash-image-preview",
@@ -210,7 +214,8 @@ var IMAGE_MODELS = [
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
     ["cowork", "space_builder"],
-    { images: 14 }
+    { images: 14 },
+    GEMINI_PROMPT_MAX_CHARS
   ),
   geminiImage(
     "gemini-3.1-flash-lite-image",
@@ -223,7 +228,8 @@ var IMAGE_MODELS = [
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png"
     },
     ["cowork", "space_builder"],
-    { images: 14 }
+    { images: 14 },
+    GEMINI_PROMPT_MAX_CHARS
   ),
   // trigger-workflows validates 1K only; pricing seeds 2K/4K rows so allow all three.
   geminiImage(
@@ -261,7 +267,8 @@ var IMAGE_MODELS = [
       sizes: ["1K", "2K", "4K"],
       qualityOptions: ["auto", "low", "medium", "high"],
       references: { images: 16 },
-      supports: ["quality", "count", "outputFormat"]
+      supports: ["quality", "count", "outputFormat"],
+      prompt: GPT_IMAGE_PROMPT
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE, slug: "gpt" },
@@ -296,7 +303,8 @@ var IMAGE_MODELS = [
       sizes: ["1K", "2K", "4K"],
       qualityOptions: ["auto", "low", "medium", "high", "xhigh", "max"],
       references: { images: 16 },
-      supports: ["quality", "count", "outputFormat"]
+      supports: ["quality", "count", "outputFormat"],
+      prompt: GPT_IMAGE_PROMPT
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE },
@@ -330,7 +338,8 @@ var IMAGE_MODELS = [
       sizes: ["1K", "2K", "4K"],
       qualityOptions: ["auto", "low", "medium", "high", "xhigh", "max"],
       references: { images: 16 },
-      supports: ["quality", "count", "outputFormat"]
+      supports: ["quality", "count", "outputFormat"],
+      prompt: GPT_IMAGE_PROMPT
     },
     defaults: { size: "1K", aspectRatio: "adaptive", quality: "auto" },
     usage: { ...IMAGE_USAGE },
@@ -453,7 +462,9 @@ var IMAGE_MODELS = [
       sizes: ["1K"],
       references: { images: 8 },
       // flux-2-pro's job type always returns image/png; only the seed is forwarded.
-      supports: ["seed"]
+      supports: ["seed"],
+      // Prodia's flux-2-pro schema gives the prompt a maxLength of 32,768.
+      prompt: { referenceSyntax: "numbered", maxChars: 32768 }
     },
     defaults: { size: "1K", aspectRatio: "1:1" },
     usage: { ...IMAGE_USAGE },
@@ -1247,12 +1258,17 @@ var TEXT_MODELS = [
 var VIDEO_USAGE = { unit: "seconds" };
 var SEEDANCE_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16", "adaptive"];
 var KLING_RATIOS = ["16:9", "9:16", "1:1", "adaptive"];
+var KLING_OMNI_RATIOS = ["16:9", "9:16", "1:1"];
 var OMNI_RATIOS = ["16:9", "9:16"];
 var GROK_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"];
 var H3_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"];
 var H3_REFERENCE_RATIOS = ["adaptive", ...H3_RATIOS];
 var NEGATIVE_PROMPT = "blur, distort, and low quality";
 var FRAMES_EXCLUDE_REFERENCES = { framesExcludeReferences: true };
+var KLING_PROMPT = { referenceSyntax: "numbered", maxChars: 2500 };
+var SEEDANCE_PROMPT = { referenceSyntax: "numbered", maxChars: 3e4 };
+var H3_PROMPT = { referenceSyntax: "numbered", maxChars: 5e4 };
+var OMNI_PROMPT = { referenceSyntax: "caption", maxChars: 5e4 };
 var BYTEDANCE_LOGO = "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/3bba5d81-4e57-4e71-911b-cdfa05acca2c_compressed.png";
 var GOOGLE_LOGO2 = "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/192485d2-a76a-4657-9c06-930b2c70badd_compressed.png";
 var VIDEO_MODELS = [
@@ -1273,9 +1289,13 @@ var VIDEO_MODELS = [
     constraints: {
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["720p", "1080p", "4k"],
+      // Veo also takes 4 and 6, but must be 8 at 1080p/4k or with reference images;
+      // [8] until the kit has a rule that forces it there (CHANGELOG 0.2.21).
       durations: [8],
       references: { images: 3 },
       supports: ["lastFrame", "seed"],
+      // 1,024 text tokens; 3,000 characters assumes ~2.9 characters per token.
+      prompt: { referenceSyntax: "numbered", maxChars: 3e3 },
       audio: "always"
     },
     defaults: { durationSeconds: 8, resolution: "720p", aspectRatio: "16:9" },
@@ -1286,7 +1306,8 @@ var VIDEO_MODELS = [
       description: "Google's highest-quality video generation model. Supports up to 4K resolution and 8-second clips with reference image conditioning.",
       logo: GOOGLE_LOGO2
     },
-    capabilities: { ...FRAMES_EXCLUDE_REFERENCES }
+    // Veo's lastFrame "must be used in combination with the image parameter".
+    capabilities: { ...FRAMES_EXCLUDE_REFERENCES, lastFrameRequiresFirstFrame: true }
   },
   {
     id: "veo-3.1-fast",
@@ -1371,8 +1392,7 @@ var VIDEO_MODELS = [
       references: { images: 6, videos: 1, videoSeconds: { max: 10 } },
       sourceVideoSeconds: { max: 10 },
       supports: [],
-      // generateOmniVideo sends MediaRef.label as a text part beside each image.
-      prompt: { referenceSyntax: "caption" },
+      prompt: OMNI_PROMPT,
       audio: "always"
     },
     defaults: {},
@@ -1406,10 +1426,10 @@ var VIDEO_MODELS = [
       // extension can upload a <= 10 s source with task "extend"; later ones
       // chain by `previousInteractionId` (the API rejects the id together
       // with a video task, so those calls carry the prompt alone).
-      supports: ["videoExtension"],
+      // First-to-last-frame interpolation: `<LAST_FRAME>` goes with `<FIRST_FRAME>`.
+      supports: ["videoExtension", "lastFrame"],
       extension: { segmentSeconds: 10, maxTotalSeconds: 40 },
-      // generateOmniVideo sends MediaRef.label as a text part beside each image.
-      prompt: { referenceSyntax: "caption" },
+      prompt: OMNI_PROMPT,
       audio: "always"
     },
     defaults: {},
@@ -1420,7 +1440,7 @@ var VIDEO_MODELS = [
       logo: GOOGLE_LOGO2,
       description: "Google Gemini Omni Flash 1.1 conversational video generation, editing and extension; text, image, and up to 10-second video input, 3-10 second output at up to 4K and 24 FPS, extendable to 40 seconds."
     },
-    capabilities: { acceptsSourceVideo: true }
+    capabilities: { acceptsSourceVideo: true, lastFrameRequiresFirstFrame: true }
   },
   {
     // vibe-triggers and Space Builder drop the ratio when a frame is wired; Cowork always sends it.
@@ -1446,7 +1466,9 @@ var VIDEO_MODELS = [
       },
       sourceVideoSeconds: { min: 2, max: 15, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
-      supports: ["generateAudio", "seed", "lastFrame", "watermark"],
+      // No seed: 2.x echoes it but does not honour it (two seeded runs differed, 2026-10-01).
+      supports: ["generateAudio", "lastFrame", "watermark"],
+      prompt: SEEDANCE_PROMPT,
       audio: "optional"
     },
     defaults: {
@@ -1486,7 +1508,9 @@ var VIDEO_MODELS = [
       },
       sourceVideoSeconds: { min: 2, max: 15, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
-      supports: ["generateAudio", "seed", "lastFrame", "watermark"],
+      // No seed: 2.x echoes it but does not honour it (two seeded runs differed, 2026-10-01).
+      supports: ["generateAudio", "lastFrame", "watermark"],
+      prompt: SEEDANCE_PROMPT,
       audio: "optional"
     },
     defaults: {
@@ -1505,7 +1529,6 @@ var VIDEO_MODELS = [
     capabilities: { acceptsSourceVideo: true, ...FRAMES_EXCLUDE_REFERENCES }
   },
   {
-    // generateAudio defaults to false here (trigger-workflows); Space Builder defaults it to true.
     // omni_reference_task_type edit/extend: adaptive ratio, edit sends duration -1.
     id: "seedance-2.5",
     aliases: ["seedance-2-5", "dreamina-seedance-2-5-260628"],
@@ -1527,14 +1550,16 @@ var VIDEO_MODELS = [
       },
       sourceVideoSeconds: { min: 2, max: 30, editMin: 4, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
-      supports: ["generateAudio", "seed", "lastFrame", "watermark", "taskType"],
+      // No seed: 2.x echoes it but does not honour it (two seeded runs differed, 2026-10-01).
+      supports: ["generateAudio", "lastFrame", "watermark", "taskType"],
+      prompt: SEEDANCE_PROMPT,
       audio: "optional"
     },
     defaults: {
       durationSeconds: 5,
       resolution: "720p",
       aspectRatio: "16:9",
-      generateAudio: false
+      generateAudio: true
     },
     usage: { ...VIDEO_USAGE },
     pricingKind: "video_per_second",
@@ -1546,7 +1571,6 @@ var VIDEO_MODELS = [
     capabilities: { acceptsSourceVideo: true, ...FRAMES_EXCLUDE_REFERENCES }
   },
   {
-    // Cowork allows 7 reference images and durations 4/6/8/10; Space Builder allows 5 and 1-15s.
     id: "grok-imagine",
     aliases: ["grok-imagine-video", "grokImagine"],
     label: "Grok Imagine",
@@ -1560,7 +1584,8 @@ var VIDEO_MODELS = [
       resolutions: ["480p", "720p"],
       durations: { min: 1, max: 15 },
       durationPresets: [4, 6, 8, 10],
-      references: { images: 5 },
+      // xAI: "A maximum of 7 reference images can be provided per request."
+      references: { images: 7 },
       supports: [],
       // xAI can switch sound off (generate_audio); xai-video.ts never sends it.
       audio: "always"
@@ -1585,16 +1610,16 @@ var VIDEO_MODELS = [
     providerModelId: "kling-video/v2.5-turbo/pro/image-to-video",
     lifecycle: "active",
     exposure: ["cowork", "space_builder"],
+    // The endpoint has no aspect_ratio or last_image_url: the start image sets the framing.
     constraints: {
-      aspectRatios: [...KLING_RATIOS],
       durations: [5, 10],
       requires: ["firstFrame"],
-      supports: ["cfgScale", "negativePrompt", "lastFrame"],
+      supports: ["cfgScale", "negativePrompt"],
+      prompt: KLING_PROMPT,
       audio: "never"
     },
     defaults: {
       durationSeconds: 5,
-      aspectRatio: "16:9",
       cfgScale: 0.5,
       negativePrompt: NEGATIVE_PROMPT
     },
@@ -1603,7 +1628,7 @@ var VIDEO_MODELS = [
     display: {
       provider: "kuaishou",
       logo: "https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.97.0/light/kling-color.png",
-      description: "Kuaishou Kling 2.5 Turbo Pro image-to-video; animates a single input image from a text prompt with an optional end image, 5- or 10-second clips."
+      description: "Kuaishou Kling 2.5 Turbo Pro image-to-video; animates a single input image from a text prompt, 5- or 10-second clips."
     },
     capabilities: { ...FRAMES_EXCLUDE_REFERENCES }
   },
@@ -1617,19 +1642,18 @@ var VIDEO_MODELS = [
     providerModelId: "kling-video/v3.0/pro/image-to-video",
     lifecycle: "active",
     exposure: ["cowork", "space_builder"],
+    // The endpoint has no aspect_ratio or negative_prompt; sound is "on"/"off" (default on).
     constraints: {
-      aspectRatios: [...KLING_RATIOS],
       durations: { min: 3, max: 15 },
       requires: ["firstFrame"],
-      supports: ["cfgScale", "negativePrompt", "lastFrame"],
-      // Higgsfield has a `sound` switch (default on); KlingCreate doesn't send it.
-      audio: "always"
+      supports: ["cfgScale", "lastFrame", "generateAudio"],
+      prompt: KLING_PROMPT,
+      audio: "optional"
     },
     defaults: {
       durationSeconds: 5,
-      aspectRatio: "16:9",
       cfgScale: 0.5,
-      negativePrompt: NEGATIVE_PROMPT
+      generateAudio: true
     },
     usage: { ...VIDEO_USAGE },
     pricingKind: "video_per_second",
@@ -1641,7 +1665,7 @@ var VIDEO_MODELS = [
     capabilities: { ...FRAMES_EXCLUDE_REFERENCES }
   },
   {
-    // mode standard/pro selects 720p/1080p; the endpoint takes no separate resolution.
+    // mode standard/pro/4k selects 720p/1080p/4K; the endpoint takes no separate resolution.
     // Replicate: "Max 7 [images] without video, 4 with video"; 4K does not support
     // reference_video. No `videos` limit yet: the adapter sends no reference video,
     // so `imagesWithVideo` stays dormant until one is wired through.
@@ -1654,22 +1678,25 @@ var VIDEO_MODELS = [
     lifecycle: "active",
     exposure: ["cowork", "space_builder"],
     constraints: {
-      aspectRatios: [...KLING_RATIOS],
-      resolutions: ["720p", "1080p"],
+      aspectRatios: [...KLING_OMNI_RATIOS],
+      resolutions: ["720p", "1080p", "4k"],
       durations: { min: 3, max: 15 },
       references: { images: 7, imagesWithVideo: 4 },
       supports: ["generateAudio", "lastFrame"],
+      prompt: KLING_PROMPT,
       audio: "optional"
     },
-    defaults: { durationSeconds: 5, aspectRatio: "16:9", generateAudio: false, mode: "pro" },
+    defaults: { durationSeconds: 5, aspectRatio: "16:9", generateAudio: true, mode: "pro" },
     usage: { unit: "compute_seconds" },
     pricingKind: "video_per_second",
     display: {
       provider: "kuaishou",
       logo: "https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.97.0/light/kling-color.png",
-      description: "Kuaishou Kling Video 3.0 Omni unified generation and editing from text, start/end images, up to 7 reference images, and reference video; up to 15 seconds at up to 1080p."
-    },
-    capabilities: {}
+      description: "Kuaishou Kling Video 3.0 Omni unified generation and editing from text, start/end images, up to 7 reference images, and reference video; up to 15 seconds at up to 4K."
+    }
+    // end_image "Requires start_image", but no lastFrameRequiresFirstFrame: SpaceLab resolves
+    // replicate rows in error mode, so the flag would refuse its end-frame-only nodes, which
+    // the adapter sends as start_image.
   },
   {
     id: "minimax-h3",
@@ -1684,7 +1711,10 @@ var VIDEO_MODELS = [
       aspectRatios: [...H3_RATIOS],
       resolutions: ["480p", "768p", "2k", "4k"],
       durations: { min: 5, max: 15 },
+      // fal's image-to-video endpoint has no aspect_ratio; the frame sets it.
+      ratioIgnoredWith: ["firstFrame"],
       supports: ["seed", "promptExpansion", "lastFrame", "safetyChecker"],
+      prompt: H3_PROMPT,
       audio: "always"
     },
     defaults: {
@@ -1713,9 +1743,12 @@ var VIDEO_MODELS = [
     exposure: ["cowork", "space_builder"],
     constraints: {
       aspectRatios: [...H3_RATIOS],
-      resolutions: ["480p", "768p"],
+      resolutions: ["480p", "768p", "1080p"],
       durations: { min: 5, max: 15 },
+      // fal's image-to-video endpoint has no aspect_ratio; the frame sets it.
+      ratioIgnoredWith: ["firstFrame"],
       supports: ["seed", "promptExpansion", "lastFrame", "safetyChecker"],
+      prompt: H3_PROMPT,
       audio: "always"
     },
     defaults: {
@@ -1729,7 +1762,7 @@ var VIDEO_MODELS = [
     display: {
       provider: "minimax",
       logo: "https://d31vvfpk2ppdyq.cloudfront.net/assets/image/f4c2e906-28b7-4a4a-b491-df8fef7808ed.png",
-      description: "High-speed MiniMax H3 Max variant for text-to-video and image-to-video (first/last frame) only, up to 768p."
+      description: "High-speed MiniMax H3 Max variant for text-to-video and image-to-video (first/last frame) only, up to 1080p."
     },
     capabilities: { ...FRAMES_EXCLUDE_REFERENCES }
   },
@@ -1746,6 +1779,8 @@ var VIDEO_MODELS = [
       aspectRatios: [...H3_REFERENCE_RATIOS],
       resolutions: ["480p", "768p", "2k", "4k"],
       durations: { min: 5, max: 15 },
+      // A start frame routes to image-to-video, which has no aspect_ratio.
+      ratioIgnoredWith: ["firstFrame"],
       references: {
         images: 9,
         videos: 3,
@@ -1755,6 +1790,7 @@ var VIDEO_MODELS = [
         videoSeconds: { min: 2, max: 15, total: 15 }
       },
       supports: ["seed", "promptExpansion", "safetyChecker"],
+      prompt: H3_PROMPT,
       audio: "always"
     },
     defaults: {
@@ -1785,8 +1821,10 @@ var VIDEO_MODELS = [
     exposure: ["cowork", "space_builder"],
     constraints: {
       aspectRatios: [...H3_REFERENCE_RATIOS],
-      resolutions: ["480p", "768p"],
+      resolutions: ["480p", "768p", "1080p"],
       durations: { min: 5, max: 15 },
+      // A start frame routes to image-to-video, which has no aspect_ratio.
+      ratioIgnoredWith: ["firstFrame"],
       references: {
         images: 9,
         videos: 3,
@@ -1796,6 +1834,7 @@ var VIDEO_MODELS = [
         videoSeconds: { min: 2, max: 15, total: 15 }
       },
       supports: ["seed", "promptExpansion", "safetyChecker"],
+      prompt: H3_PROMPT,
       audio: "always"
     },
     defaults: {
@@ -2344,6 +2383,7 @@ var CatalogDisplaySchema = z3.looseObject({
 var CatalogCapabilitiesSchema = z3.looseObject({
   acceptsSourceVideo: z3.boolean().optional(),
   framesExcludeReferences: z3.boolean().optional(),
+  lastFrameRequiresFirstFrame: z3.boolean().optional(),
   reasoning: z3.boolean().optional(),
   vision: z3.boolean().optional(),
   contextWindow: z3.number().optional()
@@ -2925,6 +2965,24 @@ function resolveVideoOptions(model, request, onUnsupported = "error") {
     });
     delete merged.sourceVideo;
   }
+  if (merged.lastFrame !== void 0 && merged.firstFrame === void 0 && model.capabilities?.lastFrameRequiresFirstFrame) {
+    if (onUnsupported === "error") {
+      throw new ModelKitError({
+        code: "missing_input",
+        message: `${model.id} takes an end frame only together with a start frame`,
+        model: model.id,
+        retryable: false
+      });
+    }
+    warnings.push({
+      code: "option_ignored",
+      field: "lastFrame",
+      to: "firstFrame",
+      message: `end frame used as start frame: ${model.id} needs a start frame with an end frame`
+    });
+    merged.firstFrame = merged.lastFrame;
+    delete merged.lastFrame;
+  }
   const hasFrames = merged.firstFrame !== void 0 || merged.lastFrame !== void 0;
   const hasRefs = compact(merged.referenceImages).length + compact(merged.referenceVideos).length + compact(merged.referenceAudios).length > 0;
   if (hasFrames && hasRefs && model.capabilities?.framesExcludeReferences) {