@marlinjai/studio-mcp 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -33,12 +33,14 @@ declare const DocNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "multiview-to-3d": "multiview-to-3d";
         remesh: "remesh";
         texture: "texture";
+        rig: "rig";
         "text-to-audio": "text-to-audio";
         "text-to-speech": "text-to-speech";
         "speech-to-text": "speech-to-text";
         "speech-to-speech": "speech-to-speech";
         "image-to-text": "image-to-text";
         "image-to-json": "image-to-json";
+        "video-to-text": "video-to-text";
         judge: "judge";
         "text-generation": "text-generation";
         upscale: "upscale";
@@ -68,6 +70,13 @@ declare const DocNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     assetId: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
     collapsed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"video-source">;
+    videoUrl: z.ZodDefault<z.ZodString>;
+    assetId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodLiteral<"input">;
@@ -113,12 +122,14 @@ declare const WorkflowDocumentSchema: z.ZodObject<{
             "multiview-to-3d": "multiview-to-3d";
             remesh: "remesh";
             texture: "texture";
+            rig: "rig";
             "text-to-audio": "text-to-audio";
             "text-to-speech": "text-to-speech";
             "speech-to-text": "speech-to-text";
             "speech-to-speech": "speech-to-speech";
             "image-to-text": "image-to-text";
             "image-to-json": "image-to-json";
+            "video-to-text": "video-to-text";
             judge: "judge";
             "text-generation": "text-generation";
             upscale: "upscale";
@@ -148,6 +159,13 @@ declare const WorkflowDocumentSchema: z.ZodObject<{
         assetId: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         collapsed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"video-source">;
+        videoUrl: z.ZodDefault<z.ZodString>;
+        assetId: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"input">;
@@ -233,12 +251,14 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             "multiview-to-3d": "multiview-to-3d";
             remesh: "remesh";
             texture: "texture";
+            rig: "rig";
             "text-to-audio": "text-to-audio";
             "text-to-speech": "text-to-speech";
             "speech-to-text": "speech-to-text";
             "speech-to-speech": "speech-to-speech";
             "image-to-text": "image-to-text";
             "image-to-json": "image-to-json";
+            "video-to-text": "video-to-text";
             judge: "judge";
             "text-generation": "text-generation";
             upscale: "upscale";
@@ -268,6 +288,13 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         assetId: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         collapsed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"video-source">;
+        videoUrl: z.ZodDefault<z.ZodString>;
+        assetId: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"input">;
@@ -317,12 +344,14 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             "multiview-to-3d": "multiview-to-3d";
             remesh: "remesh";
             texture: "texture";
+            rig: "rig";
             "text-to-audio": "text-to-audio";
             "text-to-speech": "text-to-speech";
             "speech-to-text": "speech-to-text";
             "speech-to-speech": "speech-to-speech";
             "image-to-text": "image-to-text";
             "image-to-json": "image-to-json";
+            "video-to-text": "video-to-text";
             judge: "judge";
             "text-generation": "text-generation";
             upscale: "upscale";
@@ -353,6 +382,16 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strict>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"setNodeProps">;
+    kind: z.ZodLiteral<"video-source">;
+    id: z.ZodString;
+    props: z.ZodObject<{
+        videoUrl: z.ZodOptional<z.ZodString>;
+        assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"setNodeProps">;
     kind: z.ZodLiteral<"input">;
@@ -508,12 +547,14 @@ declare const PatchSchema: z.ZodObject<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -543,6 +584,13 @@ declare const PatchSchema: z.ZodObject<{
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             collapsed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"video-source">;
+            videoUrl: z.ZodDefault<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -592,12 +640,14 @@ declare const PatchSchema: z.ZodObject<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -628,6 +678,16 @@ declare const PatchSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"setNodeProps">;
+        kind: z.ZodLiteral<"video-source">;
+        id: z.ZodString;
+        props: z.ZodObject<{
+            videoUrl: z.ZodOptional<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
         kind: z.ZodLiteral<"input">;
@@ -798,7 +858,7 @@ interface ApplyError {
  * Pure: no database, no provider, no DOM.
  */
 
-type ProjectionIssueCode = "no_task_nodes" | "not_runnable" | "no_model" | "prompt_required" | "source_uploading" | "no_inputs" | "param_unmappable" | "param_type_conflict" | "integrity";
+type ProjectionIssueCode = "no_task_nodes" | "not_runnable" | "no_model" | "prompt_required" | "source_uploading" | "keyframe_positions" | "no_inputs" | "param_unmappable" | "param_type_conflict" | "integrity";
 interface ProjectionIssue {
     code: ProjectionIssueCode;
     /** The node the issue is about, when it is about one. */
@@ -911,6 +971,9 @@ interface NodeRun {
         mime?: string | null;
         text?: string;
         json?: unknown;
+        assetId?: string | null;
+        /** A name for one of several results, e.g. a rig's animation clip preset. */
+        label?: string;
     }>;
     costUsd?: number | null;
     errorMessage?: string | null;
@@ -993,7 +1056,11 @@ interface TenantUsageResponse {
     tenantId?: string;
     month: string;
     plan: string;
+    /** `null` = explicitly unlimited (only an operator-set plan can be). */
     capUsd: number | null;
+    /** `default`: no plan of its own, the default cap applies. `row`: an
+     * operator-set plan. Absent from a Studio older than 2026-09-23. */
+    capSource?: 'row' | 'default';
     rpm: number | null;
     /** Realized + in-flight estimated: the same total the quota guard checks
      * against and a 402 body's `usedUsd` reports. */
@@ -1022,7 +1089,7 @@ interface TaskDescriptor {
     inputs: Array<{
         port: string;
         wireable: boolean;
-        cardinality: 'one' | 'none';
+        cardinality: 'one' | 'two' | 'many' | 'none';
         binding: {
             key: string;
             path: string;
@@ -1144,6 +1211,25 @@ declare class StudioClient {
         jobId: string;
         kind: string;
     }>;
+    /**
+     * One 3D generation. `/api/generate` routes to its 3D branch on `?force=3d`
+     * (a prompt alone would be classified by its words); the model and its flags
+     * ride under `settings.model3d` and `settings.options3d`, an input image as
+     * `images[0]`.
+     */
+    generate3d(body: {
+        prompt: string;
+        images?: string[];
+        projectId?: string;
+        brandSlug?: string;
+        settings?: {
+            model3d?: string;
+            options3d?: Record<string, unknown>;
+        };
+    }): Promise<{
+        jobId: string;
+        kind: string;
+    }>;
     getJob(jobId: string): Promise<JobResponse>;
     listCharacters(): Promise<{
         characters: CharacterSummary[];
@@ -1160,6 +1246,11 @@ declare class StudioClient {
         descriptorPrompt: string;
         negativePrompt?: string;
         defaultModel?: string;
+        /** The likeness acknowledgement, confirmed by the human the agent acts
+         * for. The literal `true` in the type is the point: a call site with no
+         * confirmation to pass does not compile. The Studio answers 422
+         * `likeness_rights_confirmation_required` without it. */
+        likenessRightsConfirmed: true;
     }): Promise<{
         character: CharacterSummary;
     }>;
@@ -1262,6 +1353,10 @@ declare class StudioClient {
         budgetUsd?: number;
         /** Bypasses the $10 confirmation threshold for this one request. */
         confirm?: boolean;
+        /** The likeness acknowledgement. Required by the Studio when the recipe
+         * creates a character (422 `likeness_rights_confirmation_required`,
+         * before anything is spent); ignored by a recipe that creates none. */
+        likenessRightsConfirmed?: true;
     }): Promise<{
         runId: string;
         status: string;
@@ -1404,7 +1499,7 @@ declare function registerTools(server: McpServer, ctx: ToolContext): void;
  */
 
 declare const SERVER_NAME = "lumitra-studio";
-declare const SERVER_VERSION = "0.1.1";
+declare const SERVER_VERSION = "0.3.0";
 interface CreateServerOptions {
     config?: StudioConfig;
     env?: NodeJS.ProcessEnv;
@@ -1476,12 +1571,14 @@ declare const studioWorkflowCreate: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -1511,6 +1608,13 @@ declare const studioWorkflowCreate: ToolDef<{
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             collapsed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"video-source">;
+            videoUrl: z.ZodDefault<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -1560,12 +1664,14 @@ declare const studioWorkflowCreate: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -1596,6 +1702,16 @@ declare const studioWorkflowCreate: ToolDef<{
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"setNodeProps">;
+        kind: z.ZodLiteral<"video-source">;
+        id: z.ZodString;
+        props: z.ZodObject<{
+            videoUrl: z.ZodOptional<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
         kind: z.ZodLiteral<"input">;
@@ -1753,12 +1869,14 @@ declare const studioWorkflowApply: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -1788,6 +1906,13 @@ declare const studioWorkflowApply: ToolDef<{
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             collapsed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"video-source">;
+            videoUrl: z.ZodDefault<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -1837,12 +1962,14 @@ declare const studioWorkflowApply: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -1873,6 +2000,16 @@ declare const studioWorkflowApply: ToolDef<{
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"setNodeProps">;
+        kind: z.ZodLiteral<"video-source">;
+        id: z.ZodString;
+        props: z.ZodObject<{
+            videoUrl: z.ZodOptional<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
         kind: z.ZodLiteral<"input">;
@@ -2029,12 +2166,14 @@ declare const studioWorkflowValidate: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -2064,6 +2203,13 @@ declare const studioWorkflowValidate: ToolDef<{
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             collapsed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"video-source">;
+            videoUrl: z.ZodDefault<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -2150,12 +2296,14 @@ declare const studioWorkflowValidate: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -2185,6 +2333,13 @@ declare const studioWorkflowValidate: ToolDef<{
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
             collapsed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"video-source">;
+            videoUrl: z.ZodDefault<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -2234,12 +2389,14 @@ declare const studioWorkflowValidate: ToolDef<{
                 "multiview-to-3d": "multiview-to-3d";
                 remesh: "remesh";
                 texture: "texture";
+                rig: "rig";
                 "text-to-audio": "text-to-audio";
                 "text-to-speech": "text-to-speech";
                 "speech-to-text": "speech-to-text";
                 "speech-to-speech": "speech-to-speech";
                 "image-to-text": "image-to-text";
                 "image-to-json": "image-to-json";
+                "video-to-text": "video-to-text";
                 judge: "judge";
                 "text-generation": "text-generation";
                 upscale: "upscale";
@@ -2270,6 +2427,16 @@ declare const studioWorkflowValidate: ToolDef<{
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"setNodeProps">;
+        kind: z.ZodLiteral<"video-source">;
+        id: z.ZodString;
+        props: z.ZodObject<{
+            videoUrl: z.ZodOptional<z.ZodString>;
+            assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
         kind: z.ZodLiteral<"input">;
@@ -2439,6 +2606,7 @@ interface NodeSummary {
     promptLength?: number;
     /** Image-source nodes: the url clipped; empty means still uploading. */
     imageUrl?: string;
+    videoUrl?: string;
     /** Input nodes (declared run parameters). */
     name?: string;
     type?: string;
@@ -2597,14 +2765,60 @@ declare function characterSheetDefinition(overrides?: {
 declare const DEFAULT_SWAP_EDIT_MODEL = "fal/nano-banana-2-edit";
 /** Single start-frame animation. */
 declare const DEFAULT_SWAP_VIDEO_MODEL = "fal/seedance-pro-image-to-video";
-declare const DEFAULT_SWAP_PROMPT = "Replace the person in the first image with the person from the second image. Keep the pose, framing, camera angle, clothing fit, lighting, background, and every other pixel of the scene identical. Match the face, hair, and body of the second image exactly. Photorealistic, no artifacts.";
-declare const DEFAULT_MOTION_PROMPT = "Natural, subtle motion that continues the scene: gentle camera movement, realistic body motion, consistent lighting. Keep the person identical to the still.";
+/**
+ * How much of the person a swap replaces. The rest of the shot always comes
+ * from the footage: pose, expression, gaze, hands, clothing, lighting, focus,
+ * framing and background.
+ *
+ * - `identity` (the default): face, head and hair come from the character; the
+ *   footage keeps its body. The smallest change, so the fewest things can break.
+ * - `full_body`: the character's body proportions too. The silhouette changes,
+ *   so whatever the old body covered has to be reconstructed and every contact
+ *   point (a hand on a tool, a shoulder behind a door) re-derived; say so before
+ *   spending on it.
+ *
+ * Identity is the default because an unspecified scope should preserve the
+ * source, never quietly widen the edit.
+ */
+declare const SWAP_SCOPES: readonly ["identity", "full_body"];
+type SwapScope = (typeof SWAP_SCOPES)[number];
+interface SwapPromptOptions {
+    scope?: SwapScope;
+    /**
+     * Shot-specific constraints most likely to fail here, as concrete
+     * relationships from an analysis of this shot, e.g. "keep the open door in
+     * front of his body". Each becomes its own sentence.
+     */
+    preserve?: string[];
+}
+/**
+ * The still-swap edit prompt for a declared scope.
+ *
+ * Deliberately short and literal. It names what changes, which image supplies
+ * it, and what the first image keeps. It carries no realism suffix
+ * ("photorealistic, no artifacts") and no promise that every pixel stays
+ * identical: an edit model cannot guarantee either, and the suffix is how a
+ * deliberately soft, defocused subject came back tack-sharp on real footage.
+ * Untouched pixels are kept by compositing after the edit, not by asking.
+ */
+declare function composeSwapPrompt(options?: SwapPromptOptions): string;
+/** The identity-scope prompt, the one a swap gets when nothing is declared. */
+declare const DEFAULT_SWAP_PROMPT: string;
+/**
+ * The motion prompt when none is given. It asks for NO camera move: in a
+ * replacement the camera belongs to the original footage, and a model told to
+ * add "gentle camera movement" invents one the edit then has to fight.
+ */
+declare const DEFAULT_MOTION_PROMPT = "Continue the scene as photographed: keep the camera position and framing of the still, move the person naturally and continuously, and keep the lighting consistent. Add no camera movement.";
 interface CharacterSwapInput {
     sceneFrameUrl: string;
     characterImageUrl: string;
     /** A second, already-swapped keyframe for the END of the clip (Kling start+end). */
     endFrameUrl?: string;
+    /** Replaces the composed prompt entirely; `scope` and `preserve` are then ignored. */
     swapPrompt?: string;
+    scope?: SwapScope;
+    preserve?: string[];
     motionPrompt?: string;
     editModel?: string;
     /** Explicit video model; when absent, Seedance for one frame, Kling when endFrameUrl is set. */
@@ -2645,4 +2859,4 @@ declare function parseArgs(argv: string[]): CliArgs;
 declare function createHttpHandler(): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 declare function main(argv?: string[]): Promise<void>;
 
-export { type AllTenantsUsageResponse, type Binding, CHARACTER_SHEET_DEFINITION, CHARACTER_SHEET_NODES, type CharacterReference, type CharacterSummary, type CharacterSwapInput, ConfigError, ContractError, type CreateServerOptions, DEFAULT_BASE_URL, DEFAULT_MOTION_PROMPT, DEFAULT_SWAP_EDIT_MODEL, DEFAULT_SWAP_PROMPT, DEFAULT_SWAP_VIDEO_MODEL, DEFAULT_TIMEOUT_MS, type DocumentSummary, type FetchLike, type JobResponse, type JobStatus, type JudgeCandidate, MINT_REFERENCE_CATEGORIES, type NodeResultResponse, type NodeRun, type NodeStatus, type NodeSummary, type NodeTypesResponse, type PollOptions, PollTimeoutError, type ProjectSummary, type Projection, type RemovedNode, type RunResponse, type RunStartResponse, type RunStatus, SERVER_NAME, SERVER_VERSION, SUMMARY_TEXT_CHARS, type SpendLedger, StudioApiError, StudioClient, type StudioClientOptions, type StudioConfig, type StudioMcp, type SummaryMeta, TOOLS, TOOL_NAMES, type TaskDescriptor, type TenantSpendSummary, type TenantUsageResponse, type ToolContext, type ToolDef, ToolInputError, type ToolResult, type TurnaroundView, type UploadFile, type UsageByModel, type UsageResponse, WORKFLOW_TOOLS, type WorkflowApplyResponse, type WorkflowCreateResponse, type WorkflowDefinition, type WorkflowDocumentResponse, type WorkflowNode, type WorkflowValidateResponse, affectedNodes, buildCharacterSheetParams, buildCharacterSwapDefinition, categoryForNode, characterSheetDefinition, createHttpHandler, createStudioMcpServer, extensionForMime, filenameFromUrl, invokeTool, main, mimeForFilename, parseArgs, parseDocument, parseOps, pollUntil, projectionOf, redactSecret, registerTools, resolveConfig, seedFacePrompt, studioWorkflowApply, studioWorkflowCreate, studioWorkflowDescribe, studioWorkflowGet, studioWorkflowScreenshot, studioWorkflowValidate, summarizeDocument, summarizeNode, touchedNodeIds, turnaroundViewPrompt, waitForJob, waitForRun };
+export { type AllTenantsUsageResponse, type Binding, CHARACTER_SHEET_DEFINITION, CHARACTER_SHEET_NODES, type CharacterReference, type CharacterSummary, type CharacterSwapInput, ConfigError, ContractError, type CreateServerOptions, DEFAULT_BASE_URL, DEFAULT_MOTION_PROMPT, DEFAULT_SWAP_EDIT_MODEL, DEFAULT_SWAP_PROMPT, DEFAULT_SWAP_VIDEO_MODEL, DEFAULT_TIMEOUT_MS, type DocumentSummary, type FetchLike, type JobResponse, type JobStatus, type JudgeCandidate, MINT_REFERENCE_CATEGORIES, type NodeResultResponse, type NodeRun, type NodeStatus, type NodeSummary, type NodeTypesResponse, type PollOptions, PollTimeoutError, type ProjectSummary, type Projection, type RemovedNode, type RunResponse, type RunStartResponse, type RunStatus, SERVER_NAME, SERVER_VERSION, SUMMARY_TEXT_CHARS, SWAP_SCOPES, type SpendLedger, StudioApiError, StudioClient, type StudioClientOptions, type StudioConfig, type StudioMcp, type SummaryMeta, type SwapPromptOptions, type SwapScope, TOOLS, TOOL_NAMES, type TaskDescriptor, type TenantSpendSummary, type TenantUsageResponse, type ToolContext, type ToolDef, ToolInputError, type ToolResult, type TurnaroundView, type UploadFile, type UsageByModel, type UsageResponse, WORKFLOW_TOOLS, type WorkflowApplyResponse, type WorkflowCreateResponse, type WorkflowDefinition, type WorkflowDocumentResponse, type WorkflowNode, type WorkflowValidateResponse, affectedNodes, buildCharacterSheetParams, buildCharacterSwapDefinition, categoryForNode, characterSheetDefinition, composeSwapPrompt, createHttpHandler, createStudioMcpServer, extensionForMime, filenameFromUrl, invokeTool, main, mimeForFilename, parseArgs, parseDocument, parseOps, pollUntil, projectionOf, redactSecret, registerTools, resolveConfig, seedFacePrompt, studioWorkflowApply, studioWorkflowCreate, studioWorkflowDescribe, studioWorkflowGet, studioWorkflowScreenshot, studioWorkflowValidate, summarizeDocument, summarizeNode, touchedNodeIds, turnaroundViewPrompt, waitForJob, waitForRun };