@kolbo/mcp 1.99.1 → 1.101.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.99.1",
+  "version": "1.101.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/apps/index.js

@@ -612,11 +612,19 @@ function sibling(models, hit, types) {
  * unchanged, so identifiers the catalog does not publish (hidden models) still
  * reach the API and it stays the source of truth.
  */
+const NATIVE_WORKFLOW_MODEL_IDS = new Set([
+  'kolbo-morphious-motion', 'kolbo-morphious-swap', 'kolbo-morphious-reframe',
+  'kolbo-morphious-lite-motion', 'kolbo-morphious-lite-swap',
+  'higgsfield-genjutsu-motion-transfer', 'higgsfield-genjutsu-object-swap',
+]);
 async function canonicalModelId(client, input, type) {
   if (!input || typeof input !== 'string') return input;
   const key = input.toLowerCase().trim();
   const want = normId(key);
-  if (!want || AUTO_ALIASES.has(want)) return input;
+  if (!want || AUTO_ALIASES.has(want)) return input;
+  // Exact native-workflow ids pass through: the near-miss check below would reject an
+  // unpublished or cached-out 'kolbo-*' id as unknown.
+  if (NATIVE_WORKFLOW_MODEL_IDS.has(key)) return input;
 
   let all;
   try {

package/src/toolAnnotations.js

@@ -33,6 +33,8 @@ const READ_ONLY = [
   'get_music_track_related', 'get_music_track_lyrics',
   'search_stock_media', 'get_stock_sources', 'get_stock_categories',
   'get_stock_collections', 'get_stock_asset', 'analyze_script_for_stock',
+  // Free (no credits, no DB write) — returns a scratch composition plan for the caller to edit.
+  'create_music_composition_plan',
 ];
 
 const OPEN_WORLD_READ_ONLY = [
@@ -85,6 +87,9 @@ const DESTRUCTIVE_WRITE = [
   'generate_image', 'generate_image_edit', 'generate_creative_director',
   'generate_video', 'generate_video_from_image', 'generate_music',
   'generate_speech', 'generate_sound', 'cancel_generation',
+  // Both spend credits — reference-audio upload is billed by ElevenLabs like a generation,
+  // section edit creates a new billed track.
+  'create_music_reference_audio', 'edit_music_section',
   'generate_elements', 'generate_first_last_frame', 'generate_lipsync',
   'generate_video_from_video', 'transcribe_audio', 'generate_3d',
   'edit_image', 'edit_video', 'trim_video', 'clone_voice',

package/src/tools/generate.js

@@ -57,6 +57,27 @@ const CINEMATIC_SCHEMA = z.object({
 // alongside the prompt (generate_video_from_image: `{ image_url, prompt }` — the
 // image is what varies, and that is the whole point). Either way the widget
 // captions each tile with the item's prompt, so that is the label we carry.
+// ElevenLabs Music v2.5 composition-plan chunk — one entry is EITHER a generation chunk
+// (text/duration_ms/positive_styles, optionally conditioning_ref to steer its style off a
+// stored song) OR an audio-reference chunk (song_id/range, splices that slice in unchanged).
+// All fields optional at the schema level; the backend validates the real constraints
+// (3-120s per generation chunk, <=30s conditioning reference, <=30 chunks per plan).
+const MUSIC_TIME_RANGE_SCHEMA = z.object({
+  start_ms: z.number().int().min(0),
+  end_ms: z.number().int().min(0),
+}).describe('{ start_ms, end_ms } — a slice of a stored song, in milliseconds.');
+const MUSIC_CHUNK_SCHEMA = z.object({
+  text: z.string().optional().describe('Generation chunk only: section name in [brackets], lyric lines, {inline directions}. E.g. "[Chorus]\\nWe rise tonight".'),
+  duration_ms: z.number().int().min(3000).max(120000).optional().describe('Generation chunk only: length in ms, 3000-120000.'),
+  positive_styles: z.array(z.string()).optional().describe('Generation chunk only: styles/directions to include (max 50). The first chunk\'s styles set the whole song\'s tone.'),
+  negative_styles: z.array(z.string()).optional().describe('Generation chunk only: styles/directions to avoid.'),
+  context_adherence: z.enum(['low', 'medium', 'high']).optional().describe('Generation chunk only: how closely it follows neighboring chunks. Default high.'),
+  conditioning_ref: z.object({ song_id: z.string(), range: MUSIC_TIME_RANGE_SCHEMA }).optional().describe('Generation chunk only: condition this chunk\'s STYLE on <=30s of a stored song (does not splice audio in — it steers a fresh generation).'),
+  condition_strength: z.enum(['low', 'medium', 'high', 'xhigh']).optional().describe('Generation chunk only: how strongly it follows conditioning_ref. Default medium.'),
+  song_id: z.string().optional().describe('Audio-reference chunk only: id of a stored song (from a prior generate_music result\'s song_id, or create_music_reference_audio) to splice in unchanged.'),
+  range: MUSIC_TIME_RANGE_SCHEMA.optional().describe('Audio-reference chunk only: the slice of song_id to insert unchanged.'),
+});
+
 const MAX_BATCH_PROMPTS = 8;
 const MAX_STATUS_IDS = 20;
 async function submitBatch(rawItems, submitOne) {
@@ -212,6 +233,15 @@ const promptsField = (what) => z.array(z.string()).max(MAX_BATCH_PROMPTS).option
   `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. **Hard cap: ${MAX_BATCH_PROMPTS} prompts per call — more than that is REJECTED with an error (never silently truncated), so split a longer list across several calls of at most ${MAX_BATCH_PROMPTS}.** Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
 );
 
+// Native workflows: exactly one source video, prompt optional (the server analyzes the media).
+const MORPHIOUS_MODELS = new Set(['kolbo-morphious-motion', 'kolbo-morphious-swap', 'kolbo-morphious-reframe', 'kolbo-morphious-lite-motion', 'kolbo-morphious-lite-swap']);
+const PROMPTLESS_NATIVE = new Set([...MORPHIOUS_MODELS, 'higgsfield-genjutsu-motion-transfer', 'higgsfield-genjutsu-object-swap']);
+const MORPHIOUS_GUIDE = ' MORPHIOUS / GENJUTSU (exactly ONE source video, omit duration - it comes from the source): higgsfield-genjutsu-motion-transfer and higgsfield-genjutsu-object-swap accept an omitted prompt, and so do the kolbo-morphious-* models (Morphious only needs the source video and references; it analyzes them itself). '
+  + 'kolbo-morphious-motion 1-30 images, 4-30s; kolbo-morphious-swap 0-30 images, 4-30s; both 480p/720p/1080p, output keeps the source shape. '
+  + 'Lite (kolbo-morphious-lite-motion 1-10 images / kolbo-morphious-lite-swap 0-10 images) caps at 15s. '
+  + 'kolbo-morphious-reframe: NO images/DNA, 1-300s, aspect_ratio REQUIRED (16:9, 9:16, 1:1, 4:3, 3:4, 21:9), 540p or 720p. '
+  + 'higgsfield-genjutsu-motion-transfer / -object-swap: 1-8 images or Visual DNA, 4-30s, 480p/720p/1080p.';
+
 function registerGenerateTools(server, client, options = {}) {
   // Every JSON POST from these tools rehosts local file paths into the media
   // library first (see local-rehost.js) — the API only understands URLs.
@@ -797,7 +827,7 @@ function registerGenerateTools(server, client, options = {}) {
     'generate_music',
     'Generate music from a text description using Kolbo AI. Supports instrumental mode, custom lyrics, style direction, vocal gender, negative tags, song length, and Suno fine-controls (style weight, weirdness, audio weight, persona/singing voice). Default model is Suno. Some controls are Suno-only; the engine ignores controls that do not apply to the chosen model. Returns the final audio URL when complete.',
     {
-      prompt: z.string().describe('Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers")'),
+      prompt: z.string().optional().describe('Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers"). Required unless composition_plan is passed (ElevenLabs Music v2.5 structured mode, which cannot be combined with prompt).'),
       model: z.string().optional().describe('Model identifier. Use list_models type="music_gen" to see options. Omit for Suno (default).'),
       style: z.string().optional().describe('Music style / genre (e.g., "pop", "rock", "lo-fi", "electronic", "jazz")'),
       title: z.string().optional().describe('Song title. If omitted, one is generated.'),
@@ -816,16 +846,22 @@ function registerGenerateTools(server, client, options = {}) {
       use_composition_plan: z.boolean().optional().describe('Suno: enable structured composition planning (verse/chorus structure).'),
       singing_dna_id: z.string().optional().describe('Visual DNA character id whose singing voice to use (must be owned by the caller).'),
       singing_voice_id: z.string().optional().describe('Custom cloned singing-voice id (must be owned by the caller).'),
+      // ── ElevenLabs Music v2.5 structured mode (mutually exclusive with `prompt`) ──
+      composition_plan: z.array(MUSIC_CHUNK_SCHEMA).optional().describe('ElevenLabs Music v2.5 ONLY, model must resolve to the ElevenLabs music model: an ordered list of chunks instead of a prompt. A GENERATION chunk has text/duration_ms/positive_styles (optionally conditioning_ref+condition_strength to steer it off a stored song). An AUDIO-REFERENCE chunk has song_id/range and splices that stored slice in unchanged (used to keep part of an existing track — see edit_music_section for the common case of regenerating one section). Get a starter plan from create_music_composition_plan, or build one from a prior generate_music result\'s `song_id`. Cannot be combined with `prompt`.'),
+      seed: z.number().optional().describe('ElevenLabs Music v2.5: random seed for reproducibility. Only valid together with composition_plan, never with prompt.'),
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id, session_id }) => {
+    async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt = false, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, composition_plan, seed, project_id, session_id }) => {
+      if (!prompt && !composition_plan) throw new Error('prompt is required (or pass composition_plan for ElevenLabs Music v2.5)');
       model = await canonicalModelId(client, model, 'music_gen'); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/music', {
         prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags,
         duration_seconds, enhance_prompt, preset_id,
         style_weight, weirdness, audio_weight, persona_id, use_composition_plan,
-        singing_dna_id, singing_voice_id, project_id, session_id
+        singing_dna_id, singing_voice_id,
+        ...(composition_plan ? { composition_plan: { chunks: composition_plan }, seed } : {}),
+        project_id, session_id
       });
 
       if (returnsImmediately()) return submittedResult({
@@ -855,11 +891,99 @@ function registerGenerateTools(server, client, options = {}) {
         playback_urls: result.result.playback_urls,
         title: result.result.title,
         duration: result.result.duration,
-        lyrics: result.result.lyrics
+        lyrics: result.result.lyrics,
+        // ElevenLabs Music v2.5 only — reuse in a later composition_plan / edit_music_section.
+        ...(result.result.song_id ? { song_id: result.result.song_id } : {}),
       }, null, 2));
     }
   );
 
+  // ─── create_music_composition_plan ─────────────────────────
+  // FREE (no credits, no generation created) — ElevenLabs Music v2.5's POST /v1/music/plan.
+  server.tool(
+    'create_music_composition_plan',
+    'Generate a starter ElevenLabs Music v2.5 structured composition plan (an ordered list of chunks with section text, styles, and durations) from a plain-text prompt. FREE — creates no generation and charges no credits. Edit the returned chunks and pass them as `composition_plan` to generate_music to actually create the track.',
+    {
+      prompt: z.string().describe('Text description of the song to plan (e.g. "an upbeat pop song with verse and chorus about summer").'),
+      duration_seconds: z.number().optional().describe('Target total length in seconds, 3-600. Omit to let the model choose.'),
+      project_id: projectIdField,
+      session_id: sessionIdField,
+    },
+    async ({ prompt, duration_seconds, project_id, session_id }) => {
+      const res = await client.post('/v1/generate/music/composition-plan', { prompt, duration_seconds, project_id, session_id });
+      return { content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
+    }
+  );
+
+  // ─── create_music_reference_audio ───────────────────────────
+  // BILLED at the same rate as a song generation of the clip's length (ElevenLabs charges
+  // the upload itself, even half-price if it flags the clip for copyright) — this is NOT a
+  // free utility call, unlike create_music_composition_plan above.
+  server.tool(
+    'create_music_reference_audio',
+    'Upload an existing audio clip you already have in Kolbo so it can be used as an audio reference in a later generate_music composition_plan (as a song_id in a conditioning_ref, to steer style, or in an audio-reference chunk, to splice a slice in unchanged) or as the source for edit_music_section. BILLED the same as generating a track of the clip\'s length — ElevenLabs charges for this upload itself. LOCAL FILE? Call upload_media first and pass the returned media id here.',
+    {
+      media_id: z.string().describe('A media-library item id for an audio file you own — from upload_media, or from list_media (mediaType audio).'),
+      project_id: projectIdField,
+      session_id: sessionIdField,
+    },
+    async ({ media_id, project_id, session_id }) => {
+      const res = await client.post('/v1/generate/music/reference-audio', { media_id, project_id, session_id });
+      return { content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
+    }
+  );
+
+  // ─── edit_music_section ─────────────────────────────────────
+  // ElevenLabs Music v2.5 inpainting — regenerate one time range of an existing track,
+  // keeping the rest unchanged. BILLED like an ordinary generation (creates a new track).
+  server.tool(
+    'edit_music_section',
+    'Regenerate one section (time range) of an ElevenLabs Music v2.5 track you already generated, keeping the rest of the song unchanged — e.g. "redo the outro with different lyrics". Only works on tracks made with the ElevenLabs Music model (check the earlier generate_music result for a `song_id`; a track without one cannot be edited this way). Creates a NEW generation in the same session; the source track is untouched. Returns a generation_id to poll like any other generate_music call.',
+    {
+      source_generation_id: z.string().describe('The generation_id of the ElevenLabs Music v2.5 track to edit (must have returned a song_id).'),
+      start_ms: z.number().int().min(0).describe('Start of the region to regenerate, in milliseconds.'),
+      end_ms: z.number().int().min(0).describe('End of the region to regenerate, in milliseconds. (end_ms - start_ms) must be 3000-120000ms.'),
+      text: z.string().optional().describe('New section text — [Section Name], lyric lines, {inline directions}. Omit to keep it instrumental/unlabeled.'),
+      positive_styles: z.array(z.string()).optional().describe('Styles/directions for the regenerated section.'),
+      negative_styles: z.array(z.string()).optional().describe('Styles/directions to avoid in the regenerated section.'),
+      context_adherence: z.enum(['low', 'medium', 'high']).optional().describe('How closely the new section follows the kept audio around it. Default high.'),
+      project_id: projectIdField,
+      session_id: sessionIdField,
+    },
+    async ({ source_generation_id, start_ms, end_ms, text, positive_styles, negative_styles, context_adherence, project_id, session_id }) => {
+      const gen = await client.post('/v1/generate/music/edit-section', {
+        source_generation_id, start_ms, end_ms, text,
+        positive_styles, negative_styles, context_adherence,
+        project_id, session_id,
+      });
+
+      if (returnsImmediately()) return submittedResult({
+        tool: 'edit_music_section', kind: 'audio', gen, client, model: 'ElevenLabs Music', prompt: text || '(section edit)',
+      });
+
+      const poll = await pollOrTimedOut(client, gen.generation_id, { interval: (gen.poll_interval_hint || 8) * 1000, timeout: 150000 });
+      if (poll.timedOut) return poll.timedOut;
+      const result = poll.result;
+
+      return uiCompleted({
+        tool: 'edit_music_section', kind: 'audio', gen, client, model: 'ElevenLabs Music', prompt: text || '(section edit)',
+        urls: result.result.urls,
+        playback_urls: result.result.playback_urls,
+        title: result.result.title,
+        duration: result.result.duration,
+        credits_used: creditFields(result).credits_used,
+      }, JSON.stringify({
+        ...creditFields(result),
+        session_id: gen.session_id,
+        urls: result.result.urls,
+        playback_urls: result.result.playback_urls,
+        duration: result.result.duration,
+        ...(result.result.song_id ? { song_id: result.result.song_id } : {}),
+      }, null, 2));
+    }
+  );
+
+
   // ─── music import / extend / cover ─────────────────────────
   // Three tools over the SDK's /v1/generate/music/{import,extend,cover}. The web app has
   // had upload-extend and upload-cover for a long time; agents could not reach either
@@ -1434,9 +1558,9 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_elements ─────────────────────────────────────
   server.tool(
     'generate_elements',
-    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. SPECIAL MODEL EXCEPTION: seedance-2-5-multilingual accepts an ordinary prompt in any language with the ORIGINAL target-language dialogue in double quotes, including Hebrew script. Use this tool even without references for that model, duration 8 or 12, resolution 480p/720p/1080p (no Draft), up to 3 still references or Visual DNAs, no video/audio references. It performs translation, distinct designed voices and segmented lip sync internally; never transliterate or pre-translate its quoted dialogue. The following regular Seedance instructions apply only to other model IDs. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PRIMARY ROUTE FOR A DNA-ANCHORED MULTI-SHOT FILM: one call can carry the whole sequence — seedance-2-5 takes 4-30s, up to 30 shots and 20 Visual DNAs in a SINGLE generation (seedance-2: 4-15s, 9 DNAs) — instead of a stack of separate clips. DIALOGUE IS PERFORMED NATIVELY: quoted dialogue in the prompt comes back as synced voices with lip movement, room tone and the SFX named in the AUDIO block — never route scene dialogue to generate_speech or generate_lipsync. Write dialogue in ENGLISH or Latin transliteration of Hebrew ("shalom"), never Hebrew script — Seedance does not speak Hebrew; prefer Gemini Omni Flash 1.1 or Gemini Omni 1 for native Hebrew. COST: resolution is a multiplier. When list_models publishes `video_input_credit` and this call carries videos, charge that rate against nominal input seconds + nominal output seconds; MP4 padding within 0.15s of an integer snaps to that integer and larger fractions round up. Otherwise use the normal output-second rate. PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers and durations of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio plus min_video_duration / max_video_duration before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.',
+    'Generate a video from reference elements (images, videos, and/or audio) + a text prompt. SPECIAL MODEL EXCEPTION: seedance-2-5-multilingual accepts an ordinary prompt in any language with the ORIGINAL target-language dialogue in double quotes, including Hebrew script. Use this tool even without references for that model, duration 8 or 12, resolution 480p/720p/1080p (no Draft), up to 3 still references or Visual DNAs, no video/audio references. It performs translation, distinct designed voices and segmented lip sync internally; never transliterate or pre-translate its quoted dialogue. The following regular Seedance instructions apply only to other model IDs. Use when the user wants to animate specific uploaded/referenced assets — e.g. "animate this product", "put these 3 characters into a scene". PRIMARY ROUTE FOR A DNA-ANCHORED MULTI-SHOT FILM: one call can carry the whole sequence — seedance-2-5 takes 4-30s, up to 30 shots and 20 Visual DNAs in a SINGLE generation (seedance-2: 4-15s, 9 DNAs) — instead of a stack of separate clips. DIALOGUE IS PERFORMED NATIVELY: quoted dialogue in the prompt comes back as synced voices with lip movement, room tone and the SFX named in the AUDIO block — never route scene dialogue to generate_speech or generate_lipsync. Write dialogue in ENGLISH or Latin transliteration of Hebrew ("shalom"), never Hebrew script — Seedance does not speak Hebrew; prefer Gemini Omni Flash 1.1 or Gemini Omni 1 for native Hebrew. COST: resolution is a multiplier. When list_models publishes `video_input_credit` and this call carries videos, charge that rate against nominal input seconds + nominal output seconds; MP4 padding within 0.15s of an integer snaps to that integer and larger fractions round up. Otherwise use the normal output-second rate. PROMPT CONTRACT (Seedance / Elements): Locked Intro only — Total line, then [GLOBAL LOOK] / [CAST] / [LOCATION] / SHOT N. Do NOT write SCENE CONTEXT / OPTICS / ACTION department packs. Every Visual DNA in visual_dna_ids MUST also appear in the prompt as @ExactDNAName (e.g. "@Zohar walks…") — never "Zohar\'s" or "the man on the left" as a substitute. IMPORTANT: different models accept different numbers and durations of inputs — call list_models type="elements" and read elements_max_images / elements_max_videos / elements_max_audio plus min_video_duration / max_video_duration before generating. For text-only → video use generate_video instead. For animating a single still image use generate_video_from_image. Returns the final video URL when complete.' + MORPHIOUS_GUIDE,
     {
-      prompt: z.string().describe('For seedance-2-5-multilingual: ordinary scene description with original target-language dialogue in double quotes; no manual translation or transliteration. For other models, Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name. EVERY attached reference must also be tagged by its 1-based array position — `@Image 1`/`@Image 2` (reference_images), `@Video 1` (reference_videos), `@Audio 1` (reference_audio_urls) — and its job stated ("@Image 1 defines the character\'s face and wardrobe", "@Video 1 defines the camera move"). An untagged attachment is ignored by the engine even though it was uploaded and billed.'),
+      prompt: z.string().optional().describe('Optional ONLY for kolbo-morphious-* and higgsfield-genjutsu-* models (the server analyzes the media). For seedance-2-5-multilingual: ordinary scene description with original target-language dialogue in double quotes; no manual translation or transliteration. For other models, Locked Intro prompt (Seedance/Elements): Total line, [GLOBAL LOOK], [CAST] with @ExactDNAName for every visual_dna_ids entry, [LOCATION], then SHOT N. Not SCENE CONTEXT/OPTICS/ACTION packs. Never substitute "the left man" or "Zohar\'s" for @Name. EVERY attached reference must also be tagged by its 1-based array position — `@Image 1`/`@Image 2` (reference_images), `@Video 1` (reference_videos), `@Audio 1` (reference_audio_urls) — and its job stated ("@Image 1 defines the character\'s face and wardrobe", "@Video 1 defines the camera move"). An untagged attachment is ignored by the engine even though it was uploaded and billed.'),
       model: z.string().optional().describe('Model identifier. If the user already named a family (Grok / Kling / Veo / Seedance / …), pass THAT family — never default to Seedance because Elements often uses it. Use list_models type="elements" for exact ids and elements_max_* caps. Do NOT omit (omitting = Smart Select).'),
       reference_images: z.array(z.string()).optional().describe('Array of image references (product shots, character references, etc.). Tag each one in the prompt text by its 1-based position here — item 1 is `@Image 1`, item 2 is `@Image 2` — or the engine ignores it. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.**'),
       reference_videos: z.array(z.string()).optional().describe('Array of reference videos for models that accept video inputs. Tag each one in the prompt text by its 1-based position here — `@Video 1`, `@Video 2` — stating what it defines (motion, camera move, pacing), or the engine ignores it. Accepts a public URL (forwarded as-is; if the API rejects an external URL as untrusted, it is auto-rehosted into the media library and retried once) OR an absolute local path, which is uploaded for you. **Cap: pass at most `elements_max_videos` URLs and keep every clip within `min_video_duration`-`max_video_duration` from list_models.** If `video_input_credit` is present, every attached video contributes its nominal duration to combined-second billing: encoder padding within 0.15s of an integer snaps to it; larger fractions round up.'),
@@ -1462,14 +1586,14 @@ function registerGenerateTools(server, client, options = {}) {
       project_id: projectIdField,
       session_id: sessionIdField
     },
-    async ({ prompt, model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, draft, sound_enabled, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id }) => {
+    async ({ prompt = '', model, reference_images, reference_videos, reference_audio_urls, audio_url, files, duration, aspect_ratio, motion, preset_id, enhance_prompt = false, visual_dna_ids, resolution, draft, sound_enabled, keyframes, multi_shots, multi_shot_count, session_name, project_id, session_id }) => {
       validateVideoPrompt({ prompt, duration, aspect_ratio, multi_shots, multi_shot_count });
       if (draft === true) resolution = '480p-draft';
       else if (draft === false && resolution?.endsWith('-draft')) resolution = resolution.slice(0, -6);
       model = await canonicalModelId(client, model, 'elements'); // lenient id resolution ("z-image" → "z-image/turbo")
       aspect_ratio = await resolveCatalogAspectRatio(client, model, aspect_ratio, 'elements');
       validateVideoPrompt({ prompt, duration, aspect_ratio, multi_shots, multi_shot_count });
-      if (!prompt) throw new Error('prompt is required');
+      if (!prompt && !PROMPTLESS_NATIVE.has(model)) throw new Error('prompt is required');
 
       // Elements is the one tool that takes all three modalities, and either a
       // URL or a local path for any of them. Bucket every input by the kind the
@@ -1855,10 +1979,10 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_video_from_video ─────────────────────────────
   server.tool(
     'generate_video_from_video',
-    'Restyle / transform an existing video (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, character replacement, or burning in styled subtitles (VEED Subtitles). Source video can be a URL or absolute local path. `prompt` is OPTIONAL: most models need it, but prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control) ignore it. For VEED Subtitles, pass a `preset` style and optional `source_language` / `translation_language` instead of a prompt. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read max_images / max_videos / max_elements on the chosen model before generating. Pass reference_images for models with max_images > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with max_videos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with max_elements > 0. REPAIR / RETIME (not restyling, no prompt needed — these keep the footage and fix or retime it): model "topaz/deblur/video" removes lens, motion and compression blur; "topaz/colorize/video" colorizes black-and-white footage; "topaz/interpolate/video" is SLOW MOTION and frame-rate conversion (see slowdown_factor / target_fps); "topaz/sdr-to-hdr/video" masters SDR footage to HDR (see output_format). Reach for these when the user says blurry, shaky-detail, black-and-white, slow motion, smoother frame rate, or HDR — a restyle model would repaint the video instead of repairing it. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.',
+    'Restyle / transform an existing video (video-to-video). Use for style transfer, scene restyling, subject swap, motion transfer, character replacement, or burning in styled subtitles (VEED Subtitles). Source video can be a URL or absolute local path. `prompt` is OPTIONAL: most models need it, but prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control) ignore it. For VEED Subtitles, pass a `preset` style and optional `source_language` / `translation_language` instead of a prompt. IMPORTANT: different models support different extra inputs — call list_models type="video_to_video" and read max_images / max_videos / max_elements on the chosen model before generating. Pass reference_images for models with max_images > 0 (e.g. Kling O1/O3, Aleph, WAN VACE), reference_videos for models with max_videos > 1 (e.g. WAN 2.6 reference-to-video accepts up to 3), and elements for models with max_elements > 0. REPAIR / RETIME (not restyling, no prompt needed — these keep the footage and fix or retime it): model "topaz/deblur/video" removes lens, motion and compression blur; "topaz/colorize/video" colorizes black-and-white footage; "topaz/interpolate/video" is SLOW MOTION and frame-rate conversion (see slowdown_factor / target_fps); "topaz/sdr-to-hdr/video" masters SDR footage to HDR (see output_format). Reach for these when the user says blurry, shaky-detail, black-and-white, slow motion, smoother frame rate, or HDR — a restyle model would repaint the video instead of repairing it. For animating a still image use generate_video_from_image instead. For text-only → video use generate_video.' + MORPHIOUS_GUIDE,
     {
       source_video: z.string().describe('URL or absolute local path to the primary source video to restyle. **Source duration must fall within `min_video_duration`-`max_video_duration` from list_models for the chosen model** — videos outside that range are rejected (or silently truncated by some upstream providers). For models that use reference_videos as their primary input (e.g. WAN 2.6 reference-to-video), pass the first reference video here and also include it in reference_videos.'),
-      prompt: z.string().optional().describe('Text description of the desired restyle / transformation. Required by most video-to-video models; omit for prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control).'),
+      prompt: z.string().optional().describe('Text description of the desired restyle / transformation. Required by most video-to-video models; omit for prompt-less models (VEED Subtitles, Act Two, Wan Animate, Kling Motion Control, kolbo-morphious-*, higgsfield-genjutsu-motion-transfer, higgsfield-genjutsu-object-swap).'),
       model: z.string().optional().describe('Model identifier. Use list_models type="video_to_video" to see options and check max_images / max_videos / max_elements / max_video_duration per model. Pick a SPECIFIC model — do NOT omit (omitting = Smart Select auto-pick, which we avoid); call list_models for this type and choose the model that best fits the user\'s intent.'),
       aspect_ratio: z.string().optional().describe(aspectRatioDescribe() + ' Default: matches source.'),
       duration: z.number().optional().describe('Output duration in seconds. Must be in `supported_durations` from list_models, OR within `min_output_duration`-`max_output_duration`. Default: matches source'),

package/src/tools/video-prompt.js

@@ -1,6 +1,6 @@
 // Validate only explicit, machine-readable declarations. Never infer creative
 // intent from adjectives, require a template, or rewrite a user's prompt.
-function validateVideoPrompt({ prompt, duration, aspect_ratio, multi_shots, multi_shot_count }) {
+function validateVideoPrompt({ prompt = '', duration, aspect_ratio, multi_shots, multi_shot_count }) {
   const totals = [...prompt.matchAll(/^\s*Total:\s*(\d+(?:\.\d+)?)s\s*\/\s*(\d+)\s*shots?\s*\/\s*(\d+:\d+)\s*$/gim)]
     .map((m) => ({ duration: Number(m[1]), count: Number(m[2]), aspect: m[3] }));
   if (!totals.length) return; // Existing free-form clients remain supported.