vidspotai-shared 1.0.94 → 1.0.96

package/lib/services/agent/tools/generateAvatarVideo.tool.js

@@ -4,79 +4,177 @@ exports.generateAvatarVideoTool = void 0;
 const zod_1 = require("zod");
 const aiModels_1 = require("../../../globals/aiModels");
 const firebase_1 = require("../../../libs/firebase");
-const aiGenFactory_service_1 = require("../../aiGen/aiGenFactory.service");
+const avatarProviderFactory_1 = require("../../avatarGen/avatarProviderFactory");
 const types_1 = require("../../aiGen/types");
 const rateLimiter_1 = require("../../rateLimiter");
 const ttsFactory_service_1 = require("../../tts/ttsFactory.service");
 const toolRegistry_1 = require("../toolRegistry");
 /**
- * generate_avatar_video — wraps the existing kling-avatar pipeline so the
- * planner's `talking-head-avatar` scene strategy is executable. Accepts a
- * presenter face image URL plus either a pre-uploaded audio URL or raw TTS
- * text (in which case the tool synthesizes via ElevenLabs and uploads to GCS
- * before handing off, since Kling avatar requires a public sound_file URL).
+ * generate_avatar_video — drives avatar generation through the dedicated avatar
+ * provider seam (getAvatarVideoProvider / IAvatarVideoProvider), so the planner's
+ * `talking-head-avatar` scene strategy is executable. Avatar gen is handled by
+ * the avatar provider — NOT the generic video-gen provider. Two engine families:
  *
- * Returns a provider task id; the executor / monitor layer polls completion
- * exactly as it does for generate_video.
+ *  - byo-media (default kling-avatar): caller supplies a presenter face image
+ *    plus either a pre-uploaded audio URL or raw TTS text (the tool synthesizes
+ *    via ElevenLabs + uploads to GCS first, since the engine needs a public
+ *    audio URL).
+ *  - hosted (heygen-avatar / tavus-avatar, via `model`): caller supplies a
+ *    provider-hosted avatar id + a script; the engine runs its own TTS/lipsync,
+ *    so the tool does NO TTS and passes no audio.
+ *
+ * Returns a provider task id; the executor's TaskPoller polls completion — it
+ * routes hosted models through the avatar seam and everything else through the
+ * generic video factory, so this works for both families.
  */
 const InputSchema = zod_1.z
     .object({
+    model: zod_1.z
+        .nativeEnum(aiModels_1.EVideoGenModels)
+        .optional()
+        .describe("Avatar engine. Default kling-avatar (byo-media: animate a face image). heygen-avatar / tavus-avatar are hosted (animate a provider-hosted avatar + native TTS)."),
     inputImageUrl: zod_1.z
         .string()
         .url()
-        .describe("Presenter face still — Kling animates this image to lipsync the audio."),
+        .optional()
+        .describe("byo-media: presenter face still the engine animates to lipsync the audio. Required for byo-media; omit for hosted."),
+    hostedAvatarId: zod_1.z
+        .string()
+        .optional()
+        .describe("hosted: provider-hosted avatar id (HeyGen) or replica_id (Tavus) to animate. Required for hosted engines."),
+    hostedVoiceId: zod_1.z
+        .string()
+        .optional()
+        .describe("hosted: provider-hosted voice id (HeyGen). Unused for Tavus (the replica owns its voice)."),
     ttsText: zod_1.z
         .string()
         .min(1)
         .optional()
-        .describe("VO line to synthesize. Either ttsText or inputAudioUrl must be set; if both are set, inputAudioUrl wins."),
+        .describe("VO line / script. byo-media: synthesized to audio (or use inputAudioUrl; if both set, inputAudioUrl wins). hosted: spoken natively by the engine (required)."),
     inputAudioUrl: zod_1.z
         .string()
         .url()
         .optional()
-        .describe("Pre-uploaded audio URL (mp3/wav). Skips internal TTS+upload."),
+        .describe("byo-media only: pre-uploaded audio URL (mp3/wav). Skips internal TTS+upload."),
     voiceId: zod_1.z.string().optional(),
     languageCode: zod_1.z.string().optional(),
     mode: zod_1.z.enum(["std", "pro"]).default("std"),
     prompt: zod_1.z
         .string()
         .optional()
-        .describe("Optional motion/emotion hint passed through to Kling."),
+        .describe("byo-media only: optional motion/emotion hint passed through to the engine."),
 })
     .superRefine((v, ctx) => {
-    if (!v.ttsText && !v.inputAudioUrl) {
-        ctx.addIssue({
-            code: zod_1.z.ZodIssueCode.custom,
-            message: "Either ttsText or inputAudioUrl is required.",
-        });
+    if (v.model && (0, avatarProviderFactory_1.isHostedAvatarModel)(v.model)) {
+        if (!v.hostedAvatarId) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "hostedAvatarId is required for hosted avatar engines.",
+                path: ["hostedAvatarId"],
+            });
+        }
+        if (!v.ttsText) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "ttsText (the script) is required for hosted avatar engines.",
+                path: ["ttsText"],
+            });
+        }
+    }
+    else {
+        if (!v.inputImageUrl) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "inputImageUrl is required for byo-media avatar engines.",
+                path: ["inputImageUrl"],
+            });
+        }
+        if (!v.ttsText && !v.inputAudioUrl) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Either ttsText or inputAudioUrl is required.",
+            });
+        }
     }
 });
 const OutputSchema = zod_1.z.object({
     status: zod_1.z.literal("triggered"),
     taskId: zod_1.z.string(),
-    audioUrl: zod_1.z.string().url().describe("Audio URL fed to Kling — host can reuse for caption sync."),
+    audioUrl: zod_1.z
+        .string()
+        .url()
+        .optional()
+        .describe("byo-media: audio URL fed to the engine — host can reuse for caption sync. Absent for hosted engines (native TTS)."),
 });
 exports.generateAvatarVideoTool = {
     name: "generate_avatar_video",
     description: [
-        "Generate a talking-head avatar video by animating a presenter face still",
-        "to lipsync a voiceover. Wraps the kling-avatar provider.",
+        "Generate a talking-head avatar video that lipsyncs a voiceover. Routed",
+        "through the dedicated avatar provider seam. Two engine families: byo-media",
+        "(default kling-avatar) animates a presenter face still you supply; hosted",
+        "(heygen-avatar / tavus-avatar, via `model`) animates a provider-hosted",
+        "avatar and runs its own TTS from a script.",
         "Use this for the `talking-head-avatar` scene strategy. Do NOT use it for",
         "general motion shots — generate_video is cheaper and more flexible there.",
         "Examples:",
         '  { inputImageUrl: "https://.../face.png", ttsText: "Hi, today we\'re testing the new serum." }',
         '  { inputImageUrl: "https://.../face.png", inputAudioUrl: "https://.../vo.mp3", mode: "pro" }',
+        '  { model: "heygen-avatar", hostedAvatarId: "Daisy-inskirt-20220818", hostedVoiceId: "2d5b0e6cf36f460aa7fc47e3eee4ba54", ttsText: "Welcome back!" }',
     ].join(" "),
     inputSchema: InputSchema,
     outputSchema: OutputSchema,
     idempotent: false,
     estimateCost: async (input) => {
-        // Kling avatar bills per audio second. Without a length we assume 6s (typical scene).
+        // Without a length we assume 6s (typical scene).
         const approxSec = input.ttsText ? Math.max(2, Math.ceil(input.ttsText.length / 15)) : 6;
+        const modelKey = input.model ?? aiModels_1.EVideoGenModels.KLING_AVATAR;
+        if ((0, avatarProviderFactory_1.isHostedAvatarModel)(modelKey)) {
+            // Hosted engines bill per generated MINUTE (min 1 minute).
+            const perMinute = aiModels_1.aiModelConfigs[modelKey]?.cost?.perMinute ?? 0.5;
+            const billedMinutes = Math.max(1, Math.ceil(approxSec / 60));
+            return Math.ceil(perMinute * billedMinutes * 100); // rough credit conversion
+        }
+        // byo-media (Kling) bills per audio second.
         const perSec = input.mode === "pro" ? 0.028 : 0.014;
-        return Math.ceil(approxSec * perSec * 100); // rough credit conversion
+        return Math.ceil(approxSec * perSec * 100);
     },
     handler: async (input, ctx) => {
+        const modelKey = input.model ?? aiModels_1.EVideoGenModels.KLING_AVATAR;
+        const renderMode = input.mode === "pro" ? types_1.EVideoMode.PROFESSIONAL : types_1.EVideoMode.STANDARD;
+        // ── Hosted engines (HeyGen/Tavus) ────────────────────────────────────────
+        // The engine does its own TTS + lipsync from the script, so there's no TTS
+        // synthesis / GCS upload here. Submit and hand the task id to the poller,
+        // which routes hosted models through the avatar seam.
+        if ((0, avatarProviderFactory_1.isHostedAvatarModel)(modelKey)) {
+            const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(modelKey);
+            await limiter.waitUntilAvailable();
+            let heldSlot = true;
+            try {
+                const provider = (0, avatarProviderFactory_1.getAvatarVideoProvider)(modelKey);
+                const result = await provider.generate({
+                    mode: "hosted",
+                    hostedAvatarId: input.hostedAvatarId,
+                    hostedVoiceId: input.hostedVoiceId ?? "",
+                    script: input.ttsText,
+                    locale: input.languageCode,
+                    renderMode,
+                });
+                const taskId = result.providerTaskId?.taskId ??
+                    result.providerTaskId?.id ??
+                    (typeof result.providerTaskId === "string" ? result.providerTaskId : "unknown");
+                if (taskId === "unknown") {
+                    limiter.releaseSlot();
+                    heldSlot = false;
+                }
+                return { status: "triggered", taskId };
+            }
+            catch (err) {
+                if (heldSlot)
+                    limiter.releaseSlot();
+                throw err;
+            }
+        }
+        // ── byo-media engines (Kling) ─────────────────────────────────────────────
         let audioUrl = input.inputAudioUrl;
         if (!audioUrl) {
             const ttsLimiter = (0, rateLimiter_1.getTtsProviderRateLimiter)("elevenlabs");
@@ -100,29 +198,27 @@ exports.generateAvatarVideoTool = {
             const [signedUrl] = await file.getSignedUrl({ action: "read", expires: "03-09-2491" });
             audioUrl = signedUrl;
         }
-        // Hold the Kling-avatar slot through return — host's TaskPoller releases
+        // Hold the byo-media model slot through return — host's TaskPoller releases
         // when the task settles. Release here on submit error.
-        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(aiModels_1.EVideoGenModels.KLING_AVATAR);
+        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(modelKey);
         await limiter.waitUntilAvailable();
         let heldSlot = true;
         try {
-            const provider = (0, aiGenFactory_service_1.getAiGenProviderService)(aiModels_1.EVideoGenModels.KLING_AVATAR);
-            // No `type` — kling-avatar's modelConfig.type is ["avatar-video"], which is
-            // outside the VideoGenerationParams.type union. Setting type:"image-to-video"
-            // here trips validateParams (image-to-video branch requires the model's
-            // config.type to include "image-to-video", which avatar's doesn't). The
-            // kling provider routes by modelKey === "kling-avatar" before any
-            // type-based dispatch, so omitting type is correct.
-            const result = await provider.generateVideo({
-                modelKey: aiModels_1.EVideoGenModels.KLING_AVATAR,
+            // byo-media avatar request: a face still + the audio we just resolved. The
+            // avatar provider owns endpoint/type dispatch internally (Kling routes on
+            // modelKey === "kling-avatar"), so no generic-video `type` is passed here.
+            // inputImageUrl presence is guaranteed by the byo-media superRefine branch.
+            const provider = (0, avatarProviderFactory_1.getAvatarVideoProvider)(modelKey);
+            const result = await provider.generate({
+                mode: "byo-media",
+                faceImageUrl: input.inputImageUrl,
+                audioUrl,
                 prompt: input.prompt,
-                inputImageUrl: input.inputImageUrl,
-                inputAudioUrl: audioUrl,
-                mode: input.mode === "pro" ? types_1.EVideoMode.PROFESSIONAL : types_1.EVideoMode.STANDARD,
+                renderMode,
             });
-            const taskId = result.task?.taskId ??
-                result.task?.id ??
-                (typeof result.task === "string" ? result.task : "unknown");
+            const taskId = result.providerTaskId?.taskId ??
+                result.providerTaskId?.id ??
+                (typeof result.providerTaskId === "string" ? result.providerTaskId : "unknown");
             if (taskId === "unknown") {
                 limiter.releaseSlot();
                 heldSlot = false;

package/lib/services/agent/tools/planVideo.tool.d.ts

@@ -332,12 +332,12 @@ declare const OutputSchema: z.ZodObject<{
             estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
             sceneIndices: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
         }, z.core.$strip>>>;
-        script: z.ZodOptional<z.ZodObject<{
+        script: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
             fullText: z.ZodString;
             wordCount: z.ZodOptional<z.ZodNumber>;
             estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
             wpm: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         music: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodEnum<{
                 none: "none";

package/lib/services/aiGen/aiGenFactory.service.d.ts

@@ -1,7 +1,7 @@
 import { BaseAiGenProviderService } from "./providers/baseAiGenProvider.service";
 import { EImageGenModelKey, EMusicGenModels, ESfxGenModels, ETextGenModels, EVideoGenModels, TAiGenModel } from "../../globals/aiModels";
 type AiGenServiceConstructor = new () => BaseAiGenProviderService;
-export declare const videoServicesMap: Record<EVideoGenModels, AiGenServiceConstructor>;
+export declare const videoServicesMap: Partial<Record<EVideoGenModels, AiGenServiceConstructor>>;
 /**
  * Image-gen factory. Each provider service implements `generateImage()` (sync;
  * returns a URL or base64 in a single API roundtrip — no BullMQ worker needed).

package/lib/services/aiGen/aiGenFactory.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAchC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AAElE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CA+DxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,iBAAiB,EACjB,uBAAuB,CA2CxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,aAAa,EACb,uBAAuB,CAGxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAsBzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAkB1B"}
+{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAchC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AASlE,eAAO,MAAM,gBAAgB,EAAE,OAAO,CACpC,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC,CA+DjD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,iBAAiB,EACjB,uBAAuB,CA2CxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,aAAa,EACb,uBAAuB,CAGxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAsBzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAmB1B"}

package/lib/services/aiGen/aiGenFactory.service.js

@@ -14,6 +14,13 @@ const pixverse_service_1 = require("./providers/pixverse/pixverse.service");
 const bytedance_service_1 = require("./providers/bytedance/bytedance.service");
 const elevenlabs_service_1 = require("./providers/elevenlabs/elevenlabs.service");
 const anthropic_service_1 = require("./providers/anthropic/anthropic.service");
+// Partial, intentionally: hosted avatar engines (heygen-avatar, tavus-avatar)
+// are NOT generic video models — they're handled by the dedicated avatar seam
+// (getAvatarVideoProvider / IAvatarVideoProvider). getAiGenProviderService gates
+// on `modelKey in videoServicesMap` and throws for anything absent, so these
+// keys correctly resolve through the avatar factory instead. (kling-avatar stays
+// here because KlingService still backs both its generic-credit path and the
+// KlingAvatarProvider adapter.)
 exports.videoServicesMap = {
     // --- Pixverse ---
     "pixverse-v6": pixverse_service_1.PixVerseService,
@@ -157,8 +164,9 @@ exports.textServicesMap = {
     // "openai-gpt-3.5-turbo": OpenaiService,
 };
 function getAiGenProviderService(modelKey) {
-    if (modelKey in exports.videoServicesMap) {
-        return new exports.videoServicesMap[modelKey]();
+    const VideoService = exports.videoServicesMap[modelKey];
+    if (VideoService) {
+        return new VideoService();
     }
     if (modelKey in exports.imageServicesMap) {
         return new exports.imageServicesMap[modelKey]();

package/lib/services/aiGen/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,EAAE,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAqJrE"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,EAAE,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAiKrE"}

package/lib/services/aiGen/helpers.js

@@ -5,6 +5,7 @@ exports.getModelsSupportingLastFrame = getModelsSupportingLastFrame;
 exports.modelDeclaresField = modelDeclaresField;
 exports.validateParams = validateParams;
 const aiModels_1 = require("../../globals/aiModels");
+const errors_1 = require("../../utils/errors");
 /**
  * Whether a model supports first-last-frame (FLF) interpolation, i.e. accepts a
  * `lastFrameImageUrl`. The source of truth is the model config: a model declares
@@ -125,9 +126,18 @@ function validateParams(params) {
             }
         }
     }
-    // 4. Fail fast if validation fails
+    // 4. Fail fast if validation fails.
+    // These are DETERMINISTIC input/capability mismatches (a required input the
+    // model needs is absent, an unsupported value/combo, etc.) — an expected
+    // user-input outcome, NOT a server fault. Throw a typed UserFacingError with
+    // CAPABILITY_MISMATCH so it (a) short-circuits the scene retry loop, (b) stays
+    // OFF the pager (errorPaging non-paging set) instead of alerting on-call with
+    // a raw "INTERNAL Validation failed" — e.g. a kling-motion-control job
+    // submitted without its required inputVideoUrl (2026-07-09). The job surfaces
+    // the friendly CAPABILITY_MISMATCH message; the technical detail stays on the
+    // scene for debugging.
     if (errors.length) {
-        throw new Error(`INTERNAL Validation failed: ${errors.join("; ")}`);
+        throw new errors_1.UserFacingError(`Validation failed: ${errors.join("; ")}`, errors_1.USER_FACING_ERROR_CODES.CAPABILITY_MISMATCH);
     }
     return true;
 }

package/lib/services/aiGen/providers/kling/kling.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kling.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/kling/kling.service.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAsBlB;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,wBAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IASxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkD;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;;YAWlE,OAAO;IAgCf,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAoDjC;;;;OAIG;YACW,WAAW;YA6BX,iBAAiB;YA6BjB,qBAAqB;YAgCrB,eAAe;YAkDf,mBAAmB;YAgCnB,uBAAuB;IAwF/B,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW7E,cAAc,IAAI,MAAM;IAexB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAGjD"}
+{"version":3,"file":"kling.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/kling/kling.service.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAsBlB;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,wBAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IASxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkD;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;;YAWlE,OAAO;IAgCf,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAoDjC;;;;OAIG;YACW,WAAW;YA6BX,iBAAiB;YA6BjB,qBAAqB;YAgCrB,eAAe;YAkDf,mBAAmB;YAgCnB,uBAAuB;IAqI/B,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW7E,cAAc,IAAI,MAAM;IAexB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAGjD"}

package/lib/services/aiGen/providers/kling/kling.service.js

@@ -219,25 +219,64 @@ class KlingService extends baseAiGenProvider_service_1.BaseAiGenProviderService
                 // True rate-limit (HTTP 429 without the balance code) — worth retrying with backoff.
                 const isRateLimit = httpStatus === 429 && !isInsufficientBalance;
                 const isRetryable = (isTimeout || isNetworkError || isRateLimit) && !isInsufficientBalance;
-                // Insufficient balance is a critical ops issue — surface immediately to Slack.
+                // Insufficient balance is a billing/account fault an operator must act on
+                // (top up Kling). Classify as ACCOUNT_QUOTA_EXCEEDED so the shared paging
+                // policy (errorPaging.ts) pages ONCE at the scene boundary — consistent
+                // with the Veo billing-depletion path. The top-up detail is logged at
+                // warn (Loki only, no duplicate Slack page) so it stays searchable
+                // without the previous double-page (raw throw here + generic scene page).
                 if (isInsufficientBalance) {
-                    logger_1.logger.error("Kling account balance too low — top up required to continue video generation", {
+                    logger_1.logger.warn("Kling account balance too low — top up required to continue video generation", {
                         endpoint,
                         klingCode,
                         klingMessage: err.response?.data?.message,
                         httpStatus,
                     });
-                    throw err;
+                    throw new errors_1.UserFacingError("This video provider is temporarily unavailable. Please try a different model or retry shortly.", errors_1.USER_FACING_ERROR_CODES.ACCOUNT_QUOTA_EXCEEDED);
                 }
-                // Audio rejected by Kling — pick the user message based on which 1201 variant it is.
+                // Kling code 1201 is a broad "input rejected" family — a user-fixable
+                // input constraint, not a system fault. It fires for AUDIO (avatar /
+                // lip-sync `sound_file`) AND for IMAGE inputs (e.g. an oversized
+                // end-frame `image_tail` on a plain image2video — see the kling-v3.0
+                // end-frame case, 2026-07-09). So only blame audio when audio was
+                // actually part of the request; otherwise the message misleads the
+                // user (and whoever debugs the log) into hunting a non-existent audio
+                // clip. CAPABILITY_MISMATCH keeps it off the pager (errorPaging set).
                 if (isAudioError) {
                     const klingMsg = (err.response?.data?.message ?? "").toLowerCase();
-                    const userMessage = klingMsg.includes("size")
-                        ? "Your audio file is too large for this avatar generation. Please use a shorter audio clip and try again."
-                        : "Your audio format is not supported. Please upload an MP3 or WAV file and try again.";
-                    throw new errors_1.UserFacingError(userMessage);
+                    const isSize = klingMsg.includes("size");
+                    const hasAudioInput = endpoint.includes("avatar") ||
+                        endpoint.includes("lip") ||
+                        !!(body && typeof body === "object" && body.sound_file);
+                    let userMessage;
+                    if (hasAudioInput) {
+                        userMessage = isSize
+                            ? "Your audio clip is too large for this video. Please use a shorter audio clip and try again."
+                            : "Your audio format is not supported. Please upload an MP3 or WAV file and try again.";
+                    }
+                    else {
+                        userMessage = isSize
+                            ? "One of your input images is too large for this model. Please use a smaller image (or remove the end-frame) and try again."
+                            : "One of your inputs was rejected by this model. Please adjust your image or settings and try again.";
+                    }
+                    throw new errors_1.UserFacingError(userMessage, errors_1.USER_FACING_ERROR_CODES.CAPABILITY_MISMATCH);
                 }
                 if (!isRetryable || attempt === maxAttempts) {
+                    // A rate-limit that exhausted its retries is an expected, un-actionable
+                    // condition (Kling throughput saturation) — surface it as a non-paging
+                    // UserFacingError rather than a raw axios 429, so it doesn't page
+                    // on-call. (Genuine 1102 balance depletion is handled above and DOES
+                    // page; ambiguous bare 429s land here and read as rate-limit, which is
+                    // the safe default — rate limits shouldn't page.)
+                    if (isRateLimit) {
+                        logger_1.logger.warn("Kling rate-limited — retries exhausted", {
+                            endpoint,
+                            attempt,
+                            maxAttempts,
+                            httpStatus,
+                        });
+                        throw new errors_1.UserFacingError("This video provider is busy right now. Please retry in a little while.", errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_RATE_LIMITED);
+                    }
                     logger_1.logger.error("Kling API request failed (non-retryable or max attempts reached)", {
                         endpoint,
                         attempt,

package/lib/services/aiGen/providers/pixverse/pixverse.service.d.ts

@@ -2,6 +2,14 @@ import { BaseAiGenProviderService } from "../baseAiGenProvider.service";
 import { CreditUsageParams, VideoGenerationParams, VideoGenerationResult, VideoStatusParams, VideoStatusResult } from "../types";
 export declare class PixVerseService extends BaseAiGenProviderService {
     private readonly baseUrl;
+    /**
+     * Uploads a source image to PixVerse and returns the integer `img_id` that
+     * /img/generate requires. The Upload-Image endpoint accepts either a binary
+     * `image` file or an `image_url` string (multipart/form-data) — we pass the
+     * URL we already have. Note: NO Content-Type header here; fetch sets the
+     * multipart boundary itself when the body is a FormData.
+     */
+    private uploadImage;
     generateVideo(params: VideoGenerationParams): Promise<VideoGenerationResult>;
     checkVideoStatus({ task, outputFilename, outputFilePath, }: VideoStatusParams): Promise<VideoStatusResult>;
     getCreditUsed(params: CreditUsageParams): number;

package/lib/services/aiGen/providers/pixverse/pixverse.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixverse.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/pixverse/pixverse.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AA0FlB,qBAAa,eAAgB,SAAQ,wBAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAKpE,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAyK3B,gBAAgB,CAAC,EACrB,IAAI,EACJ,cAAc,EACd,cAAyB,GAC1B,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0FjD,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAkDjD"}
+{"version":3,"file":"pixverse.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/pixverse/pixverse.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AA0FlB,qBAAa,eAAgB,SAAQ,wBAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAK1E;;;;;;OAMG;YACW,WAAW;IA6CnB,aAAa,CACjB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;IAgL3B,gBAAgB,CAAC,EACrB,IAAI,EACJ,cAAc,EACd,cAAyB,GAC1B,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0FjD,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAkDjD"}

package/lib/services/aiGen/providers/pixverse/pixverse.service.js

@@ -82,6 +82,52 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
         this.baseUrl = "https://app-api.pixverse.ai/openapi/v2/video";
     }
     // =========================================================
+    // UPLOAD IMAGE (image-to-video prerequisite)
+    // =========================================================
+    /**
+     * Uploads a source image to PixVerse and returns the integer `img_id` that
+     * /img/generate requires. The Upload-Image endpoint accepts either a binary
+     * `image` file or an `image_url` string (multipart/form-data) — we pass the
+     * URL we already have. Note: NO Content-Type header here; fetch sets the
+     * multipart boundary itself when the body is a FormData.
+     */
+    async uploadImage(imageUrl, traceId) {
+        const form = new FormData();
+        form.append("image_url", imageUrl);
+        return (0, transientRetry_1.withTransientRetry)("pixverse:uploadImage", async () => {
+            const resp = await fetch(`https://app-api.pixverse.ai/openapi/v2/image/upload`, {
+                method: "POST",
+                headers: {
+                    "API-KEY": process.env.PIXVERSE_API_KEY,
+                    "Ai-trace-id": traceId,
+                },
+                body: form,
+            });
+            if (!resp.ok) {
+                const errText = await resp.text();
+                throw classifyPixVerseHttpError(resp.status, errText, "uploadImage");
+            }
+            const data = await resp.json();
+            if (data.ErrCode !== undefined && data.ErrCode !== 0) {
+                throw classifyPixVerseApiError(data.ErrCode, data.ErrMsg ?? "", "uploadImage");
+            }
+            const imgId = data?.Resp?.img_id;
+            if (imgId === undefined || imgId === null) {
+                throw new Error("PixVerse image upload did not return img_id");
+            }
+            return Number(imgId);
+        }, {
+            onRetry: ({ attempt, maxAttempts, backoffMs, err }) => {
+                logger_1.logger.warn(`PixVerse uploadImage transient error — retrying`, {
+                    attempt,
+                    maxAttempts,
+                    backoffMs,
+                    message: err.message,
+                });
+            },
+        });
+    }
+    // =========================================================
     // GENERATE VIDEO
     // =========================================================
     async generateVideo(params) {
@@ -206,10 +252,17 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
             if (params.lipSync.ttsSpeakerId)
                 body.lip_sync_tts_speaker_id = params.lipSync.ttsSpeakerId;
         }
-        // I2V switches endpoint and adds the image reference.
+        // I2V switches endpoint and adds the image reference. The /img/generate
+        // endpoint does NOT accept a raw image_url — it requires an integer
+        // `img_id` from the Upload-Image API (verified 2026-06-30 against
+        // https://docs.platform.pixverse.ai/image-to-video-generation-13016633e0).
+        // Sending image_url instead surfaced in prod as ErrCode 400017 "Either
+        // img_id or api_gen_img_ids must be provided." So we upload first, then
+        // pass the returned img_id. (Distinct from the /template/generate "effect"
+        // path above, which DOES take a customer_img_url directly.)
         const isImageToVideo = !!params.inputImageUrl;
         if (isImageToVideo) {
-            body.image_url = params.inputImageUrl;
+            body.img_id = await this.uploadImage(params.inputImageUrl, traceId);
         }
         // I2V path is `/img/generate` — NOT `/image/generate`, which returns a bare
         // "404 page not found" (verified 2026-06-15 via PixVerse OpenAPI smoke test