@starreel/mcp 0.1.256 → 0.1.258

package/SKILL.md

@@ -94,6 +94,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | Their own portraits / scene / prop / shot images | `upload_image` · `set_character_portrait` · `upload_scene_image` · `upload_prop_sheet` · `upload_shot_frame` — **check the image before uploading** (see *Customer-supplied images* below); after a portrait swap, `generate_character_sheet` for that character (the old sheet is invalidated and **not** regenerated automatically) | rendering a "fix" elsewhere and uploading it — use `generate_shot_frame`; uploading a group photo, a captioned/watermarked image, or a multi-view sheet as a portrait; uploading a scene photo with people in it |
 | Their own **footage** for a shot (screen recording, product b-roll, an existing clip) | `upload_shot_footage` → that shot is no longer AI-generated (frames/video skipped, final cut uses the clip as-is, duration written back from the clip); **it overwrites whatever AI video that shot already had**, and afterwards every AI video call on it (including `edit_video_shot`) is refused with **409** until you `clear_shot_footage` or pass `replace_user_footage: true` | pasting an externally AI-generated clip to "fix" a shot — it carries none of this film's identity / style anchors; use `regenerate_shot_video` instead |
 | A **greybox / 3D previs** or any clip whose motion, camera move and blocking a shot should be **generated from** | `create_motion_reference` (greybox: `kind` = `greybox_coarse` / `greybox_fine`) → `attach_motion_reference` — with several proxies pass `greybox_bindings` (which coloured proxy is which character) → `quote_videos` / `generate_videos` as usual; the shot's first/last frames are not sent and identity comes from the character references. Coarse greyboxes built from simple primitives work best; keep trail lines / axes / camera frustums out of fine greyboxes | `upload_shot_footage` (that makes the clip the finished shot); a greybox with several characters and no bindings — identities get swapped |
+| Shot size / camera move / blocking keep coming out wrong and the client has **no greybox** | `generate_greybox_previs` (`dry_run=true` first to see which fields and fallbacks it uses; fix fields with `update_shot`) — the platform renders a coarse greybox from the storyboard fields and fills `greybox_bindings` → `get_greybox_previs` → `review_frames` → `quote_videos` / `generate_videos`. Tell the client first: first/last frames are not sent and the video quote rises by about 20% | Using it on insert shots, shots with no on-screen character, shots over 15 s or state-change shots (it returns the reason instead) |
 | A clip that should **drive the motion** of an AI shot (a blocking/previz pass, a dance or action reference) | `edit_video_shot` with `reference_video_urls` — the shot keeps its AI video and borrows the clip's movement. To make the clip itself the source and restyle it in place, `upload_shot_footage` it first, then `edit_video_shot` with `replace_user_footage: true` | `upload_shot_footage` alone — that registers the clip as the finished shot, so nothing gets restyled and every later AI call on it returns 409 |
 | A clip whose **motion should be kept while the people / outfits are redrawn** (video repaint) — their own footage or a shot already generated here | `get_repaint_capabilities` (is it enabled for this drama; `relayMaxSegments`) → for their own clip, `upload_shot_footage` it onto a shot first → `quote_repaint_shot_video` → `repaint_shot_video` (prompt + reference image; with no `reference_image_url` the shot's character portrait is used — without any reference the person is redrawn too) **or** `quote_reskin_shot_video` → `reskin_shot_video` (`first_frame_url` = an already-reskinned first frame that matches the original first frame's composition, pose and props exactly) → `get_repaint_status` with the returned id until `completed` → `restore_repaint_original` to switch back (free). Motion, lip timing and camera move follow the source and its audio is carried over. ≤5 s is one charge (billed as 5 s); with long-shot relay enabled, 5–~14 s is split into ≤3 relayed segments, one charge each, and the quote is the total and the charge cap. A quote is tied to the shot's current video — if that video changes, generating returns 409; re-quote (free) | `edit_video_shot` to swap the whole cast or wardrobe (it edits by instruction); clips longer than ~14 s (`split_shot` first) |
 | `review_storyboards` reports `forbidden_term` (light / color-temperature / BGM wording in the shot text) | every hit is listed at once in the finding's `hits` (`shot`, `field`, `term`) → `get_shot_prompts` to read that field (`description` is returned there too) → `update_shot` to remove the term from that field; if the intent is lighting, move it to `update_shot`'s `lighting` field (not scanned, and video / image generation read it); a hit with `field=sound_effect` is fixed with `update_shot`'s `sound_effect` field (its current value is in `get_shot_prompts` too) → `review_storyboards` again | rewriting the whole shot blind, or putting the lighting back into `description` / prompts in other words |
@@ -1559,6 +1560,23 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   with their timestamps (first frame becomes a soft constraint; ±1 s timing; same
   price). Shots whose first frame is a copy of the previous shot's last frame keep
   first-frame mode (`reason: strict-continuity`) so the seam stays exact.
+- **Storyboard grid reference (closed beta, `seedance-2.5` only)**:
+  `set_shot_storyboard_grid` (free) mounts one multi-panel storyboard image
+  (line art / stick figures, ideally ≤15 panels) on a shot; the video is then
+  generated as one multi-shot clip following the grid's story, action, shot
+  order, camera positions and blocking. The grid is sent as reference image 1,
+  **not** as the first frame, and is **not** matched panel-by-panel — when the
+  frames must match exactly, use keyframes instead. The platform drops the
+  first/last frame (they are mutually exclusive with the grid), appends the
+  shot's character portraits and scene image, and writes the asset-reference
+  block at the top of the prompt; the grid never defines faces or art style.
+  Write the shot's `video_prompt` as a synopsis plus per-panel details the
+  sketch cannot show (shot size, camera move, action, materials, style).
+  Advisories (>15 panels, more panels than seconds) do not block. Non-2.5
+  engine → 400; grid shots never join scene groups; mounting marks the
+  existing video stale. `quote_regenerate_shot_video` returns `storyboard_grid`
+  when the grid will be used. Read with `get_shot_storyboard_grid`, remove with
+  `clear_shot_storyboard_grid`. A 400 "未开启" means the project is not in the beta.
 - **Era contract**: `set_era_contract` / `get_era_contract` — see the project
   settings tier above. Non-contemporary projects must set this before frames.
 - **Lengthen a finished cut**: `quote_extend_final` (free, quote first) →

package/dist/i18n/tools.en.json

@@ -281,5 +281,7 @@
   "create_motion_reference": "Register a **motion / camera reference clip** in your own motion reference library (free), then attach it to a shot with attach_motion_reference — the AI video for that shot is regenerated following the clip's motion, camera move and blocking. ★**Greybox (3D previs) goes here**: set kind to greybox_coarse / greybox_fine and the platform tells the model to use the greybox only for camera movement, rhythm, shot size, motion paths and blocking — never its proxy shapes or untextured look. Greybox tips: coarse works best — build people/objects from simple primitives; model only the torso, or if you model limbs/wings animate them fully, otherwise limbs come out stiff; one clip ≤30 s (Seedance 2.5), 1–5 subjects work best. ⚠️ Not the same as upload_shot_footage: that one says \"this clip IS the finished shot\"; this one says \"regenerate the shot following this clip\".",
   "list_motion_references": "List the clips in your own motion reference library (greyboxes included), free. Returns id / name / kind / video_url; pass the id to attach_motion_reference.",
   "get_shot_motion_reference": "Show the motion reference / greybox attached to a shot and its proxy-to-character bindings (free). greybox_gray_on=false means greybox rendering is not enabled for this drama yet and a greybox is treated as a plain motion reference.",
-  "attach_motion_reference": "Attach a motion reference / greybox to a shot (free); asset_id=null detaches it (bindings are cleared too). Then quote_videos / generate_videos as usual: the shot switches to the reference-video path — motion, camera move, blocking and shot size follow the clip, first/last frames are not sent (the vendor treats the two as mutually exclusive), identity comes from the character reference images, and review_frames is still required before video. ★**When the greybox has several proxies, always pass greybox_bindings** saying which proxy is which character (e.g. [{proxy:\"red model\",character_id:12},{proxy:\"blue model\",character_id:15}]); the platform writes each character's reference image number into the prompt — without bindings, multi-character shots tend to swap identities. Write proxy exactly as the colour/number in the client's greybox; character_id must be a character of this drama (get_characters). Bound characters not on the shot's cast list get their reference images added automatically. Omitting greybox_bindings keeps the existing bindings for the same clip and clears them when the clip changes."
+  "attach_motion_reference": "Attach a motion reference / greybox to a shot (free); asset_id=null detaches it (bindings are cleared too). Then quote_videos / generate_videos as usual: the shot switches to the reference-video path — motion, camera move, blocking and shot size follow the clip, first/last frames are not sent (the vendor treats the two as mutually exclusive), identity comes from the character reference images, and review_frames is still required before video. ★**When the greybox has several proxies, always pass greybox_bindings** saying which proxy is which character (e.g. [{proxy:\"red model\",character_id:12},{proxy:\"blue model\",character_id:15}]); the platform writes each character's reference image number into the prompt — without bindings, multi-character shots tend to swap identities. Write proxy exactly as the colour/number in the client's greybox; character_id must be a character of this drama (get_characters). Bound characters not on the shot's cast list get their reference images added automatically. Omitting greybox_bindings keeps the existing bindings for the same clip and clears them when the clip changes.",
+  "generate_greybox_previs": "**Auto-generate a coarse greybox** for a shot from the fields the storyboard already has and attach it (free): shot size, camera height and side, camera move (push/pull/pan/tilt/track/crane/arc), blocking, facing, duration and action (approach, back away, turn, sit down…). The platform renders a primitive-geometry greybox clip (one colour per character, torso only), registers it as greybox_coarse and **fills greybox_bindings automatically** — the client does not have to build a greybox. The point is to turn shot size / camera move / blocking from text hints into pixel constraints when shots ignore the staging. ★Once attached the shot uses the reference-video path: **first/last frames are no longer sent** (identity comes from the character references) and **the video quote rises by roughly 20%** (reference video is billed per second) — tell the client both before generating. ★Run dry_run=true first to see which fields were used and what was assumed (assumptions = fallbacks for missing fields); fix fields with update_shot before generating. Shots it does not apply to come back with a reason: insert shots, no on-screen character, longer than 15 s, state-change shots (they rely on the end-frame state; pass include_state_change=true to force). A motion reference the client attached themselves is never overwritten (409) unless replace_existing=true. Pass episode_id without storyboard_id for a whole episode (≤40 shots per call; pick shots with storyboard_ids). Returns 409 while the drama is not enabled (gradual rollout). Afterwards review_frames → quote_videos → generate_videos as usual.",
+  "get_greybox_previs": "Inspect a shot's auto greybox (free): attached = whether the attached motion reference is a platform-generated greybox; stale=true means the shot fields changed since and the greybox is outdated — run generate_greybox_previs again; current is the plan and assumptions the current fields would produce; skip is the reason when the shot does not apply."
 }

package/dist/i18n/tools.zh-CN.json

@@ -288,5 +288,7 @@
   "create_motion_reference": "把一段**动作 / 运镜参考视频**登记进本人运动参考库(免费),之后用 attach_motion_reference 挂到某镜,AI 出视频时照它的动作、运镜、站位重新生成。★**白模(3D 预演)走这里**:kind 选 greybox_coarse / greybox_fine,平台会告诉模型「白模只作运镜 / 节奏 / 景别 / 运动轨迹 / 站位参考,不参考几何体外形和灰模材质」。白模建议:粗粒度最好,只用简单几何体拼人物 / 物体;身体只建躯干即可,建了四肢 / 翅膀就把动作补全,否则成片四肢僵硬;单段 ≤30 秒(Seedance 2.5),主体 1~5 个效果最好。⚠️ 与 upload_shot_footage 的区别:那个是「这段视频**就是**成片」,本工具是「照这段视频**重新生成**」。",
   "list_motion_references": "列出本人运动参考库里的素材(含白模),免费。返回 id / name / kind / video_url;id 给 attach_motion_reference 用。",
   "get_shot_motion_reference": "看某镜当前挂的运动参考 / 白模与「色块 → 角色」绑定(免费)。greybox_gray_on=false 表示本剧还没开放白模渲染,白模按普通运动参考处理。",
-  "attach_motion_reference": "把运动参考 / 白模挂到某镜(免费),asset_id=null 解除挂载(绑定一并清掉)。挂好后照常 quote_videos / generate_videos:该镜改走参考视频路径——动作、运镜、站位、景别跟参考视频走,首尾帧不送(厂商规定两者互斥),身份靠角色参考图,出视频前仍要过 review_frames。★**白模有多个模型时务必传 greybox_bindings**,写明白模里「哪个色块是哪个角色」(如 [{proxy:\"红色模型\",character_id:12},{proxy:\"蓝色模型\",character_id:15}]);平台会把对应角色的参考图编号写进提示词,不绑定的话多人镜容易串身份。proxy 按客户白模里的真实颜色 / 编号写,character_id 必须是本剧角色(get_characters)。绑定了但不在本镜出镜名单里的角色,参考图也会自动带上。不传 greybox_bindings = 同一素材保留原绑定、换了素材就清空。"
+  "attach_motion_reference": "把运动参考 / 白模挂到某镜(免费),asset_id=null 解除挂载(绑定一并清掉)。挂好后照常 quote_videos / generate_videos:该镜改走参考视频路径——动作、运镜、站位、景别跟参考视频走,首尾帧不送(厂商规定两者互斥),身份靠角色参考图,出视频前仍要过 review_frames。★**白模有多个模型时务必传 greybox_bindings**,写明白模里「哪个色块是哪个角色」(如 [{proxy:\"红色模型\",character_id:12},{proxy:\"蓝色模型\",character_id:15}]);平台会把对应角色的参考图编号写进提示词,不绑定的话多人镜容易串身份。proxy 按客户白模里的真实颜色 / 编号写,character_id 必须是本剧角色(get_characters)。绑定了但不在本镜出镜名单里的角色,参考图也会自动带上。不传 greybox_bindings = 同一素材保留原绑定、换了素材就清空。",
+  "generate_greybox_previs": "按分镜已有字段**自动生成粗粒度白模**并挂到镜上(免费):景别 / 机位高度与方位 / 运镜(推拉摇移跟升降环绕) / 站位 / 朝向 / 时长 / 动作(走近、后退、转身、坐下等)→ 平台本机渲成几何体白模视频(每个角色一种颜色、只建躯干),登记成 greybox_coarse 并**自动写好 greybox_bindings**,不用客户自己建白模。目的是把景别 / 运镜 / 站位从文字约束变成像素约束,治「镜头调度不听话」。★挂上后该镜改走参考视频路径:**首尾帧不再送达**(身份靠角色参考图),**视频报价会上涨约两成**(参考视频按秒计费)——生成前把这两点讲给客户。★先 dry_run=true 看平台按哪些字段、做了哪些假设(assumptions:缺失字段的兜底),字段不对先 update_shot 改再生成。不适用的镜会返回原因:插入镜、没有出镜角色、超过 15 秒、状态变化镜(依赖尾帧终态,确需生成传 include_state_change=true)。镜上已挂客户自己的运动参考时不覆盖(409),确要替换传 replace_existing=true。传 episode_id 不传 storyboard_id = 整集批量(一次 ≤40 镜,可用 storyboard_ids 选镜)。本剧未开放时回 409(灰度中)。生成后照常 review_frames → quote_videos → generate_videos。",
+  "get_greybox_previs": "看某镜的自动白模(免费):attached=当前挂的是不是平台自动生成的白模;stale=true 表示镜头字段改过、白模已过时,需要重新 generate_greybox_previs;current 是按当前字段会生成的规格与假设;skip 是不适用的原因。"
 }

package/dist/tools/guide-data.js

@@ -274,7 +274,7 @@ export const PIPELINE = [
     },
     {
         step: '8 出视频',
-        tools: ['quote_videos', 'generate_videos', 'cancel_videos(停整集出视频:已派的照常出完扣费,未派的不再派·免费)', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)'],
+        tools: ['quote_videos', 'generate_videos', 'cancel_videos(停整集出视频:已派的照常出完扣费,未派的不再派·免费)', 'get_scene_group_plan', 'generate_scene_groups', 'quote_regenerate_shot_video', 'regenerate_shot_video', 'quote_edit_video_shot', 'edit_video_shot', 'upload_shot_footage(实拍素材镜:客户录屏/产品实拍直接当该镜视频,不出视频不扣费)', 'get_edit_capabilities', 'get_repaint_capabilities', 'quote_repaint_shot_video', 'repaint_shot_video', 'quote_reskin_shot_video', 'reskin_shot_video', 'get_repaint_status', 'restore_repaint_original', 'get_av_anchors(定妆视频锚现况:挂锚的镜首尾帧不送)', 'clear_character_av_anchor(客户确认后摘锚·免费)', 'set_shot_storyboard_grid(宫格分镜参考·内测·2.5:线稿宫格一次出一段多镜头,不严格对齐)', 'get_shot_storyboard_grid', 'clear_shot_storyboard_grid'],
         billing: '报价确认后扣点',
         note: 'video_engine 必须在出视频前定(写实真人剧 seedance-2.5 或降本 hailuo-3 / 动漫·风格化 seedance-2.5 或 wan3.0·wan 绝不用于写实真人;' + MODEL_AVAILABILITY_NOTE + ');切换不回溯已生成镜头。',
     },
@@ -382,6 +382,7 @@ export const COMMON_REQUESTS = [
     { customer_says: '我想自己剪', do: '`export_handoff_pack` + `build_av_timing_contract`(音画时长契约) + `get_handoff_toolchain`,不走 `compose_episode`。' },
     { customer_says: '做动作片 / 打斗 / 技能展示 / 这条参考动作片我们能不能做', do: '先 `get_capabilities_guide` section=action_film:资产照常走 `rewrite_script` → `review_script` → `extract_assets`,分镜改用自己写的表(`import_storyboard_table`)而不是 AI 拆镜,首帧停在起势,拖沓尾段用 `trim_shot` 剪;平台不支持镜内分段变速。' },
     { customer_says: '我有白模 / 3D 预演视频 / 想让某镜照一段视频的动作和运镜重新生成', do: '`create_motion_reference`(白模选 kind=greybox_coarse / greybox_fine)→ `attach_motion_reference`(多个色块传 greybox_bindings 写明哪个色块是哪个角色)→ `get_shot_motion_reference` 核对 → 照常 `review_frames` → `quote_videos` → `generate_videos`。别用 `upload_shot_footage`(那是把视频直接当成片);白模别带轨迹线 / 坐标轴 / 相机锥,四肢不建或建全动作。' },
+    { customer_says: '镜头景别 / 运镜 / 站位总是不听话、想先做白模预演但手上没有白模', do: '`generate_greybox_previs`(先 `dry_run=true` 看平台用了哪些字段、做了哪些假设,字段不对先 `update_shot`)→ 平台按分镜字段自动渲粗粒度白模并写好色块绑定 → `get_greybox_previs` 核对 → 照常 `review_frames` → `quote_videos` → `generate_videos`。先告诉客户:白模镜不送首尾帧、视频报价约贵两成;插入镜 / 无角色 / 超 15 秒 / 状态变化镜不适用。' },
     { customer_says: '要配音 / 不要视频原声', do: '`update_project_settings` use_clip_audio=false → `assign_voices` → `generate_tts` → `compose_episode`。' },
 ];
 /**

package/dist/tools/produce.js

@@ -1366,6 +1366,29 @@ export function registerProduceTools(server, client) {
         ...REVIEW_ARGS,
         ...ASSET_REVIEW_ARG,
     }, async ({ storyboard_id, quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/keyframes/generate`, { quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge })));
+    server.tool('get_shot_storyboard_grid', '★**内测**·读**某一镜**挂的宫格分镜参考(故事板)。免费。回 grid(image_url / cells / advisories,null = 没挂)、'
+        + 'enabled(本剧是否在内测名单)、video_engine 与 engine_supported(只有 Seedance 2.5 支持宫格参考)、tips(宫格怎么画、提示词怎么写)。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/storyboard-grid`)));
+    server.tool('set_shot_storyboard_grid', '★**内测**·给**某一镜**挂一张**宫格分镜图**(故事板,Seedance 2.5 官方多模态能力):客户手画的线稿 / 火柴人多宫格,'
+        + '一张图里按从左到右、从上到下排好这一段的镜头顺序、动作、机位与站位,出视频时**一次出成一段多镜头视频**。免费(只挂载,出视频照常报价扣费)。'
+        + '\n★宫格作参考图「图片1」送(不是首帧),**不严格对齐**画面细节——它只管剧情、动作、镜头顺序、机位与站位;'
+        + '**要逐格严格对齐画面,改用关键帧**(set_shot_keyframes 单镜中间关键帧,或场景组关键帧),不是本工具。'
+        + '\n★出视频时平台自动:不送首尾帧(厂商规定与宫格互斥)、把本镜角色定妆图与场景图接在宫格之后、在提示词最前面写好素材指代'
+        + '(宫格图@图片1、角色图@图片N、场景图@图片M);宫格图不当身份参考,人物长相以定妆图为准,也不会沿用宫格的线稿画风。'
+        + '\n★本镜视频提示词(update_shot 的 video_prompt)请写:故事梗概 + 按格逐镜补齐宫格里画不出的信息(景别、运镜、动作、材质、风格);写实片可再写一句「宫格只作脚本参考」。'
+        + '\n★建议 ≤15 格(超过易画面静止、顺序错乱,会回 advisories 提示但不拦截);推荐线稿 / 火柴人,不要过度锐化的 AI 直出图,图上少写字;'
+        + '格数多于本镜秒数也会提示(动作会被挤压)。'
+        + '\n★前提:本镜或本剧视频引擎是 seedance-2.5,否则 400;挂了宫格的镜不并场景组。挂 / 换宫格会把本镜已有视频标为待重生。'
+        + '之后照常 quote_regenerate_shot_video(回 storyboard_grid 字段即确认本次按宫格出)→ regenerate_shot_video。'
+        + '回 400「本剧未开启」= 不在内测名单,别重试。传 file_path(本地图,自动上传)或 image_url 二选一。', {
+        storyboard_id: z.number().int().positive(),
+        cells: z.number().int().min(2).max(36).describe('宫格的格数,例如 3×3 填 9'),
+        file_path: z.string().optional().describe('本地宫格图路径(自动上传)'),
+        image_url: z.string().optional().describe('已上传的宫格图地址(与 file_path 二选一)'),
+    }, async ({ storyboard_id, cells, file_path, image_url }) => {
+        const url = file_path ? await client.uploadLocalFile(file_path, 'image') : image_url;
+        return jsonResult(await client.producePut(`/storyboards/${storyboard_id}/storyboard-grid`, { image_url: url, cells }));
+    });
+    server.tool('clear_shot_storyboard_grid', '★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式。免费。本镜已有视频会被标为待重生。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceDelete(`/storyboards/${storyboard_id}/storyboard-grid`)));
     server.tool('quote_extend_final', '★成片续写**报价**(免费·无副作用):在已有成片后面再接几轮 AI 生成的片段,把片子拉长。'
         + '回 rounds(轮数)/duration_per_round(每轮秒数)/max_rounds(上限)/estimated_points(预估点数)。'
         + '\n★**必须先 quote_extend_final 报价,再调 extend_final**' + MODE_DECIDES('报价确认') + '(派发前平台按同参整单报价过预算预检,超出硬上限回 402 BUDGET_WOULD_EXCEED、未扣费,那就停下问客户)' + '——每轮都真扣厂商的钱。'
@@ -1651,6 +1674,22 @@ export function registerProduceTools(server, client) {
     }, async ({ storyboard_id, asset_id, greybox_bindings }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/motion-reference`, {
         asset_id, ...(greybox_bindings !== undefined ? { greybox_bindings } : {}),
     })));
+    server.tool('generate_greybox_previs', '按分镜已有字段**自动生成粗粒度白模**并挂到镜上(免费):景别 / 机位高度与方位 / 运镜(推拉摇移跟升降环绕) / 站位 / 朝向 / 时长 / 动作(走近、后退、转身、坐下等)→ 平台本机渲成几何体白模视频(每个角色一种颜色、只建躯干),登记成 greybox_coarse 并**自动写好 greybox_bindings**,不用客户自己建白模。目的是把景别 / 运镜 / 站位从文字约束变成像素约束,治「镜头调度不听话」。★挂上后该镜改走参考视频路径:**首尾帧不再送达**(身份靠角色参考图),**视频报价会上涨约两成**(参考视频按秒计费)——生成前把这两点讲给客户。★先 dry_run=true 看平台按哪些字段、做了哪些假设(assumptions:缺失字段的兜底),字段不对先 update_shot 改再生成。不适用的镜会返回原因:插入镜、没有出镜角色、超过 15 秒、状态变化镜(依赖尾帧终态,确需生成传 include_state_change=true)。镜上已挂客户自己的运动参考时不覆盖(409),确要替换传 replace_existing=true。传 episode_id 不传 storyboard_id = 整集批量(一次 ≤40 镜,可用 storyboard_ids 选镜)。本剧未开放时回 409(灰度中)。生成后照常 review_frames → quote_videos → generate_videos。', {
+        storyboard_id: z.number().int().positive().optional().describe('单镜;与 episode_id 二选一'),
+        episode_id: z.number().int().positive().optional().describe('整集批量;不传 storyboard_ids = 本集全部镜(≤40)'),
+        storyboard_ids: z.array(z.number().int().positive()).max(40).optional().describe('整集模式下只做这几镜'),
+        dry_run: z.boolean().optional().describe('true = 只回规格与假设,不渲染不挂载'),
+        replace_existing: z.boolean().optional().describe('true = 替换客户自己挂的运动参考'),
+        include_state_change: z.boolean().optional().describe('true = 状态变化镜也生成(会失去尾帧终态约束)'),
+    }, async ({ storyboard_id, episode_id, storyboard_ids, dry_run, replace_existing, include_state_change }) => {
+        const body = { dry_run, replace_existing, include_state_change };
+        if (storyboard_id)
+            return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/greybox-previs`, body));
+        if (episode_id)
+            return jsonResult(await client.producePost(`/episodes/${episode_id}/greybox-previs`, { ...body, ...(storyboard_ids ? { storyboard_ids } : {}) }));
+        return jsonResult({ error: 'storyboard_id 或 episode_id 必须给一个' });
+    });
+    server.tool('get_greybox_previs', '看某镜的自动白模(免费):attached=当前挂的是不是平台自动生成的白模;stale=true 表示镜头字段改过、白模已过时,需要重新 generate_greybox_previs;current 是按当前字段会生成的规格与假设;skip 是不适用的原因。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/greybox-previs`)));
     server.tool('list_unlinked_assets', '列出本剧「已解除引用」的旧资产(免费):清尾帧、换定妆图时被摘下来的旧尾帧/旧定妆图/旧设定图/发型·身体参考/视频锚,每个 URL 一条。' +
         '这些文件仍然存在于存储里。清单会尽量排除已被重新用上的图,但不保证完全排除——某张图是否还在别处被引用,' +
         '以平台的全库检查为准。客户问「旧图还在不在」时用它。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/unlinked-assets`)));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.256",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.256 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.258",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`). For video, quote == actual charge. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.258 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -15896,6 +15896,119 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/greybox-previs": {
+      "post": {
+        "operationId": "generate_greybox_previs",
+        "summary": "按分镜已有字段**自动生成粗粒度白模**并挂到镜上(免费):景别 / 机位高度与方位 / 运镜(推拉摇移跟升降环绕) / 站位 / 朝向 / 时长 / 动作(走近、后退、转身、坐下等)→ 平台本机渲成几何体白模视频(每个角色一种颜色、只建躯",
+        "description": "按分镜已有字段**自动生成粗粒度白模**并挂到镜上(免费):景别 / 机位高度与方位 / 运镜(推拉摇移跟升降环绕) / 站位 / 朝向 / 时长 / 动作(走近、后退、转身、坐下等)→ 平台本机渲成几何体白模视频(每个角色一种颜色、只建躯干),登记成 greybox_coarse 并**自动写好 greybox_bindings**,不用客户自己建白模。目的是把景别 / 运镜 / 站位从文字约束变成像素约束,治「镜头调度不听话」。★挂上后该镜改走参考视频路径:**首尾帧不再送达**(身份靠角色参考图),**视频报价会上涨约两成**(参考视频按秒计费)——生成前把这两点讲给客户。★先 dry_run=true 看平台按哪些字段、做了哪些假设(assumptions:缺失字段的兜底),字段不对先 update_shot 改再生成。不适用的镜会返回原因:插入镜、没有出镜角色、超过 15 秒、状态变化镜(依赖尾帧终态,确需生成传 include_state_change=true)。镜上已挂客户自己的运动参考时不覆盖(409),确要替换传 replace_existing=true。传 episode_id 不传 storyboard_id = 整集批量(一次 ≤40 镜,可用 storyboard_ids 选镜)。本剧未开放时回 409(灰度中)。生成后照常 review_frames → quote_videos → generate_videos。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "dry_run": {
+                    "type": "boolean"
+                  },
+                  "replace_existing": {
+                    "type": "boolean"
+                  },
+                  "include_state_change": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      },
+      "get": {
+        "operationId": "get_greybox_previs",
+        "summary": "看某镜的自动白模(免费):attached=当前挂的是不是平台自动生成的白模;stale=true 表示镜头字段改过、白模已过时,需要重新 generate_greybox_previs;current 是按当前字段会生成的规格与假设;sk",
+        "description": "看某镜的自动白模(免费):attached=当前挂的是不是平台自动生成的白模;stale=true 表示镜头字段改过、白模已过时,需要重新 generate_greybox_previs;current 是按当前字段会生成的规格与假设;skip 是不适用的原因。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/keyframes": {
       "get": {
         "operationId": "get_shot_keyframes",
@@ -17236,6 +17349,98 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/storyboard-grid": {
+      "get": {
+        "operationId": "get_shot_storyboard_grid",
+        "summary": "★**内测**·读**某一镜**挂的宫格分镜参考(故事板)",
+        "description": "★**内测**·读**某一镜**挂的宫格分镜参考(故事板)。免费。回 grid(image_url / cells / advisories,null = 没挂)、enabled(本剧是否在内测名单)、video_engine 与 engine_supported(只有 Seedance 2.5 支持宫格参考)、tips(宫格怎么画、提示词怎么写)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "clear_shot_storyboard_grid",
+        "summary": "★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式",
+        "description": "★**内测**·清除**某一镜**的宫格分镜参考,本镜回到普通首帧出视频模式。免费。本镜已有视频会被标为待重生。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/trim": {
       "put": {
         "operationId": "trim_shot",
@@ -18667,6 +18872,10 @@
     }
   },
   "x-unmapped-tools": [
+    {
+      "tool": "set_shot_storyboard_grid",
+      "reason": "unmappable: local file upload flow"
+    },
     {
       "tool": "upload_image",
       "reason": "unmappable: local file upload flow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.256",
+  "version": "0.1.258",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.256",
+  "version": "0.1.258",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.256",
+      "version": "0.1.258",
       "transport": {
         "type": "stdio"
       },