@pixeldojo/mcp 0.9.1 → 0.10.0

package/dist/index.js

@@ -183,19 +183,23 @@ var init_upload_helpers = __esm({
 });
 
 // src/skills/schema-snap.ts
-function getFieldConstraints(apiId, client) {
+function getModelInfo(apiId, client) {
   const cached = schemaCache.get(apiId);
   if (cached) return cached;
   if (typeof client?.getModelSchema !== "function") return Promise.resolve(null);
-  const pending = Promise.resolve().then(() => client.getModelSchema(apiId)).then(
-    (res) => res.schema?.properties ?? {}
-  ).catch(() => {
+  const pending = Promise.resolve().then(() => client.getModelSchema(apiId)).then((res) => {
+    const body = res;
+    return { props: body.schema?.properties ?? {}, media: body.media };
+  }).catch(() => {
     schemaCache.delete(apiId);
     return null;
   });
   schemaCache.set(apiId, pending);
   return pending;
 }
+async function getFieldConstraints(apiId, client) {
+  return (await getModelInfo(apiId, client))?.props ?? null;
+}
 function parseAspectRatio(ar) {
   const m = /^\s*(\d+)\s*:\s*(\d+)\s*$/.exec(ar);
   if (!m) return null;
@@ -231,11 +235,20 @@ async function snapAspectRatio(apiId, requested, client, opts = {}) {
   if (!field.enum || field.enum.length === 0) return requested;
   return nearestAspectFromEnum(requested, field.enum);
 }
-async function resolveReferenceField(apiId, client) {
-  const props = await getFieldConstraints(apiId, client);
-  if (props === null) return void 0;
-  for (const name of REFERENCE_FIELD_PRIORITY) {
-    const field = props[name];
+async function resolveMediaSlot(apiId, kind, client) {
+  const info = await getModelInfo(apiId, client);
+  if (info === null) return void 0;
+  const declared = info.media?.[kind];
+  if (declared) {
+    return {
+      name: declared.key,
+      isArray: info.props[declared.key]?.type === "array",
+      also: declared.also
+    };
+  }
+  if (info.media && kind !== "audio") return null;
+  for (const name of FALLBACK_KEYS[kind]) {
+    const field = info.props[name];
     if (field) return { name, isArray: field.type === "array" };
   }
   return null;
@@ -295,21 +308,29 @@ async function snapDuration(apiId, requested, client, opts = {}) {
   }
   return requested;
 }
+function isVideoUrl(url) {
+  return /\.(mp4|mov|webm|m4v)(?:[?#]|$)/i.test(url);
+}
+function isAudioUrl(url) {
+  return /\.(mp3|wav|m4a|aac|ogg|flac)(?:[?#]|$)/i.test(url);
+}
 async function resolveImageRefs(apiId, urls, client) {
   if (urls.length === 0) return null;
-  const props = await getFieldConstraints(apiId, client);
-  if (props === null) return null;
-  const key = REF_KEYS.find((k) => props[k] !== void 0);
+  const info = await getModelInfo(apiId, client);
+  if (info === null) return null;
+  const props = info.props;
+  const key = info.media ? info.media.image?.key : REF_KEYS.find((k) => props[k] !== void 0);
   if (!key) return null;
-  const field = props[key];
+  const also = info.media?.image?.also;
+  const field = props[key] ?? {};
   if (field.type === "array") {
     const cap = typeof field.maxItems === "number" ? field.maxItems : urls.length;
     const kept = urls.slice(0, Math.max(1, cap));
-    return { key, value: kept, dropped: urls.length - kept.length };
+    return { key, value: kept, dropped: urls.length - kept.length, also };
   }
-  return { key, value: urls[0], dropped: urls.length - 1 };
+  return { key, value: urls[0], dropped: urls.length - 1, also };
 }
-var schemaCache, REFERENCE_FIELD_PRIORITY, REF_KEYS;
+var schemaCache, REFERENCE_FIELD_PRIORITY, FALLBACK_KEYS, REF_KEYS;
 var init_schema_snap = __esm({
   "src/skills/schema-snap.ts"() {
     schemaCache = /* @__PURE__ */ new Map();
@@ -325,6 +346,11 @@ var init_schema_snap = __esm({
       "image_input",
       "images"
     ];
+    FALLBACK_KEYS = {
+      image: REFERENCE_FIELD_PRIORITY,
+      video: ["reference_videos"],
+      audio: ["reference_audios", "audio_url"]
+    };
     REF_KEYS = [
       "image_urls",
       "images",
@@ -337,7 +363,51 @@ var init_schema_snap = __esm({
     ];
   }
 });
-function buildPayload(apiId, input, refField, referenceUrls = []) {
+function paramsWithoutModel(params, model) {
+  if (!params || Object.keys(params).length === 0) return null;
+  if (model) return null;
+  return "Those settings are model-specific. Tell me which model to use and I will apply them.";
+}
+function applyParams(body, params, paramsModel, apiId) {
+  if (!params || Object.keys(params).length === 0) return void 0;
+  if (paramsModel !== apiId) {
+    return `This ran on ${apiId}, so I left those settings off: they are ${paramsModel}'s fields. Ask again naming ${apiId} if you want them applied.`;
+  }
+  const rest = { ...params };
+  delete rest.prompt;
+  Object.assign(body, rest);
+  return "prompt" in params ? "I kept the prompt from the skill call and ignored the one in params." : void 0;
+}
+function prefixNote(result, note) {
+  if (!note) return result;
+  return { ...result, text: `${note} ${result.text}`.trim() };
+}
+var ParamsInput, PARAMS_JSON_SCHEMA;
+var init_params = __esm({
+  "src/skills/params.ts"() {
+    ParamsInput = z.record(z.unknown()).optional();
+    PARAMS_JSON_SCHEMA = {
+      type: "object",
+      additionalProperties: true,
+      description: 'Advanced settings for the model that runs this, named exactly as that model documents them (e.g. {"resolution": "1080p", "seed": 42}). Set `model` in the same call: field names differ per model, so params without one are refused. Applied last, so these override anything derived from the other inputs. An invalid field comes back named with its allowed values and nothing is charged, so fix it and call again.'
+    };
+  }
+});
+function fallbackSlot(apiId, kind) {
+  return apiId === VIDEO_REFERENCE_MODEL ? VIDEO_REFERENCE_SLOTS[kind] : void 0;
+}
+function sourceMedia(videoUrl, referenceUrls) {
+  const clip = videoUrl && !isAudioUrl(videoUrl) ? videoUrl : void 0;
+  const stills = referenceUrls.filter((u) => !isAudioUrl(u));
+  const url = clip ?? stills[0];
+  return {
+    url,
+    isClip: Boolean(clip) || !!url && isVideoUrl(url),
+    audioUrl: [videoUrl, ...referenceUrls].find((u) => u && isAudioUrl(u)),
+    stills
+  };
+}
+function buildPayload(apiId, input, src, slot, audioSlot) {
   const body = { prompt: input.prompt };
   if (input.aspect_ratio) body.aspect_ratio = input.aspect_ratio;
   if (input.preset) body.preset = input.preset;
@@ -345,9 +415,9 @@ function buildPayload(apiId, input, refField, referenceUrls = []) {
     case "grok-video-extend":
     case "wan-video-edit":
     case "seedance-video-edit":
-      if (input.image_url) {
-        body.video_url = input.image_url;
-        body.image_url = input.image_url;
+      if (src.url) {
+        body.video_url = src.url;
+        body.image_url = src.url;
       }
       if (input.duration !== void 0) {
         body.video_duration = input.duration;
@@ -355,14 +425,19 @@ function buildPayload(apiId, input, refField, referenceUrls = []) {
       }
       break;
     default:
-      if (input.image_url) {
-        const refs = referenceUrls.length > 0 ? referenceUrls : [input.image_url];
-        if (refField) {
-          body[refField.name] = refField.isArray ? refs : refs[0];
+      if (src.url) {
+        const refs = src.isClip ? [src.url] : src.stills.length > 0 ? src.stills : [src.url];
+        if (slot) {
+          body[slot.name] = slot.isArray ? refs : refs[0];
+          if (slot.also) Object.assign(body, slot.also);
         } else {
           body.image_url = refs[0];
         }
       }
+      if (src.audioUrl && audioSlot) {
+        body[audioSlot.name] = audioSlot.isArray ? [src.audioUrl] : src.audioUrl;
+        if (audioSlot.also) Object.assign(body, audioSlot.also);
+      }
       if (input.duration !== void 0) body.duration = input.duration;
       if (input.resolution) body.resolution = input.resolution;
       break;
@@ -370,7 +445,8 @@ function buildPayload(apiId, input, refField, referenceUrls = []) {
   return body;
 }
 async function run(input, ctx) {
-  const apiId = input.model ?? DEFAULT_MODEL;
+  const paramsGate = paramsWithoutModel(input.params, input.model);
+  if (paramsGate) return { kind: "text", text: paramsGate };
   let resolved = input;
   let referenceUrls = [];
   try {
@@ -391,11 +467,22 @@ async function run(input, ctx) {
     }
     throw err;
   }
+  const src = sourceMedia(input.video_url, referenceUrls);
+  let apiId = input.model ?? DEFAULT_MODEL;
+  let routeNote;
+  if ((src.isClip || src.audioUrl) && !VIDEO_INPUT_MODELS.has(apiId)) {
+    if (!input.model) {
+      apiId = VIDEO_REFERENCE_MODEL;
+    } else if (src.isClip && await resolveMediaSlot(input.model, "video", ctx.client) === null) {
+      apiId = VIDEO_REFERENCE_MODEL;
+      routeNote = `${input.model} can't work from a video clip, so I used ${VIDEO_REFERENCE_MODEL} instead.`;
+    }
+  }
   if (apiId === "grok-video-extend") {
-    if (!resolved.image_url) {
+    if (!src.url) {
       return {
         kind: "text",
-        text: 'pixeldojo_generate with model="grok-video-extend" requires image_url (the source video URL to extend, or image_path for a local file).'
+        text: 'pixeldojo_generate with model="grok-video-extend" requires video_url (the source video URL to extend, or image_path for a local file).'
       };
     }
     if (resolved.duration === void 0) {
@@ -406,17 +493,22 @@ async function run(input, ctx) {
     }
   }
   let refField;
+  let audioSlot;
   if (!VIDEO_INPUT_MODELS.has(apiId)) {
-    const [aspect_ratio, duration, resolution, ref] = await Promise.all([
+    const [aspect_ratio, duration, resolution, ref, audio] = await Promise.all([
       snapAspectRatio(apiId, resolved.aspect_ratio, ctx.client),
       snapDuration(apiId, resolved.duration, ctx.client),
       snapResolution(apiId, resolved.resolution, ctx.client),
-      resolved.image_url ? resolveReferenceField(apiId, ctx.client) : Promise.resolve(void 0)
+      src.url ? resolveMediaSlot(apiId, src.isClip ? "video" : "image", ctx.client) : Promise.resolve(void 0),
+      src.audioUrl ? resolveMediaSlot(apiId, "audio", ctx.client) : Promise.resolve(void 0)
     ]);
     resolved = { ...resolved, aspect_ratio, duration, resolution };
-    refField = ref;
+    refField = ref === void 0 && src.url ? fallbackSlot(apiId, src.isClip ? "video" : "image") : ref;
+    audioSlot = audio === void 0 && src.audioUrl ? fallbackSlot(apiId, "audio") : audio;
   }
-  const body = buildPayload(apiId, resolved, refField, referenceUrls);
+  const body = buildPayload(apiId, resolved, src, refField, audioSlot);
+  const paramsNote = applyParams(body, input.params, input.model, apiId);
+  const note = [routeNote, paramsNote].filter(Boolean).join(" ");
   const submitted = await ctx.client.run(apiId, body);
   const result = await pollJobUntilDoneOrHandoff(
     submitted.jobId,
@@ -427,18 +519,22 @@ async function run(input, ctx) {
       sleep: ctx.pollOverrides?.sleep
     }
   );
-  return pollResultToSkillResult(
-    result,
-    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : urls.length === 1 ? `Generated. Asset: ${urls[0]}` : `Generated ${urls.length} assets. URLs: ${urls.join(", ")}`
+  return prefixNote(
+    pollResultToSkillResult(
+      result,
+      (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : urls.length === 1 ? `Generated. Asset: ${urls[0]}` : `Generated ${urls.length} assets. URLs: ${urls.join(", ")}`
+    ),
+    note
   );
 }
-var InputSchema, DEFAULT_MODEL, VIDEO_INPUT_MODELS, InputJsonSchema, generateSkill;
+var InputSchema, DEFAULT_MODEL, VIDEO_REFERENCE_MODEL, VIDEO_REFERENCE_SLOTS, VIDEO_INPUT_MODELS, InputJsonSchema, generateSkill;
 var init_generate = __esm({
   "src/skills/generate.ts"() {
     init_poll();
     init_types();
     init_upload_helpers();
     init_schema_snap();
+    init_params();
     InputSchema = z.object({
       prompt: z.string().min(1).max(8e3).describe("Prompt describing what to generate."),
       model: z.string().optional().describe(
@@ -453,6 +549,10 @@ var init_generate = __esm({
         'Output resolution when the model supports it (e.g. "480p", "720p", "1080p", "4k"). Lower tiers cost fewer credits. Omit to use the model default.'
       ),
       image_url: z.string().url().optional().describe("Reference image URL for image-to-image / image-to-video tools."),
+      video_url: z.string().url().optional().describe(
+        "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames. A clip routes to a model that can actually read one."
+      ),
+      params: ParamsInput,
       image_path: z.string().min(1).optional().describe(
         "Absolute local file path to a reference image/video. The skill uploads it to PixelDojo first (24h temp storage) and then dispatches. Prefer this over image_url when the user has the file on disk."
       ),
@@ -464,6 +564,12 @@ var init_generate = __esm({
       )
     });
     DEFAULT_MODEL = "google-nano-banana";
+    VIDEO_REFERENCE_MODEL = "seedance-2-reference";
+    VIDEO_REFERENCE_SLOTS = {
+      image: { name: "reference_images", isArray: true },
+      video: { name: "reference_videos", isArray: true },
+      audio: { name: "reference_audios", isArray: true }
+    };
     VIDEO_INPUT_MODELS = /* @__PURE__ */ new Set(["grok-video-extend", "wan-video-edit", "seedance-video-edit"]);
     InputJsonSchema = {
       type: "object",
@@ -484,6 +590,12 @@ var init_generate = __esm({
           description: 'Output resolution when supported (e.g. "480p", "720p", "1080p", "4k"). Lower tiers cost fewer credits.'
         },
         image_url: { type: "string", format: "uri" },
+        video_url: {
+          type: "string",
+          format: "uri",
+          description: "Source video clip to animate / restyle / extend. Use this for videos; image_url is for still frames."
+        },
+        params: PARAMS_JSON_SCHEMA,
         image_urls: {
           type: "array",
           items: { type: "string", format: "uri" },
@@ -503,7 +615,7 @@ var init_generate = __esm({
     };
     generateSkill = {
       name: "pixeldojo_generate",
-      description: "Generate any image or video from a prompt. Auto-routes to a sensible default model; pass `model` to pick a specific apiId from the catalog. For reference-image / image-to-video flows: pass `image_url` if you already have a URL, or `image_path` (absolute local path) and the skill uploads it to 24h temp storage automatically.",
+      description: "Generate any image or video from a prompt. Auto-routes to a sensible default model; pass `model` to pick a specific apiId from the catalog. For reference flows: pass `image_url` for a still, `video_url` for a source clip, or `image_path` (absolute local path) and the skill uploads it to 24h temp storage automatically. A clip or an audio reference routes to an engine that can read one. Model-specific settings go in `params` alongside an explicit `model`.",
       inputZod: InputSchema,
       inputJsonSchema: InputJsonSchema,
       allowedModels: null,
@@ -570,9 +682,12 @@ async function buildBody(apiId, input, ctx) {
   }
   body.prompt = input.prompt;
   body[refs.key] = refs.value;
+  if (refs.also) Object.assign(body, refs.also);
   return { body, dropped: refs.dropped };
 }
 async function run2(input, ctx) {
+  const paramsGate = paramsWithoutModel(input.params, input.model);
+  if (paramsGate) return { kind: "text", text: paramsGate };
   let resolved = input;
   try {
     if (input.image_paths && input.image_paths.length > 0) {
@@ -604,6 +719,7 @@ async function run2(input, ctx) {
   };
   const { body, dropped } = await buildBody(apiId, resolved, ctx);
   const droppedNote = dropped > 0 ? ` (${dropped} reference${dropped === 1 ? "" : "s"} dropped \u2014 ${apiId} accepts fewer)` : "";
+  const paramsNote = applyParams(body, input.params, input.model, apiId);
   const submitted = await ctx.client.run(apiId, body);
   const result = await pollJobUntilDoneOrHandoff(
     submitted.jobId,
@@ -614,9 +730,12 @@ async function run2(input, ctx) {
       sleep: ctx.pollOverrides?.sleep
     }
   );
-  return pollResultToSkillResult(
-    result,
-    (urls) => urls.length === 0 ? `Edit job ${submitted.jobId} completed but returned no assets.` : urls.length === 1 ? `Edit complete${droppedNote}. Asset: ${urls[0]}` : `Edit produced ${urls.length} assets${droppedNote}. URLs: ${urls.join(", ")}`
+  return prefixNote(
+    pollResultToSkillResult(
+      result,
+      (urls) => urls.length === 0 ? `Edit job ${submitted.jobId} completed but returned no assets.` : urls.length === 1 ? `Edit complete${droppedNote}. Asset: ${urls[0]}` : `Edit produced ${urls.length} assets${droppedNote}. URLs: ${urls.join(", ")}`
+    ),
+    paramsNote
   );
 }
 var DEFAULT_MODEL2, ALLOWED_MODELS, InputSchema2, InputJsonSchema2, editSkill;
@@ -626,6 +745,7 @@ var init_edit = __esm({
     init_types();
     init_upload_helpers();
     init_schema_snap();
+    init_params();
     DEFAULT_MODEL2 = "wan-2.7-image-edit";
     ALLOWED_MODELS = [
       "wan-2.7-image-edit",
@@ -649,7 +769,8 @@ var init_edit = __esm({
       model: z.enum(ALLOWED_MODELS).optional().describe(
         "Override the default edit model. Defaults to wan-2.7-image-edit (most popular)."
       ),
-      aspect_ratio: z.string().optional().describe('Aspect ratio when supported (e.g. "1:1", "16:9", "match_input_image").')
+      aspect_ratio: z.string().optional().describe('Aspect ratio when supported (e.g. "1:1", "16:9", "match_input_image").'),
+      params: ParamsInput
     });
     InputJsonSchema2 = {
       type: "object",
@@ -683,7 +804,8 @@ var init_edit = __esm({
           enum: [...ALLOWED_MODELS],
           description: "Override edit model. Default: wan-2.7-image-edit."
         },
-        aspect_ratio: { type: "string" }
+        aspect_ratio: { type: "string" },
+        params: PARAMS_JSON_SCHEMA
       },
       required: ["prompt"]
     };
@@ -699,6 +821,8 @@ var init_edit = __esm({
   }
 });
 async function run3(input, ctx) {
+  const paramsGate = paramsWithoutModel(input.params, input.model);
+  if (paramsGate) return { kind: "text", text: paramsGate };
   const requested = input.model ?? DEFAULT_MODEL3;
   if (!ALLOWED.includes(requested)) {
     return {
@@ -707,24 +831,40 @@ async function run3(input, ctx) {
     };
   }
   const apiId = requested;
-  if (REQUIRES_REFERENCE.has(apiId) && !input.reference_image_url) {
+  const refUrls = (input.reference_image_urls && input.reference_image_urls.length > 0 ? input.reference_image_urls : input.reference_image_url ? [input.reference_image_url] : []).filter((u, i, all) => all.indexOf(u) === i);
+  const wrongKind = refUrls.find((u) => isVideoUrl(u) || isAudioUrl(u));
+  if (wrongKind) {
     return {
       kind: "text",
-      text: `pixeldojo_character with model="${apiId}" requires reference_image_url (the source image of the character to edit). For generation from a prompt alone, use model="${DEFAULT_MODEL3}".`
+      text: `pixeldojo_character works on still images, and ${wrongKind} is not one. Use pixeldojo_generate or pixeldojo_storyboard with video_url to work from a clip (or image_url for an audio track \u2014 they route to the reference engine). For this treatment, give me a still frame.`
+    };
+  }
+  if (REQUIRES_REFERENCE.has(apiId) && refUrls.length === 0) {
+    return {
+      kind: "text",
+      text: `pixeldojo_character with model="${apiId}" requires a reference image (reference_image_url / reference_image_urls \u2014 the source image of the character to edit). For generation from a prompt alone, use model="${DEFAULT_MODEL3}".`
     };
   }
   const body = { prompt: input.prompt };
-  if (input.reference_image_url) {
-    if (apiId === "flux-edit") {
-      body.input_image = input.reference_image_url;
+  let dropped = 0;
+  if (refUrls.length > 0) {
+    const refs = await resolveImageRefs(apiId, refUrls, ctx.client);
+    if (refs) {
+      body[refs.key] = refs.value;
+      if (refs.also) Object.assign(body, refs.also);
+      dropped = refs.dropped;
     } else {
-      body.image_urls = [input.reference_image_url];
+      body[FALLBACK_REF_KEY[apiId]] = refUrls;
     }
   }
   const snappedAspect = await snapAspectRatio(apiId, input.aspect_ratio, ctx.client, {
     onUnknown: "omit"
   });
   if (snappedAspect !== void 0) body.aspect_ratio = snappedAspect;
+  const note = [
+    dropped > 0 ? `${dropped} reference${dropped === 1 ? "" : "s"} dropped \u2014 ${apiId} accepts fewer.` : void 0,
+    applyParams(body, input.params, input.model, apiId)
+  ].filter(Boolean).join(" ");
   const submitted = await ctx.client.run(apiId, body);
   const result = await pollJobUntilDoneOrHandoff(
     submitted.jobId,
@@ -735,27 +875,49 @@ async function run3(input, ctx) {
       sleep: ctx.pollOverrides?.sleep
     }
   );
-  return pollResultToSkillResult(
-    result,
-    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Character shot ready. Asset: ${urls[0]}`
+  return prefixNote(
+    pollResultToSkillResult(
+      result,
+      (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Character shot ready. Asset: ${urls[0]}`
+    ),
+    note
   );
 }
-var ALLOWED, DEFAULT_MODEL3, REQUIRES_REFERENCE, InputSchema3, InputJsonSchema3, characterSkill;
+var ALLOWED, DEFAULT_MODEL3, MAX_REFERENCES, REQUIRES_REFERENCE, FALLBACK_REF_KEY, InputSchema3, InputJsonSchema3, characterSkill;
 var init_character = __esm({
   "src/skills/character.ts"() {
     init_poll();
     init_types();
     init_schema_snap();
-    ALLOWED = ["seedream-5", "seedream-4", "flux-edit", "gpt-image-2-edit"];
+    init_params();
+    ALLOWED = [
+      "seedream-5",
+      "seedream-4",
+      "google-nano-banana",
+      "wan-2.7-image-edit",
+      "qwen-image-2.0-pro"
+    ];
     DEFAULT_MODEL3 = "seedream-5";
-    REQUIRES_REFERENCE = /* @__PURE__ */ new Set(["flux-edit", "gpt-image-2-edit"]);
+    MAX_REFERENCES = 9;
+    REQUIRES_REFERENCE = /* @__PURE__ */ new Set(["wan-2.7-image-edit"]);
+    FALLBACK_REF_KEY = {
+      "seedream-5": "image_urls",
+      "seedream-4": "image_urls",
+      "google-nano-banana": "image_input",
+      "wan-2.7-image-edit": "image_urls",
+      "qwen-image-2.0-pro": "reference_images"
+    };
     InputSchema3 = z.object({
       prompt: z.string().min(1).max(8e3),
       model: z.string().optional().describe(`One of: ${ALLOWED.join(", ")}. Defaults to ${DEFAULT_MODEL3}.`),
       reference_image_url: z.string().url().optional().describe(
-        "Reference image of the character. Required by flux-edit and gpt-image-2-edit; optional for seedream-5/seedream-4."
+        "Single reference image of the character. Prefer reference_image_urls \u2014 more angles lock the face better."
       ),
-      aspect_ratio: z.string().optional().describe('Only honored for model="flux-edit".')
+      reference_image_urls: z.array(z.string().url()).min(1).max(MAX_REFERENCES).optional().describe(
+        `All references for this shot (1-${MAX_REFERENCES}), most important first. Multiple angles of the same person lock the face far better than one photo. Models that take fewer are clamped to their own cap.`
+      ),
+      aspect_ratio: z.string().optional().describe("Honored where the model declares the field."),
+      params: ParamsInput
     });
     InputJsonSchema3 = {
       type: "object",
@@ -766,14 +928,26 @@ var init_character = __esm({
           enum: ALLOWED,
           description: `One of: ${ALLOWED.join(", ")}. Defaults to ${DEFAULT_MODEL3}.`
         },
-        reference_image_url: { type: "string", format: "uri" },
-        aspect_ratio: { type: "string" }
+        reference_image_url: {
+          type: "string",
+          format: "uri",
+          description: "Single reference. Prefer reference_image_urls."
+        },
+        reference_image_urls: {
+          type: "array",
+          items: { type: "string", format: "uri" },
+          minItems: 1,
+          maxItems: MAX_REFERENCES,
+          description: "All references for this shot, most important first. Multiple angles of the same person lock the face far better than one photo."
+        },
+        aspect_ratio: { type: "string" },
+        params: PARAMS_JSON_SCHEMA
       },
       required: ["prompt"]
     };
     characterSkill = {
       name: "pixeldojo_character",
-      description: "Generate or edit consistent characters across shots. Pass a reference_image_url for identity locking (seedream-5 by default).",
+      description: "Generate or edit consistent characters across shots. Pass reference_image_urls (up to 9) to lock identity \u2014 send every photo of the person you have, since more angles hold the face far better than one. Defaults to seedream-5.",
       inputZod: InputSchema3,
       inputJsonSchema: InputJsonSchema3,
       allowedModels: [...ALLOWED],
@@ -783,6 +957,8 @@ var init_character = __esm({
   }
 });
 async function run4(input, ctx) {
+  const paramsGate = paramsWithoutModel(input.params, input.model);
+  if (paramsGate) return { kind: "text", text: paramsGate };
   const requested = input.model ?? DEFAULT_MODEL4;
   if (!ALLOWED2.includes(requested)) {
     return {
@@ -790,6 +966,20 @@ async function run4(input, ctx) {
       text: `Unknown model "${requested}" for pixeldojo_storyboard. Allowed: ${ALLOWED2.join(", ")}.`
     };
   }
+  if (input.image_url || input.video_url) {
+    return generateSkill.run(
+      {
+        prompt: input.brief,
+        model: input.model ?? VIDEO_REFERENCE_MODEL,
+        image_url: input.image_url,
+        video_url: input.video_url,
+        aspect_ratio: input.aspect_ratio,
+        duration: input.duration,
+        params: input.params
+      },
+      ctx
+    );
+  }
   const apiId = requested;
   const [snappedAspect, snappedDuration] = await Promise.all([
     snapAspectRatio(apiId, input.aspect_ratio, ctx.client),
@@ -798,6 +988,7 @@ async function run4(input, ctx) {
   const body = { prompt: input.brief };
   if (snappedAspect !== void 0) body.aspect_ratio = snappedAspect;
   if (snappedDuration !== void 0) body.duration = snappedDuration;
+  const note = applyParams(body, input.params, input.model, apiId);
   const submitted = await ctx.client.run(apiId, body);
   const result = await pollJobUntilDoneOrHandoff(
     submitted.jobId,
@@ -808,9 +999,12 @@ async function run4(input, ctx) {
       sleep: ctx.pollOverrides?.sleep
     }
   );
-  return pollResultToSkillResult(
-    result,
-    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Storyboard preview ready. Asset: ${urls[0]}`
+  return prefixNote(
+    pollResultToSkillResult(
+      result,
+      (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Storyboard preview ready. Asset: ${urls[0]}`
+    ),
+    note
   );
 }
 var ALLOWED2, DEFAULT_MODEL4, InputSchema4, InputJsonSchema4, storyboardSkill;
@@ -819,18 +1013,24 @@ var init_storyboard = __esm({
     init_poll();
     init_types();
     init_schema_snap();
+    init_generate();
+    init_params();
     ALLOWED2 = [
       "veo-3.1-fast",
       "veo-3.1-standard",
       "kling-video-v3-standard-text",
-      "seedance-2-high"
+      "seedance-2-high",
+      VIDEO_REFERENCE_MODEL
     ];
     DEFAULT_MODEL4 = "veo-3.1-fast";
     InputSchema4 = z.object({
       brief: z.string().min(1).max(8e3).describe("Storyboard brief: scene, shots, mood, action."),
       model: z.string().optional().describe(`One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL4}.`),
       aspect_ratio: z.string().optional(),
-      duration: z.number().int().positive().optional()
+      duration: z.number().int().positive().optional(),
+      image_url: z.string().url().optional().describe("Reference still to build the shot from (character, product, location)."),
+      video_url: z.string().url().optional().describe("Source clip to work from. Use this for videos; image_url is for still frames."),
+      params: ParamsInput
     });
     InputJsonSchema4 = {
       type: "object",
@@ -845,13 +1045,24 @@ var init_storyboard = __esm({
           description: `One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL4}.`
         },
         aspect_ratio: { type: "string" },
-        duration: { type: "integer" }
+        duration: { type: "integer" },
+        image_url: {
+          type: "string",
+          format: "uri",
+          description: "Reference still to build the shot from."
+        },
+        video_url: {
+          type: "string",
+          format: "uri",
+          description: "Source clip to work from. Use this for videos; image_url is for stills."
+        },
+        params: PARAMS_JSON_SCHEMA
       },
       required: ["brief"]
     };
     storyboardSkill = {
       name: "pixeldojo_storyboard",
-      description: "Generate a video storyboard preview from a single brief. v1: single-shot preview; multi-shot orchestration coming.",
+      description: "Generate a video storyboard preview from a single brief. Pass image_url for a reference still or video_url for a source clip. v1: single-shot preview; multi-shot orchestration coming.",
       inputZod: InputSchema4,
       inputJsonSchema: InputJsonSchema4,
       allowedModels: [...ALLOWED2],
@@ -2181,7 +2392,7 @@ function makeRedactedLogger(target = console) {
 }
 
 // src/server.ts
-var PACKAGE_VERSION = "0.9.1" ;
+var PACKAGE_VERSION = "0.10.0" ;
 function buildServer(options) {
   if (!options.apiKey) {
     throw new Error(