@starreel/mcp 0.1.251 → 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

@@ -119,7 +119,7 @@
   "upload_prop_sheet": "Use the customer's own image as a prop sheet for a prop. Auto upload + register. Free.\n★【Post-completion QC · free】After generation, wait until images are stored (poll corresponding get_* for status; do not repeat-call while pending), then call review_assets for asset-layer review (missing images / generating / failed / rejected by consistency gate / prop-era conflict / color script), tell customer findings verbatim, fix by action and re-review; then manually inspect images one by one per returned agent_qc (matches profile, same person, correct era; character sheet angles complete, proportions/structure correct; props and scene images make sense in story—check the shots in material used_in_shots), submit_qc_report; when generating shot frames, pass its review_token as asset_review_token to generate_frames / generate_shot_frame.",
   "get_edit_capabilities": "Check video edit capability switches (whether in-place edit / range replacement is available). Free.",
   "quote_edit_video_shot": "Quote: credits needed to do in-place edit/range replacement (Seedance 2.5) on a shot. Returns quote_id. No charge. This shot must already have video.",
-  "edit_video_shot": "After confirmation, in-place edit a shot video: modify by instruction, optionally with reference image/video/audio, or use start_sec/end_sec for range replacement. model can select an engine specifically for this edit (may differ from the drama engine): hailuo-3=MiniMax H3 high-fidelity edit at about 1/3 cost; wan3.0/wan3.0-prime=WAN 3.0 strong semantic edit at about 40% cost (environment may follow instruction expansion); H3/WAN do not support start_sec/end_sec ranges (passing them returns 400), and input video for edit/continuation is charged by seconds on H3/WAN.\n★If receipt contains `edit_instruction_negation_advisory` = your instruction has **negative constraints** (\"must not use X\", \"do not show X\"). Video models treat nouns as positive cues; writing \"do not X\" often makes X appear instead—the negated action/object is exactly the most salient model prior. This is not blocked; task was submitted normally; but **next time you revise the instruction, you must remove negative sentences and use positive descriptions** (write what should happen specifically: starting action, hand position, duration of each beat), otherwise the same issue will recur. Verified case: customer wrote \"must not use the static dance pose in the reference image with raised hand and one foot\", and the final cut opening arm-raise was pulled by that raised-hand reference.\n★If you receive **409 \"this shot is user-uploaded live-action footage\"** = this shot was registered by upload_shot_footage as a live-action footage shot; not a model or engine problem, switching engines and retrying is useless. Two paths: to use this footage as source for AI repaint → resend with replace_user_footage=true; to restore it to a normal AI shot → first clear_shot_footage.\n★If you receive **409 + `in_flight_generation_id`** = this shot still has a generation not finished (previous edit / regeneration / batch video generation); this edit was not submitted and not charged, quote is invalidated. The edit source is the shot's current video; when the in-flight generation completes it will replace it—so wait for completion, inspect result, then re-quote and edit; **do not chain-send** multiple edits expecting them to stack, each one is based only on the source at that time. If the in-flight one is exactly the same edit you just submitted (e.g. retry after timeout), just wait for its result, do not submit again. Resending the identical edit (same instruction, reference assets, range, engine) will not 409; it attaches to the in-flight one without duplicate charge.\n★One-click final cut autopilot stage: video regeneration for the same shot max 3 times (combined with regenerate_shot_video); at limit returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, not charged, quote not consumed)—do not bypass with another tool; stop and ask customer: if customer agrees to more generations, quote normally and generate with customer_approved_more_regens:true (grants another limit); if customer accepts current state, continue, and next paid call includes acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not constrained by this limit. ⚠️ Batch quote confirmation flow: first call corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / customer-controlled stage → tell customer and proceed only after consent, do not decide for them; autopilot stage → do not ask customer, follow get_production_plan autopilot.default_decisions, platform records in get_autopilot_log). Autopilot-stage quotes must be within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★**Image-generation quotes (character sheet/scene image/frame generation) provide two numbers**: estimated_points is the **upper bound** (estimated by that model's max reference-image count, ensuring you do not start with too-low budget and hit 402 mid-run); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it look much more expensive (full-reference upper bound can be over 2× typical), only saying typical may leave insufficient balance. For fixed-price models they are equal; then say one number. Video-generation quote and charge use the same function; no range.\n★【Post-completion QC · free】After generation, wait until stored (get_storyboards for video_status / get_pipeline_status), then call review_videos for video and dubbing-layer review (missing video / video made from old frame / hard cut at end / unexpected voice / missing dubbing / voice timbre unassigned / original voice expired), fix and re-review; then manually watch each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit_qc_report; compose_episode must include its review_token.",
+  "edit_video_shot": "After confirmation, in-place edit a shot video: modify by instruction, optionally with reference image/video/audio, or use start_sec/end_sec for range replacement. model can select an engine specifically for this edit (may differ from the drama engine): hailuo-3=MiniMax H3 high-fidelity edit at about 1/3 cost; wan3.0/wan3.0-prime=WAN 3.0 strong semantic edit at about 40% cost (environment may follow instruction expansion); H3/WAN do not support start_sec/end_sec ranges (passing them returns 400), and input video for edit/continuation is charged by seconds on H3/WAN.\n★Reference asset counts are checked against the engine actually dispatched for this edit (model first, otherwise the drama engine): Seedance 2.5 = 30 reference images / 9 extra reference videos (the source video takes 1 more slot; total video length ≤30s) / 10 reference audios; other engines = 9 / 2 / 3 (2.0 total video length ≤15s). Exceeding returns 400 with no charge — **the platform will not truncate for you**: \"image N / video N / audio N\" in the instruction are numbered by upload order, so renumber after trimming. Official guidance: 1–5 reference images work best for video editing, 6–8 are worth trying, more is not necessarily better.\n★If receipt contains `edit_instruction_negation_advisory` = your instruction has **negative constraints** (\"must not use X\", \"do not show X\"). Video models treat nouns as positive cues; writing \"do not X\" often makes X appear instead—the negated action/object is exactly the most salient model prior. This is not blocked; task was submitted normally; but **next time you revise the instruction, you must remove negative sentences and use positive descriptions** (write what should happen specifically: starting action, hand position, duration of each beat), otherwise the same issue will recur. Verified case: customer wrote \"must not use the static dance pose in the reference image with raised hand and one foot\", and the final cut opening arm-raise was pulled by that raised-hand reference.\n★If you receive **409 \"this shot is user-uploaded live-action footage\"** = this shot was registered by upload_shot_footage as a live-action footage shot; not a model or engine problem, switching engines and retrying is useless. Two paths: to use this footage as source for AI repaint → resend with replace_user_footage=true; to restore it to a normal AI shot → first clear_shot_footage.\n★If you receive **409 + `in_flight_generation_id`** = this shot still has a generation not finished (previous edit / regeneration / batch video generation); this edit was not submitted and not charged, quote is invalidated. The edit source is the shot's current video; when the in-flight generation completes it will replace it—so wait for completion, inspect result, then re-quote and edit; **do not chain-send** multiple edits expecting them to stack, each one is based only on the source at that time. If the in-flight one is exactly the same edit you just submitted (e.g. retry after timeout), just wait for its result, do not submit again. Resending the identical edit (same instruction, reference assets, range, engine) will not 409; it attaches to the in-flight one without duplicate charge.\n★One-click final cut autopilot stage: video regeneration for the same shot max 3 times (combined with regenerate_shot_video); at limit returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, not charged, quote not consumed)—do not bypass with another tool; stop and ask customer: if customer agrees to more generations, quote normally and generate with customer_approved_more_regens:true (grants another limit); if customer accepts current state, continue, and next paid call includes acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not constrained by this limit. ⚠️ Batch quote confirmation flow: first call corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / customer-controlled stage → tell customer and proceed only after consent, do not decide for them; autopilot stage → do not ask customer, follow get_production_plan autopilot.default_decisions, platform records in get_autopilot_log). Autopilot-stage quotes must be within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★**Image-generation quotes (character sheet/scene image/frame generation) provide two numbers**: estimated_points is the **upper bound** (estimated by that model's max reference-image count, ensuring you do not start with too-low budget and hit 402 mid-run); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it look much more expensive (full-reference upper bound can be over 2× typical), only saying typical may leave insufficient balance. For fixed-price models they are equal; then say one number. Video-generation quote and charge use the same function; no range.\n★【Post-completion QC · free】After generation, wait until stored (get_storyboards for video_status / get_pipeline_status), then call review_videos for video and dubbing-layer review (missing video / video made from old frame / hard cut at end / unexpected voice / missing dubbing / voice timbre unassigned / original voice expired), fix and re-review; then manually watch each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit_qc_report; compose_episode must include its review_token.",
   "get_repaint_capabilities": "Check which video-to-video repaint modes are available for this drama: whether repaint (video repaint) / reskin (outfit-change repaint) is open, maxSourceSec per source segment, relayMaxSegments max segments for long-shot relay (0=not open; shots >5 seconds cannot repaint). Free.",
   "quote_repaint_shot_video": "Quote: credits needed to do **video repaint** on a shot (redraw character and outfit by description + reference image, preserve source motion). Returns quote_id. No charge. This shot must already have video. Quote only applies to this shot's current video segment—if video is later replaced (regenerate/upload/edit completion), starting will 409; just re-quote.\n★Division vs edit_video_shot: edit modifies the image by instruction (change background/color/local edits); repaint/outfit-change repaint **uses the shot's existing video as motion skeleton and redraws the whole character and outfit**, with action, lip-sync timing, camera movement following source, and audio track pasted back to source.\n★**Customer's own video can also be repainted**: first use upload_shot_footage to register it as live-action footage for a shot (extracts first/last frames and writes back duration), then quote/start on that shot; after repaint result writes back, the shot is no longer a live-action footage shot.\n★Duration: ≤5 seconds per order (charged as 5 seconds); if this drama has long-shot relay enabled (get_repaint_capabilities relayMaxSegments>0), 5~about 14 seconds auto-splits into ≤3 relay segments, each segment one order, quote is total; longer requires split_shot first.\n★Async: start returns one generation record (segment 1 for relay); use get_repaint_status(storyboard_id, generation_id) to check completed/failed; relay in progress includes relay.segments_done/segments. On completion, this shot's video is replaced with repaint result; if unsatisfied, use restore_repaint_original to switch back to source (free).",
   "repaint_shot_video": "After confirmation, do video repaint on a shot. Charge cap = quote estimated_points (total for whole chain in relay).\n★Reference image: if reference_image_url is not passed, automatically uses the shot characters' (outfit-change) character sheets—**without a reference image, the person will still be replaced**; auto_reference=false means explicitly no reference image (draw only by description).\n★keep_scene defaults true: adds this shot's scene/props/action into description and only changes person and clothing; pass false = repaint scene too.\n★control: posebodyface (default, preserves lip-sync; use for talking shots)/ posebody (no face, mouth does not move)/ depth (by depth, solid-color backgrounds may produce vertical stripes)/ scribble (line art). strength only accepts 0 or 1.\n★If this shot is bound to product text (must preserve original product wording), it will be rejected (repaint redraws text in the image).\n★Division vs edit_video_shot: edit modifies the image by instruction (change background/color/local edits); repaint/outfit-change repaint **uses the shot's existing video as motion skeleton and redraws the whole character and outfit**, with action, lip-sync timing, camera movement following source, and audio track pasted back to source.\n★**Customer's own video can also be repainted**: first use upload_shot_footage to register it as live-action footage for a shot (extracts first/last frames and writes back duration), then quote/start on that shot; after repaint result writes back, the shot is no longer a live-action footage shot.\n★Duration: ≤5 seconds per order (charged as 5 seconds); if this drama has long-shot relay enabled (get_repaint_capabilities relayMaxSegments>0), 5~about 14 seconds auto-splits into ≤3 relay segments, each segment one order, quote is total; longer requires split_shot first.\n★Async: start returns one generation record (segment 1 for relay); use get_repaint_status(storyboard_id, generation_id) to check completed/failed; relay in progress includes relay.segments_done/segments. On completion, this shot's video is replaced with repaint result; if unsatisfied, use restore_repaint_original to switch back to source (free). ⚠️ Batch quote confirmation flow: first call corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation follows execution mode: professional mode / unconfirmed plan / customer-controlled stage → tell customer and proceed only after consent, do not decide for them; autopilot stage → do not ask customer, follow get_production_plan autopilot.default_decisions, platform records in get_autopilot_log). Autopilot-stage quotes must be within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask customer. ★**Image-generation quotes (character sheet/scene image/frame generation) provide two numbers**: estimated_points is the **upper bound** (estimated by that model's max reference-image count, ensuring you do not start with too-low budget and hit 402 mid-run); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it look much more expensive (full-reference upper bound can be over 2× typical), only saying typical may leave insufficient balance. For fixed-price models they are equal; then say one number. Video-generation quote and charge use the same function; no range.",
@@ -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

@@ -88,6 +88,11 @@
   "delete_world_state_event": "删掉一条手工事件(免费)。只能删手工加的,AI 抽取出来的要靠 rebuild_world_state 重算。",
   "link_world_state_scene_variant": "把账本里的某条事件关联到一个**场景变体**(免费)。用途：同一场景在事件前后长得不一样(灯亮/灯灭、完好/破损),关联之后出图会取对应那版场景图。",
   "derive_pose_chain": "派生**姿态链**(Action Graph)：从相邻镜的动作推出每镜的起止姿态，让镜间衔接不跳。**要花钱**(走 LLM)。\n★只填**空着**的那些镜，已经写了姿态的不动;黑场镜自动跳过。\n出图前做，能减少「上一镜站着下一镜突然坐着」这类接不上的情况。",
+  "plan_shot_keyframes": "★**内测**·规划**单镜中间关键帧**：给动作复杂的镜头在首帧与尾帧之间加 1~3 个「第 t 秒该是什么画面」的目标(蓄力、命中、落地等节点),让视频动作按节点走、不跳过过程。**要花钱**(走 LLM,文本按 token 后付)。\n★只规划视频引擎为 seedance-2.5 的镜(只有它按秒对齐关键帧,误差约 ±1 秒);时长 ≥5 秒、标为状态变化或关键镜的才会规划。\n★只填**空着**的镜:已经有中间关键帧的(含客户自己写的)一律不动。dry_run:true 只返回规划不写库,先给客户看。\n★结果用 get_storyboards 每镜的 keyframes 字段读;要改用 set_shot_keyframes。\n★回 400「本剧未开启」= 本剧不在内测名单,不是调用错误,别重试。规划完用 quote_shot_keyframes → generate_shot_keyframes 出中间帧图。",
+  "get_shot_keyframes": "★**内测**·读**某一镜**的中间关键帧与可放范围。免费。回 keyframes(每项 t_sec / prompt / source=planner|author / status)、window(min_t、max_t、相邻最小间隔 gap、本镜最多几张 cap)与 enabled(本剧是否在内测名单)。写之前先读这里,按 window 排秒数,再调 set_shot_keyframes。",
+  "set_shot_keyframes": "★**内测**·写**某一镜**的中间关键帧(整体覆盖;[] = 清空)。免费(纯文本写库)。\n每项 { t_sec, prompt }:t_sec 是镜内第几秒,必须落在 [2, 时长-1] 之内(开头会定格在首帧、结尾留给尾帧),相邻至少间隔 2 秒,每镜最多 3 张;prompt 写那一刻**看得见的**画面(人在哪、什么姿态、物件什么状态、景别机位与首帧一致)。\n★不收「正要 / 刚开始 / about to」这类起点措辞(单帧画不出「正在开始」),也不收「没有 X / no X」否定句(会把 X 画出来);违规会 400 并说明哪一张哪里不对,照着改写再提交。\n★先 get_storyboards 读现值再改。回 400「本剧未开启」= 本剧不在内测名单。",
+  "quote_shot_keyframes": "★**内测**·中间关键帧出图**报价**(免费·无副作用)。默认报本镜所有还没就绪的中间帧(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「本剧未开启」= 不在内测名单,别重试。",
+  "generate_shot_keyframes": "★**内测**·按报价出本镜中间关键帧图(**真扣费**)。每张以本镜首帧为锚、保持同一机位取景,只画到 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "quote_extend_final": "★成片续写**报价**(免费·无副作用):在已有成片后面再接几轮 AI 生成的片段,把片子拉长。回 rounds(轮数)/duration_per_round(每轮秒数)/max_rounds(上限)/estimated_points(预估点数)。\n★**必须先 quote_extend_final 报价,再调 extend_final**(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)(派发前平台按同参整单报价过预算预检,超出硬上限回 402 BUDGET_WOULD_EXCEED、未扣费,那就停下问客户)——每轮都真扣厂商的钱。\n★回 403 = 本剧没开这个能力(要求剧集视频引擎是 2.5 系)。这不是调用错误,别重试;告诉客户换引擎或走别的加长方式。",
   "extend_final": "发起成片续写(**收费**,每轮走视频生成扣费链)。后台串行跑,立即返回会话 id,用 get_extend_final 轮询。\n★调之前**必须**先 quote_extend_final 报价(报价确认按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)(派发前平台按同参整单报价过预算预检,超出硬上限回 402 BUDGET_WOULD_EXCEED、未扣费,那就停下问客户)。\n★续写只是「在成片后面接片段」,不改前面已有的内容;接出来的片段也**不会**自动成为本集成片,满意之后要显式调 apply_extend_final 才生效。\n★403 = 本剧没开(引擎需 2.5 系),别重试。",
   "get_extend_final": "查本集所有续写会话的进度与产物。免费。每条会话回 status(pending/processing/completed/partial/failed)、rounds_completed、final_url(产物直链)、applied(该产物**当前是不是**本集成片)、error_msg。\n★status=processing 时耐心轮询,别重复发起 extend_final(那会再扣一次钱)。",
@@ -125,7 +130,7 @@
   "upload_prop_sheet": "用客户自有图片作为某道具的设定图。自动上传+登记。上传本身免费。\n★【出图后自动检查·按用量后付】道具图落库(AI 出图或上传)后,平台会自动做一次道具外形分析(看图补尺寸提示,账单名「道具外形分析」),灰度阀开时还会自动做一次道具时代审核(结果见 get_props 的 era_audit)。两笔都是小额视觉审核,事先告诉客户;别再手动 audit_prop_era 重复付费。\n★【完成后质检·免费】出完等图落库(轮询对应 get_* 看状态,pending 别重复调),再调 review_assets 审资产层(缺图 / 生成中 / 失败 / 被一致性闸拒收 / 道具时代冲突 / 色彩脚本),findings 原样告诉客户、按 action 修完复审;再按它返回的 agent_qc 亲自逐张看图(像不像档案、是不是同一个人、时代对不对;设定图本身各角度齐不齐、比例与结构对不对;道具与场景图放在剧情里合不合理——对照素材 used_in_shots 那几镜),submit_qc_report 提交质检报告;出镜头图时把它的 review_token 作为 asset_review_token 传给 generate_frames / generate_shot_frame。",
   "get_edit_capabilities": "查视频编辑能力开关(就地编辑 / 区间替换是否可用)。免费。",
   "quote_edit_video_shot": "报价:对某镜做就地编辑/区间替换(Seedance 2.5)要多少点。返回 quote_id。零扣费。本镜须已有视频。",
-  "edit_video_shot": "确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换。可用 model 为本次编辑单独选引擎(与剧引擎可不同):hailuo-3=MiniMax H3 强保真编辑约1/3成本;wan3.0/wan3.0-prime=WAN 3.0 强语义编辑约4折(环境可能跟随指令扩写);H3/WAN 均不支持 start_sec/end_sec 区间(传了会 400),编辑/续写的输入视频在 H3/WAN 上另按秒计费。\n★回执里出现 `edit_instruction_negation_advisory` = 你的指令里有**否定式约束**(「不能采用X」「不要出现X」)。视频模型把名词当正向线索,写「不要 X」往往反而把 X 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),否则同一个毛病会一直复现。已实测:客户写「不能采用参考图举手单脚的静态舞姿」,成片开头的抬臂手势就被参考图那个举手带跑了。\n★收到 **409「本镜是用户上传的实拍素材」** = 这一镜被 upload_shot_footage 登记成了实拍素材镜,不是模型或引擎的问题,换引擎重试无用。两条出路:要以该素材为源做 AI 重绘 → 带 replace_user_footage=true 重发;要恢复成普通 AI 镜 → 先 clear_shot_footage。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完(上一次编辑 / 重生 / 批量出视频),这次编辑没提交、没扣费,quote 已作废。编辑的源是本镜当前视频,在途那条一完成就会换掉它——所以先等它完成、看过结果,再重新 quote 并编辑;**别连发**多条编辑想让它们叠加,每一条都只基于当时的源。若在途那条正是你刚提交的同一次编辑(例如调用超时后重发),直接等它的结果,不必再发。同一次编辑原样重发(指令、参考素材、区间、引擎都一样)不会 409,会挂到在途那条上、不重复扣费。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 regenerate_shot_video 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
+  "edit_video_shot": "确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换。可用 model 为本次编辑单独选引擎(与剧引擎可不同):hailuo-3=MiniMax H3 强保真编辑约1/3成本;wan3.0/wan3.0-prime=WAN 3.0 强语义编辑约4折(环境可能跟随指令扩写);H3/WAN 均不支持 start_sec/end_sec 区间(传了会 400),编辑/续写的输入视频在 H3/WAN 上另按秒计费。\n★参考素材条数按本次实际派发的引擎(model 优先、否则剧引擎)核:Seedance 2.5 = 参考图 30 / 额外参考视频 9(源视频另占 1 段,视频合计 ≤30 秒)/ 参考音频 10;其余引擎 = 9 / 2 / 3(2.0 视频合计 ≤15 秒)。超出直接 400、不扣费,**平台不会替你截断**——指令里的「图片N / 视频N / 音频N」按上传顺序编号,删减后编号要跟着改。官方经验:视频编辑参考图 1~5 张效果最好,6~8 张可试,更多未必更好。\n★回执里出现 `edit_instruction_negation_advisory` = 你的指令里有**否定式约束**(「不能采用X」「不要出现X」)。视频模型把名词当正向线索,写「不要 X」往往反而把 X 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),否则同一个毛病会一直复现。已实测:客户写「不能采用参考图举手单脚的静态舞姿」,成片开头的抬臂手势就被参考图那个举手带跑了。\n★收到 **409「本镜是用户上传的实拍素材」** = 这一镜被 upload_shot_footage 登记成了实拍素材镜,不是模型或引擎的问题,换引擎重试无用。两条出路:要以该素材为源做 AI 重绘 → 带 replace_user_footage=true 重发;要恢复成普通 AI 镜 → 先 clear_shot_footage。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完(上一次编辑 / 重生 / 批量出视频),这次编辑没提交、没扣费,quote 已作废。编辑的源是本镜当前视频,在途那条一完成就会换掉它——所以先等它完成、看过结果,再重新 quote 并编辑;**别连发**多条编辑想让它们叠加,每一条都只基于当时的源。若在途那条正是你刚提交的同一次编辑(例如调用超时后重发),直接等它的结果,不必再发。同一次编辑原样重发(指令、参考素材、区间、引擎都一样)不会 409,会挂到在途那条上、不重复扣费。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 regenerate_shot_video 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
   "get_repaint_capabilities": "查本剧能用哪些视频转绘:repaint(视频重绘)/ reskin(换装重绘)是否开放、单段源片上限 maxSourceSec、长镜头接力最多段数 relayMaxSegments(0=没开,>5 秒的镜不能转绘)。免费。",
   "quote_repaint_shot_video": "报价:对某镜做**视频重绘**(按描述 + 参考图重画人物与服装,保留原片动作)要多少点。返回 quote_id。零扣费。本镜须已有视频。报价只认本镜当前这段视频——之后视频被换(重生/上传/编辑完成),发起会 409,重新报价即可。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。",
   "repaint_shot_video": "确认后对某镜做视频重绘。扣费上限 = 报价的 estimated_points(接力时为整条合计)。\n★参考图:不传 reference_image_url 时自动取本镜角色的(换装)定妆图——**不带参考图人也会被换掉**;auto_reference=false 表示明确不要参考图(只按描述画)。\n★keep_scene 缺省 true:把本镜场景/道具/动作补进描述,只换人与衣服;传 false = 连场景一起重画。\n★control:posebodyface(缺省,保口型,说话镜用它)/ posebody(不带脸,嘴不动)/ depth(按景深,纯色背景易出竖条纹)/ scribble(线稿)。strength 只收 0 或 1。\n★本镜绑了产品文字(需保留商品原文)时会被拒(重绘会重画画面里的字)。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
@@ -133,7 +138,7 @@
   "reskin_shot_video": "确认后对某镜做换装重绘。扣费上限 = 报价的 estimated_points。\n★first_frame_url 是**换好装的首帧**:必须与原片首帧**构图、人物姿势、道具位置逐一对齐**(只换衣服),否则整段会跑偏——实测失败都出在首帧。完成后它会成为本镜正式首帧。只收公网 https 图片(先 upload_image 拿)。\n★prompt 可留空(系统看首帧自动写);写的话别用「制服/军装」这类服装类别词,模型会自行加肩章条纹,直接描述颜色款式。\n★control:posebodyface(缺省,保口型)/ depth。本镜绑了产品文字时会被拒。\n★与 edit_video_shot 的分工:edit 是按指令改画面(换背景/调色/局部改动);重绘/换装重绘是**以本镜现有视频为动作骨架,把人物与服装整体重画**,动作、口型时机、镜头运动跟原片走,音轨贴回原片。\n★**客户自己的视频也能转绘**:先 upload_shot_footage 把它登记成某镜的实拍素材(会抽出首尾帧、回写时长),再对该镜报价/发起即可;转绘结果写回后该镜不再是实拍素材镜。\n★时长:≤5 秒一单(按 5 秒计费);本剧开了长镜头接力(get_repaint_capabilities 的 relayMaxSegments>0)时 5~约14 秒自动切 ≤3 段接力,每段一单、报价是合计;再长先 split_shot。\n★异步:发起返回一条生成记录(接力时是段 1),用 get_repaint_status(storyboard_id, generation_id) 查到 completed/failed;接力进行中会带 relay.segments_done/segments。完成后本镜视频即换成转绘结果;不满意用 restore_repaint_original 切回原片(免费)。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "get_repaint_status": "查一次视频重绘/换装重绘的进度。generation_id 用发起时返回的 id(接力时就是段 1 的 id,返回的是整条链的状态)。免费。\n· status=processing:进行中;接力时带 relay.segments_done/segments。\n· status=completed:本镜视频已换成转绘结果(video_url / local_path);接力完成时带 relay.final_generation_id——**切回原片要用这个 final_generation_id**,不是段 1 的 id。\n· status=completed 但 errorMsg 含「未写回」:任务期间本镜视频被换掉,结果存档在这条记录里、没覆盖本镜。\n· status=failed:errorMsg 是中文原因(接力会说明第几段失败),镜头未改动,已扣的按规则退。",
   "restore_repaint_original": "把某镜从转绘结果切回转绘前的原片(换装重绘连首帧一起恢复)。免费。generation_id = 本镜当前视频对应的那次转绘(接力取 get_repaint_status 的 relay.final_generation_id)。\n★409 = 之后本镜又出过别的视频,不覆盖(保护后来的结果);有视频任务在跑时也别切回,在跑那单会因源片不符被存档(白花钱)。",
-  "quote_regenerate_shot_video": "报价:重生某镜视频要多少点。返回 quote_id。零扣费。\n★**按镜指定视频引擎**:传 model 即只为这一镜这一次重生换引擎(不改剧级 video_engine,其它镜照旧);报价按该引擎计价,quote_id 把引擎钉死,regenerate_shot_video 派发的就是它——要换引擎必须重新报价,生成时再传引擎无效。回执 video_engine = 实际派发的引擎,engine_overridden=true 表示盖过了剧引擎。★所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),不支持则 400 并列出可选引擎——不会悄悄换成别的引擎出片;本镜时长也不能超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),超了 400(厂商会截断)。适用:某镜在本剧引擎上反复失败/被厂商审核拒/镜内自剪,单独换一个引擎试。★同剧混用引擎有画风/身份漂移风险,换完先看这一镜再决定要不要推广;写实真人镜别换 wan3.0/wan3.0-prime(真人脸 720p+ 常被厂商拒)。",
+  "quote_regenerate_shot_video": "报价:重生某镜视频要多少点。返回 quote_id。零扣费。\n★**按镜指定视频引擎**:传 model 即只为这一镜这一次重生换引擎(不改剧级 video_engine,其它镜照旧);报价按该引擎计价,quote_id 把引擎钉死,regenerate_shot_video 派发的就是它——要换引擎必须重新报价,生成时再传引擎无效。回执 video_engine = 实际派发的引擎,engine_overridden=true 表示盖过了剧引擎。\n★**内测·单镜中间关键帧**:回执带 shot_keyframes(只在内测剧)时,mode=keyframes 表示本次会把首帧 + ready 的中间帧(+尾帧)按秒数一起送给 Seedance 2.5(首帧变软约束、秒数误差约 ±1 秒、点数不变);mode=first_frame 时 reason 说明为什么没走(如 strict-continuity = 首帧是上一镜尾帧拷贝,接缝优先)。★所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),不支持则 400 并列出可选引擎——不会悄悄换成别的引擎出片;本镜时长也不能超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),超了 400(厂商会截断)。适用:某镜在本剧引擎上反复失败/被厂商审核拒/镜内自剪,单独换一个引擎试。★同剧混用引擎有画风/身份漂移风险,换完先看这一镜再决定要不要推广;写实真人镜别换 wan3.0/wan3.0-prime(真人脸 720p+ 常被厂商拒)。",
   "regenerate_shot_video": "确认后重生某镜视频(可选新 prompt)。\n★收到 **409「本镜是用户上传的实拍素材」** = 该镜被 upload_shot_footage 登记成实拍素材镜,不是模型问题,换引擎无用;要用 AI 视频覆盖它就带 replace_user_footage=true,要保留素材就别重生。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完,而且它不是按这次的内容发起的(你带了新 prompt / 之后用 update_shot 改过该镜 / 之后换过该镜的首帧或尾帧——重出、上传、补出尾帧都算 / 这次带的帧、参考素材或引擎等参数与那次不同 / 在途的是一次编辑)。prompt 没变也可能是这个 409。这次重生没提交、没扣费,quote 已作废。先等在途那条完成、看过结果,再重新 quote 并重生——否则拿到的视频是旧内容(旧提示词或旧首尾帧)出的,会误以为改动没效果。\n★成功但返回里带 **`reused_in_flight: true`** = 同样的内容已经在生成(重发/双击/批量出视频已派发),这次没有新建、没有新扣费,返回的就是在途那一条,看它的进度即可,不必再发。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 edit_video_shot 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。\n★【镜头图片审查硬闸·免费】本步前必须先调 review_frames:把返回的 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_frames 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
   "split_shot": "把某镜按首尾帧拆成两镜(结构操作)。免费。",
   "trim_shot": "裁剪某镜时长(in_ms/out_ms)。免费;返回后需 rerender_episode 重拼成片。",
@@ -279,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`)));
@@ -1678,6 +1708,9 @@ export function registerProduceTools(server, client) {
     server.tool('edit_video_shot', '确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换。' +
         '可用 model 为本次编辑单独选引擎(与剧引擎可不同):hailuo-3=MiniMax H3 强保真编辑约1/3成本;wan3.0/wan3.0-prime=WAN 3.0 强语义编辑约4折(环境可能跟随指令扩写);' +
         'H3/WAN 均不支持 start_sec/end_sec 区间(传了会 400),编辑/续写的输入视频在 H3/WAN 上另按秒计费。' +
+        '\n★参考素材条数按本次实际派发的引擎(model 优先、否则剧引擎)核:Seedance 2.5 = 参考图 30 / 额外参考视频 9(源视频另占 1 段,视频合计 ≤30 秒)/ 参考音频 10;' +
+        '其余引擎 = 9 / 2 / 3(2.0 视频合计 ≤15 秒)。超出直接 400、不扣费,**平台不会替你截断**——指令里的「图片N / 视频N / 音频N」按上传顺序编号,删减后编号要跟着改。' +
+        '官方经验:视频编辑参考图 1~5 张效果最好,6~8 张可试,更多未必更好。' +
         '\n★回执里出现 `edit_instruction_negation_advisory` = 你的指令里有**否定式约束**(「不能采用X」「不要出现X」)。' +
         '视频模型把名词当正向线索,写「不要 X」往往反而把 X 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。' +
         '这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),' +
@@ -1694,9 +1727,9 @@ export function registerProduceTools(server, client) {
         quote_id: z.string().describe('来自 quote_edit_video_shot'),
         instruction: z.string().describe('编辑指令(如"把背景换成夜晚")'),
         model: z.enum(VIDEO_ENGINES).optional().describe('本次编辑的引擎(缺省=跟随剧 video_engine);hailuo-3/wan3.0/wan3.0-prime 不支持区间编辑;kling-4.0 不支持编辑'),
-        reference_image_urls: z.array(z.string()).max(9).optional().describe('参考图 URL(先 upload_image 拿)'),
-        reference_video_urls: z.array(z.string()).max(2).optional(),
-        reference_audio_urls: z.array(z.string()).max(3).optional(),
+        reference_image_urls: z.array(z.string()).max(30).optional().describe('参考图 URL(先 upload_image 拿);Seedance 2.5 最多 30 张,其余引擎最多 9 张'),
+        reference_video_urls: z.array(z.string()).max(9).optional().describe('额外参考视频 URL;源视频另占 1 段。Seedance 2.5 最多 9 段(含源视频总长 ≤30 秒),其余引擎最多 2 段'),
+        reference_audio_urls: z.array(z.string()).max(10).optional().describe('参考音频 URL;Seedance 2.5 最多 10 段,其余引擎最多 3 段'),
         start_sec: z.number().optional().describe('区间替换起点秒'),
         end_sec: z.number().optional().describe('区间替换终点秒'),
         replace_user_footage: z.boolean().optional().describe('本镜是实拍素材镜(upload_shot_footage 传过)时,显式允许以它为源做编辑并用 AI 产物覆盖它。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.251",
-    "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.251 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",
@@ -14851,7 +14891,7 @@
       "post": {
         "operationId": "edit_video_shot",
         "summary": "确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换",
-        "description": "确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换。可用 model 为本次编辑单独选引擎(与剧引擎可不同):hailuo-3=MiniMax H3 强保真编辑约1/3成本;wan3.0/wan3.0-prime=WAN 3.0 强语义编辑约4折(环境可能跟随指令扩写);H3/WAN 均不支持 start_sec/end_sec 区间(传了会 400),编辑/续写的输入视频在 H3/WAN 上另按秒计费。\n★回执里出现 `edit_instruction_negation_advisory` = 你的指令里有**否定式约束**(「不能采用X」「不要出现X」)。视频模型把名词当正向线索,写「不要 X」往往反而把 X 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),否则同一个毛病会一直复现。已实测:客户写「不能采用参考图举手单脚的静态舞姿」,成片开头的抬臂手势就被参考图那个举手带跑了。\n★收到 **409「本镜是用户上传的实拍素材」** = 这一镜被 upload_shot_footage 登记成了实拍素材镜,不是模型或引擎的问题,换引擎重试无用。两条出路:要以该素材为源做 AI 重绘 → 带 replace_user_footage=true 重发;要恢复成普通 AI 镜 → 先 clear_shot_footage。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完(上一次编辑 / 重生 / 批量出视频),这次编辑没提交、没扣费,quote 已作废。编辑的源是本镜当前视频,在途那条一完成就会换掉它——所以先等它完成、看过结果,再重新 quote 并编辑;**别连发**多条编辑想让它们叠加,每一条都只基于当时的源。若在途那条正是你刚提交的同一次编辑(例如调用超时后重发),直接等它的结果,不必再发。同一次编辑原样重发(指令、参考素材、区间、引擎都一样)不会 409,会挂到在途那条上、不重复扣费。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 regenerate_shot_video 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
+        "description": "确认后就地编辑某镜视频:按 instruction 改,可带参考图/视频/音频,或用 start_sec/end_sec 做区间替换。可用 model 为本次编辑单独选引擎(与剧引擎可不同):hailuo-3=MiniMax H3 强保真编辑约1/3成本;wan3.0/wan3.0-prime=WAN 3.0 强语义编辑约4折(环境可能跟随指令扩写);H3/WAN 均不支持 start_sec/end_sec 区间(传了会 400),编辑/续写的输入视频在 H3/WAN 上另按秒计费。\n★参考素材条数按本次实际派发的引擎(model 优先、否则剧引擎)核:Seedance 2.5 = 参考图 30 / 额外参考视频 9(源视频另占 1 段,视频合计 ≤30 秒)/ 参考音频 10;其余引擎 = 9 / 2 / 3(2.0 视频合计 ≤15 秒)。超出直接 400、不扣费,**平台不会替你截断**——指令里的「图片N / 视频N / 音频N」按上传顺序编号,删减后编号要跟着改。官方经验:视频编辑参考图 1~5 张效果最好,6~8 张可试,更多未必更好。\n★回执里出现 `edit_instruction_negation_advisory` = 你的指令里有**否定式约束**(「不能采用X」「不要出现X」)。视频模型把名词当正向线索,写「不要 X」往往反而把 X 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),否则同一个毛病会一直复现。已实测:客户写「不能采用参考图举手单脚的静态舞姿」,成片开头的抬臂手势就被参考图那个举手带跑了。\n★收到 **409「本镜是用户上传的实拍素材」** = 这一镜被 upload_shot_footage 登记成了实拍素材镜,不是模型或引擎的问题,换引擎重试无用。两条出路:要以该素材为源做 AI 重绘 → 带 replace_user_footage=true 重发;要恢复成普通 AI 镜 → 先 clear_shot_footage。\n★收到 **409 + `in_flight_generation_id`** = 这一镜还有一条生成没跑完(上一次编辑 / 重生 / 批量出视频),这次编辑没提交、没扣费,quote 已作废。编辑的源是本镜当前视频,在途那条一完成就会换掉它——所以先等它完成、看过结果,再重新 quote 并编辑;**别连发**多条编辑想让它们叠加,每一条都只基于当时的源。若在途那条正是你刚提交的同一次编辑(例如调用超时后重发),直接等它的结果,不必再发。同一次编辑原样重发(指令、参考素材、区间、引擎都一样)不会 409,会挂到在途那条上、不重复扣费。\n★一键出片托管环节:同一镜重出视频最多 3 次(与 regenerate_shot_video 合计),到上限回 **409 AUTOPILOT_SHOT_REGEN_LIMIT**(未派发、未扣费,quote 未消耗)——别换个工具绕,停下问客户:客户同意再出就照常报价、生成时带 customer_approved_more_regens:true(再给一份上限);客户接受现状就往下走,下一步收费调用带 acknowledge_review:true 记下确认。专业模式与客户把控的环节不受这个上限约束。⚠️ 批量报价确认流程:先调对应的 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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。\n★【完成后质检·免费】出完等它落库(get_storyboards 看 video_status / get_pipeline_status),再调 review_videos 审视频与配音层(缺视频 / 旧帧出的视频 / 片尾硬切 / 意外人声 / 配音缺失 / 音色未分配 / 原声声线过期),修完复审;再按 agent_qc 亲自逐镜看视频、听配音(动作到位、不变脸、台词念全、嗓音对),submit_qc_report 提交;compose_episode 要带它的 review_token。",
         "tags": [
           "storyboards"
         ],
@@ -14896,21 +14936,21 @@
                     "items": {
                       "type": "string"
                     },
-                    "maxItems": 9
+                    "maxItems": 30
                   },
                   "reference_video_urls": {
                     "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "maxItems": 2
+                    "maxItems": 9
                   },
                   "reference_audio_urls": {
                     "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "maxItems": 3
+                    "maxItems": 10
                   },
                   "start_sec": {
                     "type": "number"
@@ -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.251",
+  "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.251",
+  "version": "0.1.256",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.251",
+      "version": "0.1.256",
       "transport": {
         "type": "stdio"
       },