@shop-os/modelkit 0.2.20 → 0.2.21

package/dist/index.cjs

@@ -1368,12 +1368,14 @@ 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 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 = [
@@ -1394,9 +1396,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" },
@@ -1407,7 +1413,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",
@@ -1527,7 +1534,8 @@ 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" },
@@ -1541,7 +1549,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.
@@ -1567,7 +1575,8 @@ 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"],
       audio: "optional"
     },
     defaults: {
@@ -1607,7 +1616,8 @@ 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"],
       audio: "optional"
     },
     defaults: {
@@ -1626,7 +1636,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"],
@@ -1648,14 +1657,15 @@ 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"],
       audio: "optional"
     },
     defaults: {
       durationSeconds: 5,
       resolution: "720p",
       aspectRatio: "16:9",
-      generateAudio: false
+      generateAudio: true
     },
     usage: { ...VIDEO_USAGE },
     pricingKind: "video_per_second",
@@ -1667,7 +1677,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",
@@ -1681,7 +1690,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"
@@ -1706,16 +1716,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
     },
@@ -1724,7 +1734,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 }
   },
@@ -1738,19 +1748,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",
@@ -1762,7 +1771,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.
@@ -1775,22 +1784,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",
@@ -1805,6 +1817,8 @@ 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"],
       audio: "always"
     },
@@ -1834,8 +1848,10 @@ 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"],
       audio: "always"
     },
@@ -1850,7 +1866,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 }
   },
@@ -1867,6 +1883,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,
@@ -1906,8 +1924,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,
@@ -2464,6 +2484,7 @@ var CatalogDisplaySchema = import_zod3.z.looseObject({
 var CatalogCapabilitiesSchema = import_zod3.z.looseObject({
   acceptsSourceVideo: import_zod3.z.boolean().optional(),
   framesExcludeReferences: import_zod3.z.boolean().optional(),
+  lastFrameRequiresFirstFrame: import_zod3.z.boolean().optional(),
   reasoning: import_zod3.z.boolean().optional(),
   vision: import_zod3.z.boolean().optional(),
   contextWindow: import_zod3.z.number().optional()
@@ -4686,7 +4707,12 @@ async function generateOmniVideo(req, ctx, createGenAIClient) {
   const extend = req.taskType === "extend";
   const previousId = extend ? req.previousInteractionId : void 0;
   const chained = previousId !== void 0;
-  for (const field of ["referenceImages", "referenceVideos", "firstFrame"]) {
+  for (const field of [
+    "referenceImages",
+    "referenceVideos",
+    "firstFrame",
+    "lastFrame"
+  ]) {
     const value = req[field];
     if (!chained || value === void 0 || Array.isArray(value) && value.length === 0)
       continue;
@@ -4700,6 +4726,14 @@ async function generateOmniVideo(req, ctx, createGenAIClient) {
   const images = chained ? [] : req.referenceImages ?? [];
   const videos = chained ? [] : req.referenceVideos ?? [];
   const firstFrame = chained ? void 0 : req.firstFrame;
+  const lastFrame = firstFrame ? req.lastFrame : void 0;
+  if (!chained && req.lastFrame !== void 0 && lastFrame === void 0) {
+    ctx.warnings.push({
+      code: "option_ignored",
+      field: "lastFrame",
+      message: `${modelId} takes an end frame only with a start frame; lastFrame ignored`
+    });
+  }
   if (extend && !chained && req.sourceVideo === void 0) {
     throw new ModelKitError({
       code: "missing_input",
@@ -4784,27 +4818,7 @@ async function generateOmniVideo(req, ctx, createGenAIClient) {
         mime_type: media.mime
       });
     }
-    if (firstFrame) {
-      if (firstFrame.label !== void 0)
-        parts.push({ type: "text", text: firstFrame.label });
-      const media = await resolveMedia(
-        firstFrame,
-        ctx.fetch,
-        ctx.signal,
-        "image/png",
-        modelId
-      );
-      if (media.bytes.length > OMNI_INLINE_LIMIT_BYTES) {
-        parts.push({
-          type: "image",
-          uri: await uploadOne("image", media.bytes, media.mime),
-          mime_type: media.mime
-        });
-      } else {
-        parts.push({ type: "image", data: toBase64(media.bytes), mime_type: media.mime });
-      }
-    }
-    for (const ref of images) {
+    const pushImage = async (ref) => {
       if (ref.label !== void 0) parts.push({ type: "text", text: ref.label });
       const media = await resolveMedia(ref, ctx.fetch, ctx.signal, "image/png", modelId);
       if (media.bytes.length > OMNI_INLINE_LIMIT_BYTES) {
@@ -4816,8 +4830,12 @@ async function generateOmniVideo(req, ctx, createGenAIClient) {
       } else {
         parts.push({ type: "image", data: toBase64(media.bytes), mime_type: media.mime });
       }
-    }
-    parts.push({ type: "text", text: req.prompt });
+    };
+    if (firstFrame) await pushImage(firstFrame);
+    if (lastFrame) await pushImage(lastFrame);
+    for (const ref of images) await pushImage(ref);
+    const prompt = lastFrame ? `<FIRST_FRAME> <LAST_FRAME> ${req.prompt}` : req.prompt;
+    parts.push({ type: "text", text: prompt });
     try {
       interaction = await withRetry(async () => {
         try {
@@ -5347,6 +5365,26 @@ function videoUsage3(ctx, req, duration) {
   if (req.durationSeconds !== void 0) event.durationSeconds = req.durationSeconds;
   return event;
 }
+var KLING_ENDPOINT_FIELDS = /* @__PURE__ */ new Map([
+  [
+    "kling-video/v2.5-turbo/pro/image-to-video",
+    { aspectRatio: false, negativePrompt: true, lastFrame: false, sound: false }
+  ],
+  [
+    "kling-video/v3.0/pro/image-to-video",
+    { aspectRatio: false, negativePrompt: false, lastFrame: true, sound: true }
+  ]
+]);
+var UNLISTED_KLING_FIELDS = {
+  aspectRatio: true,
+  negativePrompt: true,
+  lastFrame: true,
+  sound: false
+};
+function klingEndpointFields(providerModelId) {
+  const path = (providerModelId.startsWith("/") ? providerModelId.slice(1) : providerModelId).toLowerCase();
+  return KLING_ENDPOINT_FIELDS.get(path) ?? UNLISTED_KLING_FIELDS;
+}
 var klingCreateSchema = import_zod13.z.object({ status_url: import_zod13.z.string() });
 var klingStatusSchema = import_zod13.z.object({
   status: import_zod13.z.string().optional(),
@@ -5381,6 +5419,13 @@ async function createRequest(ctx, url, init) {
   }
   return res;
 }
+function ignoreKlingField(ctx, field) {
+  ctx.warnings.push({
+    code: "option_ignored",
+    field,
+    message: `${ctx.model.id}: the Higgsfield endpoint has no ${field} input; ignored`
+  });
+}
 async function generateKlingVideo(req, ctx) {
   const firstFrame = req.firstFrame ? refToUrl(req.firstFrame) : void 0;
   if (!firstFrame) {
@@ -5392,16 +5437,29 @@ async function generateKlingVideo(req, ctx) {
       retryable: false
     });
   }
+  const fields = klingEndpointFields(ctx.model.providerModelId);
   const body = {
     prompt: req.prompt.trim(),
     image_url: firstFrame,
-    cfg_scale: req.cfgScale ?? 0.5,
-    negative_prompt: req.negativePrompt ?? DEFAULT_NEGATIVE_PROMPT
+    cfg_scale: req.cfgScale ?? 0.5
   };
+  if (fields.negativePrompt) {
+    body.negative_prompt = req.negativePrompt ?? DEFAULT_NEGATIVE_PROMPT;
+  } else if (req.negativePrompt !== void 0) {
+    ignoreKlingField(ctx, "negativePrompt");
+  }
   if (req.durationSeconds !== void 0) body.duration = req.durationSeconds;
-  if (req.aspectRatio !== void 0 && req.aspectRatio !== "adaptive")
-    body.aspect_ratio = req.aspectRatio;
-  if (req.lastFrame) body.last_image_url = refToUrl(req.lastFrame);
+  if (req.aspectRatio !== void 0 && req.aspectRatio !== "adaptive") {
+    if (fields.aspectRatio) body.aspect_ratio = req.aspectRatio;
+    else ignoreKlingField(ctx, "aspectRatio");
+  }
+  if (req.lastFrame) {
+    if (fields.lastFrame) body.last_image_url = refToUrl(req.lastFrame);
+    else ignoreKlingField(ctx, "lastFrame");
+  }
+  if (fields.sound && req.generateAudio !== void 0) {
+    body.sound = req.generateAudio ? "on" : "off";
+  }
   const endpoint = klingEndpoint(ctx.model.providerModelId, ctx.model.id);
   const retryOptions = mediaRetryOptions(ctx.call, ctx.signal);
   const createRes = await withRetry(
@@ -6703,24 +6761,22 @@ function klingInput(req) {
   return input;
 }
 function klingOmniMode(req) {
+  if (req.resolution === "4k") return "4k";
   if (req.resolution === "1080p") return "pro";
   if (req.resolution === "720p") return "standard";
   return req.mode ?? "standard";
 }
 function klingOmniInput(req) {
-  const images = (req.firstFrame ? [req.firstFrame] : []).map(refToUrl);
-  if (req.lastFrame) images.push(refToUrl(req.lastFrame));
   const input = {
     prompt: req.prompt,
     duration: req.durationSeconds ?? 10,
     mode: klingOmniMode(req),
     generate_audio: req.generateAudio ?? false
   };
-  const startImage = images[0];
-  if (startImage !== void 0) {
-    input.start_image = startImage;
-    const endImage = images[1];
-    if (endImage !== void 0) input.end_image = endImage;
+  const start = req.firstFrame ?? req.lastFrame;
+  if (start) {
+    input.start_image = refToUrl(start);
+    if (req.firstFrame && req.lastFrame) input.end_image = refToUrl(req.lastFrame);
   } else if (req.aspectRatio !== "adaptive") {
     input.aspect_ratio = req.aspectRatio ?? "16:9";
   }
@@ -6968,7 +7024,7 @@ async function generateXaiVideo(req, ctx, deps) {
       retryable: false
     });
   }
-  const refUrls = (req.referenceImages ?? []).map(refToUrl).slice(0, 5);
+  const refUrls = (req.referenceImages ?? []).map(refToUrl).slice(0, 7);
   const xaiOptions = {
     pollIntervalMs: POLL_INTERVAL_MS2,
     pollTimeoutMs: POLL_TIMEOUT_MS2
@@ -7682,6 +7738,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) {