@starreel/mcp 0.1.252 → 0.1.256

package/SKILL.md

@@ -93,6 +93,7 @@ announces a condensed version as MCP `instructions` at connect time.
 | **Structured data** — their own tool / spreadsheet export, or an external AI producing JSON (cast + scenes + shots in one go) | `get_bulk_import_spec` (contract + template + worked example + enums, same source as the validator) → `check_bulk_import` (same zod schema; unresolved character / scene references, dead shots and stage directions inside dialogue are surfaced) → `bulk_import_storyboards` (`mode: "replace"` only with the customer's explicit OK; defaults to `auto_complete`: professional fields for every shot, full image / video prompts only for shots that had no `image_prompt` — prompts you supply yourself are kept verbatim — metered text, tell the customer first; `auto_complete: false` imports only **and generates no composition contract** (visible head count, person / body-part / prop subject and shot size are then only inferred from text) — read `contract_coverage` in the receipt and follow the remedy its `note` gives (normally `autofill_storyboards`) before generating frames) → `get_autofill_status` until `done` → `review_storyboards` | converting the JSON to text for `import_storyboard_table`; hand-building shots with `update_shot`; reviewing before the completion batch finishes |
 | 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 |
 | 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 |
@@ -1545,11 +1546,14 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   A 400 "未开启" means the project is not in the beta. Render the keyframe
   images with `quote_shot_keyframes` (free) → `generate_shot_keyframes`
   (**billed**, last-frame price tier, one candidate each; needs the shot's first
-  frame). Each image is anchored to the first frame and kept in the same camera
-  setup; poll `get_shot_keyframes`: `ready` frames are used when the shot's video
-  is regenerated, `framing_mismatch` means the framing drifted from the first
-  frame (not sent; rewrite the prompt and regenerate), `failed` means the render
-  failed. Rendering keyframes never touches the shot's first/last frame.
+  frame). Each image keeps the first frame's camera setup (the shot's own last
+  frame, when generated separately, is also sent as the action's end point) and
+  moves the subject to the described instant; poll `get_shot_keyframes`: `ready`
+  frames are used when the shot's video is regenerated, `framing_mismatch` means
+  the framing drifted from the first frame and `no_progress` means the image is
+  nearly identical to the first frame (both are not sent; rewrite the prompt to
+  say where the subject is and how far the action has got, then regenerate),
+  `failed` means the render failed. Rendering keyframes never touches the shot's first/last frame.
   On the next `quote_regenerate_shot_video`, `shot_keyframes.mode=keyframes`
   confirms the video will be sent first frame + ready keyframes (+ last frame)
   with their timestamps (first frame becomes a soft constraint; ±1 s timing; same

package/dist/i18n/tools.en.json

@@ -277,5 +277,9 @@
   "get_shot_verse_cards": "Read this shot's current poem/lyric text cards (free). set_shot_verse_cards is a **full overwrite**—read before editing. enabled=false means the drama is not enabled yet (saved cards will not appear in the cut).",
   "set_shot_verse_cards": "Add/change/clear poem & lyric text cards on one shot (burned into the final cut; free, data only). Up to 6 cards per shot, **full overwrite** (read with get_shot_verse_cards first); cards=[] clears. Covers three staples of cinematic period-style shorts: (1) vertical or horizontal poem/lyric lines fading in at the left, right or center (a newline in text starts a new column/line, punctuation is kept; stagger several cards with start_ms); (2) a full-screen black closing card with backdrop=\"black\" (usually on the last shot, orient=horizontal, position=center); (3) end credits over the picture with motion=\"scroll_up\" (scrolls bottom to top, one name per line, blank lines separate groups). Cards automatically stay out of the dialogue-subtitle band, so they never overlap spoken subtitles; oversized text is shrunk instead of overflowing. Run compose_episode afterwards to re-cut (rerender_episode reuses the saved timeline and will not pick it up). enabled=false from get_shot_verse_cards means the drama is not enabled yet. ★Do not download the video, overlay text yourself and re-upload—that bypasses renderer fonts and subtitle avoidance. ★Only use the poem/credits text the customer supplied; do not invent it.",
   "get_theme_songs": "Read an episode's theme-song settings (free). set_theme_songs is a **full overwrite**—read before editing. enabled=false means the drama is not enabled yet.",
-  "set_theme_songs": "Attach/change/clear **theme songs with vocals** on an episode (opening song, ending song, or an insert song over a range of shots; free, data only, full overwrite, songs=[] clears; up to 3 per episode). Song source, pick one: (1) the customer's own song—upload via upload-url (kind=audio) and pass the public_url as audio_url; (2) platform-composed or library track—pass track_id; (3) an existing https URL. placement: opening = from 0 until the song ends or shot sb_to ends / ending = pinned to the end, or starting at shot sb_from / range = shots sb_from..sb_to (both required). Vocals never fight dialogue: with instrumental_url (the same song's backing track) the default dialogue_mode=instrumental fades the vocal out and the backing track in while someone speaks, then swaps back; with only the full song, dialogue_mode=duck lowers the whole song by duck_db (default -18 dB) during speech. Background music automatically yields inside the theme-song range (bgm_yield, default true) and is unchanged elsewhere. gain_db defaults to -8; track_offset_ms skips an intro. Run compose_episode afterwards; enabled=false means the drama is not enabled yet. ★Do not download the cut, remix it yourself and re-upload."
+  "set_theme_songs": "Attach/change/clear **theme songs with vocals** on an episode (opening song, ending song, or an insert song over a range of shots; free, data only, full overwrite, songs=[] clears; up to 3 per episode). Song source, pick one: (1) the customer's own song—upload via upload-url (kind=audio) and pass the public_url as audio_url; (2) platform-composed or library track—pass track_id; (3) an existing https URL. placement: opening = from 0 until the song ends or shot sb_to ends / ending = pinned to the end, or starting at shot sb_from / range = shots sb_from..sb_to (both required). Vocals never fight dialogue: with instrumental_url (the same song's backing track) the default dialogue_mode=instrumental fades the vocal out and the backing track in while someone speaks, then swaps back; with only the full song, dialogue_mode=duck lowers the whole song by duck_db (default -18 dB) during speech. Background music automatically yields inside the theme-song range (bgm_yield, default true) and is unchanged elsewhere. gain_db defaults to -8; track_offset_ms skips an intro. Run compose_episode afterwards; enabled=false means the drama is not enabled yet. ★Do not download the cut, remix it yourself and re-upload.",
+  "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."
 }

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

@@ -284,5 +284,9 @@
   "set_voice_anchor_from_shot": "从本剧某一镜选定角色的声线(声音基准)。免费。不需要客户提供外部音源——就用片子里这个角色已经念出来的声音。\n★★【原声剧(use_clip_audio=true,默认)里这就是「锁声线」】选定后,之后生成的视频会把这段声音交给视频厂商当参考音频,同一角色前后镜的嗓音跟它走;不锁的话每镜由厂商各自采样,前后镜声线会漂。\n★选哪一镜:该角色**独自说话、台词较长、没有背景音乐和别人插话**的镜;start_s/dur_s 可只截其中一段(不传则取默认窗口,时长会按各引擎上限自动钳制)。\n★只对**之后**生成的视频生效。锁之前已经出好的镜会出现在 get_pipeline_status 的 native_voice_anchor.stale_shots 里,用 regenerate_shot_video 重出才会统一。所以最省的做法是:每个说话角色先出一镜、选定声线,再批量出其余镜。\n★台词栏为空也能用:以实际音频为准——平台用已标定的人声探测确认所选区间里有人声,并把转写文字当锚文本;探测不到人声、或转写不出可用文字就拒(锚选错会污染此后所有镜的嗓音,宁拒不猜)。响应里 text_source 标明文本来自台词还是转写。\n★先 preview:true 试听:只截取并返回 preview_url 与锚文本,**不写入角色**;听着对再去掉 preview、用同样的 start_s/dur_s 正式提交。\n★去环境音与验收(平台按剧开启时生效,响应里有 hygiene 字段):自动剔除两句之间的纯环境音停顿,并测样本底噪(noise_floor_before/after,阈值 threshold)。preview 时 preview_url 是**清理后**的样本、raw_preview_url 是原样本——**请让客户前后对比试听**。verdict=fail 表示人声下面垫着明显的环境声或音乐(剔停顿救不了,克隆和视频厂商会把它当音色学走),正式提交会被拒:换一镜念得更干净的、或调 start_s/dur_s 避开背景声;只有客户听过后明确坚持,才带 allow_issues:true 写入。\n★有客户授权的外部音源时改用 clone_voice + set_character_voice;两者二选一,后设的覆盖先设的。",
   "export_handoff_pack": "启用交付追溯后会保存不可变导出清单（不改素材）。保留 pack_id 和 manifest_sha256，回传外部成片时引用。导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼。免费,零扣费。\n★本地调色/第三方 AI 后期:purpose=local_color;只有图片时传 media_type=images,无需生成视频。本模式保留源文件、关闭导出包的自动 LUT、附带后期说明和本地对比页流程;不上传第三方、不收费生成、不回填平台。图片来源可能已有处理,不能把所有导出图承诺为未调色原片。\n\n【推荐流程】① 调本工具拿 manifest;② 按 clips[].url 把裸片下载到本地;③ 你自己看片判断每个接缝该用什么转场(manifest 给了 scene_boundary 场景边界作判据),写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n\n【三个不看就会翻车的事实】\n① **人声在哪要逐镜读 `shots[].voice_track.location`,不能读整集的 audio_contract.mode**——后者是整剧级声明,而全画外旁白镜的旁白是平台在完成侧混进裸片的,同一集里逐镜可以不同。四种取值各有各的处置:`separate_file`=对白在 dialogue_audio,不铺这镜就没台词;`baked_in_clip`=已在裸片音轨里,再叠一遍会双声;`missing`=**平台侧确认缺失**(旁白补偿失败),字幕还在但声音哪都没有——回平台重生成该镜,拉长转场掩盖不了;`unknown`=有台词却查不到来源,**必须试听裸片**再决定。★有字幕从来不等于有声音:字幕是逐句的,音频是逐镜的。`conflicts_with_contract=true` 的镜以实测为准,notes 里已按镜号点名。\n② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的首尾形变帧一起拼进去。★manifest_version=0.2 起入出点投影自平台终拼时间轴(与 build_av_timing_contract、平台成片同一套),clip.url 是时间轴实际用的那个文件(clip.source_kind);0.1 时代交接包自算的 trim 与成片对不上。speed_factor≠1 要按倍率变速、freeze_pad_ms>0 要克隆末帧补齐(duration_ms=(out_ms−in_ms)/speed_factor+freeze_pad_ms),否则总长对不上;subtitles_burned_in=true 别再烧字幕,color_graded=true 别再套 LUT;trim_basis≠platform_timeline 的镜是整条不裁,notes 写了原因。工具链只认 0.1 的旧副本会拒收 0.2,重新 save_handoff_toolchain。\n③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,不是成片绝对时间。你加多少重叠转场都不用改它们——交给 compile_timeline.py 展开,别手算累加。\n\n拼之前先跑 build_av_timing_contract → get_av_timing_contract(免费):逐镜实测源片时长、平台终拼的入出点/转场占用/定格补帧、人声已混入视频还是独立轨,拿它核对你的时间轴总长。\n想让平台代拼、要平台级质量闸(终拼预检/音画等长/响度母带),改用 compose_episode。",
   "get_handoff_toolchain": "拿到素材交接包的装配工具链源码(compile_timeline.py 时间轴编译器 / assemble.sh ffmpeg 装配脚本)。免费。本工具只返回源码文本,**不会**在你机器上写文件——请自行保存到工作目录再执行。\ncompile_timeline.py 负责把「镜相对」的字幕/对白/音效锚点展开成你自己时间轴上的绝对时间码,并处理重叠转场引起的整体位移;assemble.sh 是从裸片到成片的完整 ffmpeg 装配基线(裁剪→规范化→拼接/xfade→配乐侧链→字幕→两 pass 母带)。依赖 ffmpeg(烧字幕需带 libass)、ffprobe、jq、python3。",
-  "save_handoff_toolchain": "把装配工具链(fetch_pack.py / compile_timeline.py / assemble.sh)直接写到你本地的一个目录,省掉自己复制粘贴。免费。目录必须**已存在**且是绝对路径;文件名固定,不接受自定义。\n拒绝写入隐藏目录(~/.ssh、~/.config、.git…)与系统目录——这是写盘不是读盘,覆盖错地方不可逆。\n落盘后完整流程:\n  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材、内联字幕落成 SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]"
+  "save_handoff_toolchain": "把装配工具链(fetch_pack.py / compile_timeline.py / assemble.sh)直接写到你本地的一个目录,省掉自己复制粘贴。免费。目录必须**已存在**且是绝对路径;文件名固定,不接受自定义。\n拒绝写入隐藏目录(~/.ssh、~/.config、.git…)与系统目录——这是写盘不是读盘,覆盖错地方不可逆。\n落盘后完整流程:\n  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材、内联字幕落成 SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]",
+  "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 = 同一素材保留原绑定、换了素材就清空。"
 }

package/dist/tools/guide-data.js

@@ -381,6 +381,7 @@ export const COMMON_REQUESTS = [
     { customer_says: '下载原图或视频到本地调色、用第三方 AI 后期', do: '`export_handoff_pack` purpose=local_color；只有图片传 media_type=images；按 local_postproduction.color_handoff 执行。' },
     { 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: '`update_project_settings` use_clip_audio=false → `assign_voices` → `generate_tts` → `compose_episode`。' },
 ];
 /**

package/dist/tools/produce.js

@@ -1347,7 +1347,7 @@ export function registerProduceTools(server, client) {
             prompt: z.string().min(2).max(600).describe('这一刻看得见的画面'),
         })).max(3),
     }, async ({ storyboard_id, keyframes }) => jsonResult(await client.producePut(`/storyboards/${storyboard_id}/keyframes`, { keyframes })));
-    server.tool('quote_shot_keyframes', '★**内测**·中间关键帧出图**报价**(免费·无副作用)。默认报本镜所有还没就绪的中间帧(planned / failed / framing_mismatch),'
+    server.tool('quote_shot_keyframes', '★**内测**·中间关键帧出图**报价**(免费·无副作用)。默认报本镜所有还没就绪的中间帧(planned / failed / framing_mismatch / no_progress),'
         + 'keyframe_ids 可点名重出。回 estimated_points / typical_points、要出的 keyframes 与 quote_id。'
         + '\n★前提:本镜视频引擎是 Seedance 2.5、首帧已就绪、已用 plan_shot_keyframes / set_shot_keyframes 写好中间帧。'
         + '把 estimated_points 原样告诉客户,同意后再调 generate_shot_keyframes。回 400「本剧未开启」= 不在内测名单,别重试。', {
@@ -1355,9 +1355,9 @@ export function registerProduceTools(server, client) {
         keyframe_ids: z.array(z.number().int().positive()).max(3).optional().describe('只重出这几张(默认:所有未就绪的)'),
         image_model: z.string().optional().describe('临时换图片模型(报价与出图要传同一个)'),
     }, async ({ storyboard_id, keyframe_ids, image_model }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/keyframes/quote`, { keyframe_ids, image_model })));
-    server.tool('generate_shot_keyframes', '★**内测**·按报价出本镜中间关键帧图(**真扣费**)。每张以本镜首帧为锚、保持同一机位取景,只画到 prompt 描述的那一刻;'
+    server.tool('generate_shot_keyframes', '★**内测**·按报价出本镜中间关键帧图(**真扣费**)。每张以本镜首帧为机位锚(有独立尾帧时一并作动作终点参考)、保持同一机位取景,人物按 prompt 推进到描述的那一刻;'
         + '不改本镜首尾帧、不把已有视频标陈旧。异步:立即返回 dispatched,用 get_shot_keyframes 轮询每张 status——'
-        + 'ready 才会在重出本镜视频时送进 Seedance 2.5;framing_mismatch = 取景与首帧对不上(不送),改 prompt 后报价重出;failed = 出图失败。'
+        + 'ready 才会在重出本镜视频时送进 Seedance 2.5;framing_mismatch = 取景与首帧对不上、no_progress = 与首帧几乎一样(动作没推进),这两种都不送,改 prompt 写清这一刻人物到了哪、做到哪一步后报价重出;failed = 出图失败。'
         + '\n★报价后改过关键帧会 409,重新报价(免费)即可。' + REVIEW_GATE_HINT('review_storyboards', '分镜') + ASSET_GATE_HINT + CONFIRM_HINT, {
         storyboard_id: z.number().int().positive(),
         quote_id: z.string().describe('来自 quote_shot_keyframes'),
@@ -1621,6 +1621,36 @@ export function registerProduceTools(server, client) {
         const video_url = await client.uploadLocalFile(file_path, 'footage');
         return jsonResult(await client.producePost(`/storyboards/${storyboard_id}/footage`, { video_url }));
     });
+    const GREYBOX_KIND_DESC = 'footage=真人实拍 / 成片当动作参考(默认);greybox_coarse=简单几何体拼的粗粒度白模(官方推荐,效果最好);' +
+        'greybox_fine=建模完整的细粒度白模(视频里别带轨迹线 / 坐标轴 / 相机锥,会漏进成片)';
+    server.tool('create_motion_reference', '把一段**动作 / 运镜参考视频**登记进本人运动参考库(免费),之后用 attach_motion_reference 挂到某镜,AI 出视频时照它的动作、运镜、站位重新生成。' +
+        '★**白模(3D 预演)走这里**:kind 选 greybox_coarse / greybox_fine,平台会告诉模型「白模只作运镜 / 节奏 / 景别 / 运动轨迹 / 站位参考,不参考几何体外形和灰模材质」。' +
+        '白模建议:粗粒度最好,只用简单几何体拼人物 / 物体;身体只建躯干即可,建了四肢 / 翅膀就把动作补全,否则成片四肢僵硬;单段 ≤30 秒(Seedance 2.5),主体 1~5 个效果最好。' +
+        '⚠️ 与 upload_shot_footage 的区别:那个是「这段视频**就是**成片」,本工具是「照这段视频**重新生成**」。', {
+        file_path: z.string().describe('本地视频路径(mp4/mov/webm/m4v)'),
+        name: z.string().min(1).max(80).describe('素材名,方便以后在 list_motion_references 里认出来'),
+        kind: z.enum(['footage', 'greybox_coarse', 'greybox_fine']).optional().describe(GREYBOX_KIND_DESC),
+        description: z.string().max(240).optional(),
+    }, async ({ file_path, name, kind, description }) => {
+        const video_url = await client.uploadLocalFile(file_path, 'video');
+        return jsonResult(await client.producePost('/motion-references', { video_url, name, kind, description }));
+    });
+    server.tool('list_motion_references', '列出本人运动参考库里的素材(含白模),免费。返回 id / name / kind / video_url;id 给 attach_motion_reference 用。', {}, async () => jsonResult(await client.produceGet('/motion-references')));
+    server.tool('get_shot_motion_reference', '看某镜当前挂的运动参考 / 白模与「色块 → 角色」绑定(免费)。greybox_gray_on=false 表示本剧还没开放白模渲染,白模按普通运动参考处理。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/motion-reference`)));
+    server.tool('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 = 同一素材保留原绑定、换了素材就清空。', {
+        storyboard_id: z.number().int().positive(),
+        asset_id: z.number().int().positive().nullable().describe('list_motion_references / create_motion_reference 返回的 id;null = 解除挂载'),
+        greybox_bindings: z.array(z.object({
+            proxy: z.string().min(1).max(24).describe('白模里那个模型的称呼,如「红色模型」「1号模型」'),
+            character_id: z.number().int().positive(),
+        })).max(10).nullable().optional().describe('白模色块 → 本剧角色;null / [] 清空'),
+    }, 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('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.252",
-    "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.252 tool surface (operationIds match MCP tool names 1:1)."
+    "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)."
   },
   "servers": [
     {
@@ -51,6 +51,10 @@
       "name": "images",
       "description": "Operations under /images"
     },
+    {
+      "name": "motion-references",
+      "description": "Operations under /motion-references"
+    },
     {
       "name": "production-menu",
       "description": "Operations under /production-menu"
@@ -12643,6 +12647,42 @@
         }
       }
     },
+    "/motion-references": {
+      "get": {
+        "operationId": "list_motion_references",
+        "summary": "列出本人运动参考库里的素材(含白模),免费",
+        "description": "列出本人运动参考库里的素材(含白模),免费。返回 id / name / kind / video_url;id 给 attach_motion_reference 用。",
+        "tags": [
+          "motion-references"
+        ],
+        "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"
+          }
+        }
+      }
+    },
     "/production-menu": {
       "post": {
         "operationId": "get_production_menu",
@@ -15991,7 +16031,7 @@
       "post": {
         "operationId": "generate_shot_keyframes",
         "summary": "★**内测**·按报价出本镜中间关键帧图(**真扣费**)",
-        "description": "★**内测**·按报价出本镜中间关键帧图(**真扣费**)。每张以本镜首帧为锚、保持同一机位取景,只画到 prompt 描述的那一刻;不改本镜首尾帧、不把已有视频标陈旧。异步:立即返回 dispatched,用 get_shot_keyframes 轮询每张 status——ready 才会在重出本镜视频时送进 Seedance 2.5;framing_mismatch = 取景与首帧对不上(不送),改 prompt 后报价重出;failed = 出图失败。\n★报价后改过关键帧会 409,重新报价(免费)即可。\n★【分镜审查硬闸·免费】本步前必须先调 review_storyboards:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。单镜工具(generate_shot_frame / regenerate_shot_video)只核本镜与相邻镜:改了别的镜不用复审;本镜、相邻镜或共享资产变了才 400——这时带 base_review_token=<旧 token> 调审查工具做增量复审,只重审变更镜,质检也只看变更镜。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费(acknowledge_review 只代表客户本人同意,任何执行模式都须客户明确同意,托管也不例外);托管环节只有白名单内的启发式 error 能带 auto_acknowledge:true 放行(平台判,不在白名单回 400 AUTOPILOT_MUST_ASK:must_ask_customer=true 才暂停问客户,false = 按 action 自修复审)。★灰度剧还要你(agent)亲自质检:按 review_storyboards 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。\n★【资产层硬闸·免费】还要先跑 review_assets(角色形象图/场景图/道具图),把它的 review_token 作为 asset_review_token 传进来(与分镜层的 review_token 并存,两张都要;灰度剧缺了会 400 并点名 review_assets)。出完帧不会让资产 token 失效。⚠️ 批量报价确认流程:先调对应的 quote_* 工具拿 estimated_points 与 quote_id,再用 quote_id 调本工具(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。托管环节报价须在预算硬上限内,被 402 BUDGET_WOULD_EXCEED 拦下就停下问客户。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "description": "★**内测**·按报价出本镜中间关键帧图(**真扣费**)。每张以本镜首帧为机位锚(有独立尾帧时一并作动作终点参考)、保持同一机位取景,人物按 prompt 推进到描述的那一刻;不改本镜首尾帧、不把已有视频标陈旧。异步:立即返回 dispatched,用 get_shot_keyframes 轮询每张 status——ready 才会在重出本镜视频时送进 Seedance 2.5;framing_mismatch = 取景与首帧对不上、no_progress = 与首帧几乎一样(动作没推进),这两种都不送,改 prompt 写清这一刻人物到了哪、做到哪一步后报价重出;failed = 出图失败。\n★报价后改过关键帧会 409,重新报价(免费)即可。\n★【分镜审查硬闸·免费】本步前必须先调 review_storyboards:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。单镜工具(generate_shot_frame / regenerate_shot_video)只核本镜与相邻镜:改了别的镜不用复审;本镜、相邻镜或共享资产变了才 400——这时带 base_review_token=<旧 token> 调审查工具做增量复审,只重审变更镜,质检也只看变更镜。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费(acknowledge_review 只代表客户本人同意,任何执行模式都须客户明确同意,托管也不例外);托管环节只有白名单内的启发式 error 能带 auto_acknowledge:true 放行(平台判,不在白名单回 400 AUTOPILOT_MUST_ASK:must_ask_customer=true 才暂停问客户,false = 按 action 自修复审)。★灰度剧还要你(agent)亲自质检:按 review_storyboards 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。\n★【资产层硬闸·免费】还要先跑 review_assets(角色形象图/场景图/道具图),把它的 review_token 作为 asset_review_token 传进来(与分镜层的 review_token 并存,两张都要;灰度剧缺了会 400 并点名 review_assets)。出完帧不会让资产 token 失效。⚠️ 批量报价确认流程:先调对应的 quote_* 工具拿 estimated_points 与 quote_id,再用 quote_id 调本工具(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。托管环节报价须在预算硬上限内,被 402 BUDGET_WOULD_EXCEED 拦下就停下问客户。★**出图类报价(定妆图/场景图/出帧)给的是两个数**:estimated_points 是**上界**(按该模型参考图张数上限估,保证你不会按低了的预算开跑、出到一半 402 中断);同一响应里的 typical_points 是**通常花费**。两个都要告诉客户——只说上界会让人以为贵得多(满参考图的上界可达通常值的 2 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
         "tags": [
           "storyboards"
         ],
@@ -16080,7 +16120,7 @@
       "post": {
         "operationId": "quote_shot_keyframes",
         "summary": "★**内测**·中间关键帧出图**报价**(免费·无副作用)",
-        "description": "★**内测**·中间关键帧出图**报价**(免费·无副作用)。默认报本镜所有还没就绪的中间帧(planned / failed / framing_mismatch),keyframe_ids 可点名重出。回 estimated_points / typical_points、要出的 keyframes 与 quote_id。\n★前提:本镜视频引擎是 Seedance 2.5、首帧已就绪、已用 plan_shot_keyframes / set_shot_keyframes 写好中间帧。把 estimated_points 原样告诉客户,同意后再调 generate_shot_keyframes。回 400「本剧未开启」= 不在内测名单,别重试。",
+        "description": "★**内测**·中间关键帧出图**报价**(免费·无副作用)。默认报本镜所有还没就绪的中间帧(planned / failed / framing_mismatch / no_progress),keyframe_ids 可点名重出。回 estimated_points / typical_points、要出的 keyframes 与 quote_id。\n★前提:本镜视频引擎是 Seedance 2.5、首帧已就绪、已用 plan_shot_keyframes / set_shot_keyframes 写好中间帧。把 estimated_points 原样告诉客户,同意后再调 generate_shot_keyframes。回 400「本剧未开启」= 不在内测名单,别重试。",
         "tags": [
           "storyboards"
         ],
@@ -16193,6 +16233,156 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/motion-reference": {
+      "get": {
+        "operationId": "get_shot_motion_reference",
+        "summary": "看某镜当前挂的运动参考 / 白模与「色块 → 角色」绑定(免费)",
+        "description": "看某镜当前挂的运动参考 / 白模与「色块 → 角色」绑定(免费)。greybox_gray_on=false 表示本剧还没开放白模渲染,白模按普通运动参考处理。",
+        "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"
+          }
+        }
+      },
+      "post": {
+        "operationId": "attach_motion_reference",
+        "summary": "把运动参考 / 白模挂到某镜(免费),asset_id=null 解除挂载(绑定一并清掉)",
+        "description": "把运动参考 / 白模挂到某镜(免费),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 = 同一素材保留原绑定、换了素材就清空。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "asset_id": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "exclusiveMinimum": 0
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "list_motion_references / create_motion_reference 返回的 id;null = 解除挂载"
+                  },
+                  "greybox_bindings": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "proxy": {
+                              "type": "string",
+                              "minLength": 1,
+                              "maxLength": 24,
+                              "description": "白模里那个模型的称呼,如「红色模型」「1号模型」"
+                            },
+                            "character_id": {
+                              "type": "integer",
+                              "exclusiveMinimum": 0
+                            }
+                          },
+                          "required": [
+                            "proxy",
+                            "character_id"
+                          ],
+                          "additionalProperties": false
+                        },
+                        "maxItems": 10
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  }
+                },
+                "required": [
+                  "asset_id"
+                ]
+              }
+            }
+          }
+        },
+        "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}/name-card": {
       "get": {
         "operationId": "get_shot_name_card",
@@ -18493,6 +18683,10 @@
       "tool": "upload_shot_footage",
       "reason": "unmappable: local file upload flow"
     },
+    {
+      "tool": "create_motion_reference",
+      "reason": "unmappable: local file upload flow"
+    },
     {
       "tool": "upload_scene_image",
       "reason": "unmappable: local file upload flow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.252",
+  "version": "0.1.256",
   "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.252",
+  "version": "0.1.256",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.252",
+      "version": "0.1.256",
       "transport": {
         "type": "stdio"
       },