@starreel/mcp 0.1.248 → 0.1.252

package/SKILL.md

@@ -1534,14 +1534,27 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   (LLM, **billed**; `dry_run:true` to preview) adds 1–3 "at second t the frame
   shows …" targets between a shot's first and last frame — wind-up, contact,
   landing — so the video passes those beats instead of skipping them. Only
-  shots on `seedance-2.5` (it follows keyframe timing within about ±1 s), ≥5 s,
+  shots on `seedance-2.5` (it follows keyframe timing within about ±1 s) or
+  `kling-4.0` (closed beta; keyframes are kept in order but their timing is not
+  honored, and the first frame stays hard-pinned), ≥5 s,
   marked state-change or key moment. Fills empty shots only. Read with
   `get_shot_keyframes` (returns the allowed window: t in [2, duration−1],
   ≥2 s apart, max 3) or the `keyframes` field of `get_storyboards`; overwrite
   with `set_shot_keyframes`. Prompts must describe a visible pose — no
   "about to / starting to" wording and no "no X" negations (both rejected).
-  A 400 "未开启" means the project is not in the beta. This stage only plans;
-  rendering the keyframes and feeding them to the video model come later.
+  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.
+  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
+  price). Shots whose first frame is a copy of the previous shot's last frame keep
+  first-frame mode (`reason: strict-continuity`) so the seam stays exact.
 - **Era contract**: `set_era_contract` / `get_era_contract` — see the project
   settings tier above. Non-contemporary projects must set this before frames.
 - **Lengthen a finished cut**: `quote_extend_final` (free, quote first) →

package/dist/i18n/tools.en.json

@@ -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.",

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 重拼成片。",

package/dist/tools/guide-data.js

@@ -611,6 +611,23 @@ export const MODEL_GUIDE = {
             best_for: '风格化项目赶交付',
             avoid_for: '同 wan3.0;不赶时间就用 wan3.0',
         },
+        {
+            id: 'kling-4.0', name: '可灵 4.0(内测·按剧开放)',
+            price: '720p/1080p 约 0.66×/1×(以 seedance-2.5 720p 为 1×,报价 = 实扣已实测,实价以报价为准);无 480p(按 720p 计);单镜 3~30 秒',
+            strengths: [
+                '大场面动作强:坠击、爆裂一类镜的过程与终态完整(单次样本)',
+                '能保持夸张造型(如能量化的巨拳),带立体声',
+                '原生支持首帧 + 中间帧 + 尾帧:中间关键帧近乎像素级还原(整帧相似度 0.95~0.97)',
+            ],
+            weaknesses: [
+                '内测:只在开放名单内的剧可选,未开放的剧选它会 400',
+                '不守秒数:中间帧落在哪一秒不受控制,只保证顺序',
+                '只做图生视频:不进场景组、不续拍、不收参考视频 / 声画锚,单镜编辑与单组重出不可用',
+                '单次样本里出现过人物中途消失;关键帧之间机位不一致会镜内硬切',
+            ],
+            best_for: '动作 / 特效大场面的单镜,配合首帧起势 + 中间关键帧钉住关键一拍',
+            avoid_for: '要组视频 / 续拍 / 编辑的剧;要按秒精确对点的镜(用 seedance-2.5)',
+        },
     ],
     video_decision: [
         '① 先定「是不是写实真人」:是 → seedance-2.5 或降本 hailuo-3(' + MODEL_AVAILABILITY_NOTE + ';菜单里不可用的别推荐);绝不选 wan3.0 / wan3.0-prime。',

package/dist/tools/produce.js

@@ -345,7 +345,8 @@ const FRAME_TYPE_ARG = z.enum(['first_frame', 'last_frame', 'both']);
 const ASPECT_RATIOS = ['9:16', '16:9', '1:1', '4:5', '4:3', '21:9'];
 const VIDEO_RESOLUTIONS = ['480p', '720p', '1080p', '4k'];
 // 剧级视频引擎(与后端 video-engine-policy 白名单同源;短 id,后端归一化)。
-const VIDEO_ENGINES = ['seedance-2.5', 'hailuo-3', 'wan3.0', 'wan3.0-prime'];
+// kling-4.0 为内测引擎:后端按剧灰度(KLING_VIDEO_DRAMAS),未开放的剧传它会 400——那不是调用错误,换回其它引擎即可。
+const VIDEO_ENGINES = ['seedance-2.5', 'hailuo-3', 'wan3.0', 'wan3.0-prime', 'kling-4.0'];
 // 「项目设定页」通用视觉/音频/字幕/转场设定 —— create_drama 与 update_project_settings 共用。
 // 后端内部 PUT /dramas 已接受写库,facade 白名单 Wave3 已放行(produce-create-fields.ts)。
 // 不含内部产线/成本开关(strict_mode/best_of_n/shoppable/budget_points 等,需产品决策)。
@@ -368,7 +369,7 @@ const PROJECT_SETTINGS_FIELDS = {
         'gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·31点)/' +
         'doubao-seedream-5-0-260128(Seedream 5.0)。建剧即定、整剧统一;generate_frames 可临时覆盖某次出图。★各模型实测优劣(一次过率/手部结构/安全拒绝率/画风稳定度)与选型步骤见 get_capabilities_guide(section=model_guide)'),
     // drama 级视频引擎(整剧统一,单镜/批量/场景组/重生全走它;按镜例外入口:quote_videos 的 shot_engines / quote_regenerate_shot_video 的 model / edit_video_shot 的 model)
-    video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3(' + MODEL_AVAILABILITY_NOTE + ');风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒):' +
+    video_engine: z.enum(VIDEO_ENGINES).optional().describe('视频引擎(★drama级·整剧统一·AI必须按剧选型主动引导:写实真人剧→seedance-2.5 或降本 hailuo-3(' + MODEL_AVAILABILITY_NOTE + ');风格化/动画/3D卡通/空镜/产品镜→wan3.0(赶交付 wan3.0-prime);写实真人剧绝不选 wan——720p+ 真人脸被厂商审核一致拒;kling-4.0 为内测引擎,只在开放名单内的剧可选,未开放回 400,动作大场面单镜可试):' +
         'seedance-2.5(动漫/风格化剧默认·写实真人剧在该题材可用时也默认它·全能力:帧链/场景组/就地编辑/延长/参考图锚·价格基准 720p=1×) / ' +
         '★不传时平台按画风兜底:动漫/风格化→seedance-2.5;写实/未定画风→seedance-2.5 写实开关开着用它,否则 hailuo-3——这只是兜底盖章,不查菜单的题材可用性,所以按 get_production_menu 选定后要显式传。' +
         'hailuo-3(MiniMax H3:约1/3成本 720p 约0.33×·原生对白与音效·支持2K·单镜约6分钟·支持就地编辑(强保真)与成片续写·关键帧组/时间戳区间暂不可用;编辑/续写输入视频另按秒计费) / ' +
@@ -1327,7 +1328,7 @@ export function registerProduceTools(server, client) {
         + '\n★只规划视频引擎为 seedance-2.5 的镜(只有它按秒对齐关键帧,误差约 ±1 秒);时长 ≥5 秒、标为状态变化或关键镜的才会规划。'
         + '\n★只填**空着**的镜:已经有中间关键帧的(含客户自己写的)一律不动。dry_run:true 只返回规划不写库,先给客户看。'
         + '\n★结果用 get_storyboards 每镜的 keyframes 字段读;要改用 set_shot_keyframes。'
-        + '\n★回 400「本剧未开启」= 本剧不在内测名单,不是调用错误,别重试。本期只规划、不出图,出中间帧与送进视频是后续功能。', {
+        + '\n★回 400「本剧未开启」= 本剧不在内测名单,不是调用错误,别重试。规划完用 quote_shot_keyframes → generate_shot_keyframes 出中间帧图。', {
         episode_id: z.number().int().positive(),
         dry_run: z.boolean().optional().describe('true = 只返回规划结果、不写库'),
     }, async ({ episode_id, dry_run }) => jsonResult(await client.producePost(`/episodes/${episode_id}/keyframes/plan`, { dry_run: dry_run === true })));
@@ -1346,6 +1347,25 @@ 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),'
+        + '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「本剧未开启」= 不在内测名单,别重试。', {
+        storyboard_id: z.number().int().positive(),
+        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 描述的那一刻;'
+        + '不改本镜首尾帧、不把已有视频标陈旧。异步:立即返回 dispatched,用 get_shot_keyframes 轮询每张 status——'
+        + 'ready 才会在重出本镜视频时送进 Seedance 2.5;framing_mismatch = 取景与首帧对不上(不送),改 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'),
+        keyframe_ids: z.array(z.number().int().positive()).max(3).optional().describe('与报价时一致'),
+        image_model: z.string().optional().describe('与报价时一致'),
+        ...REVIEW_ARGS,
+        ...ASSET_REVIEW_ARG,
+    }, async ({ storyboard_id, quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/keyframes/generate`, { quote_id, keyframe_ids, image_model, review_token, asset_review_token, acknowledge_review, auto_acknowledge })));
     server.tool('quote_extend_final', '★成片续写**报价**(免费·无副作用):在已有成片后面再接几轮 AI 生成的片段,把片子拉长。'
         + '回 rounds(轮数)/duration_per_round(每轮秒数)/max_rounds(上限)/estimated_points(预估点数)。'
         + '\n★**必须先 quote_extend_final 报价,再调 extend_final**' + MODE_DECIDES('报价确认') + '(派发前平台按同参整单报价过预算预检,超出硬上限回 402 BUDGET_WOULD_EXCEED、未扣费,那就停下问客户)' + '——每轮都真扣厂商的钱。'
@@ -1658,6 +1678,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 演出来——被否定的那个动作/物件恰恰是模型先验里最显眼的。' +
         '这不是拦截,任务已照常提交;但**下一轮改指令时务必删掉否定句,改成正向描述**(把该做什么写具体:起手动作、手的位置、每一拍的时值),' +
@@ -1673,10 +1696,10 @@ export function registerProduceTools(server, client) {
         storyboard_id: z.number().int().positive(),
         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 不支持区间编辑'),
-        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(),
+        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(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 产物覆盖它。' +
@@ -1744,6 +1767,8 @@ export function registerProduceTools(server, client) {
         '\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(厂商会截断)。' +
         '适用:某镜在本剧引擎上反复失败/被厂商审核拒/镜内自剪,单独换一个引擎试。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.248",
-    "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.248 tool surface (operationIds match MCP tool names 1:1)."
+    "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)."
   },
   "servers": [
     {
@@ -1261,7 +1261,8 @@
                       "seedance-2.5",
                       "hailuo-3",
                       "wan3.0",
-                      "wan3.0-prime"
+                      "wan3.0-prime",
+                      "kling-4.0"
                     ]
                   },
                   "cinematography_prompt": {
@@ -1643,7 +1644,8 @@
                       "seedance-2.5",
                       "hailuo-3",
                       "wan3.0",
-                      "wan3.0-prime"
+                      "wan3.0-prime",
+                      "kling-4.0"
                     ]
                   },
                   "cinematography_prompt": {
@@ -8138,7 +8140,7 @@
       "post": {
         "operationId": "plan_shot_keyframes",
         "summary": "★**内测**·规划**单镜中间关键帧**：给动作复杂的镜头在首帧与尾帧之间加 1~3 个「第 t 秒该是什么画面」的目标(蓄力、命中、落地等节点),让视频动作按节点走、不跳过过程",
-        "description": "★**内测**·规划**单镜中间关键帧**：给动作复杂的镜头在首帧与尾帧之间加 1~3 个「第 t 秒该是什么画面」的目标(蓄力、命中、落地等节点),让视频动作按节点走、不跳过过程。**要花钱**(走 LLM,文本按 token 后付)。\n★只规划视频引擎为 seedance-2.5 的镜(只有它按秒对齐关键帧,误差约 ±1 秒);时长 ≥5 秒、标为状态变化或关键镜的才会规划。\n★只填**空着**的镜:已经有中间关键帧的(含客户自己写的)一律不动。dry_run:true 只返回规划不写库,先给客户看。\n★结果用 get_storyboards 每镜的 keyframes 字段读;要改用 set_shot_keyframes。\n★回 400「本剧未开启」= 本剧不在内测名单,不是调用错误,别重试。本期只规划、不出图,出中间帧与送进视频是后续功能。",
+        "description": "★**内测**·规划**单镜中间关键帧**：给动作复杂的镜头在首帧与尾帧之间加 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 出中间帧图。",
         "tags": [
           "episodes"
         ],
@@ -9926,7 +9928,8 @@
                       "seedance-2.5",
                       "hailuo-3",
                       "wan3.0",
-                      "wan3.0-prime"
+                      "wan3.0-prime",
+                      "kling-4.0"
                     ]
                   }
                 },
@@ -11619,7 +11622,8 @@
                         "seedance-2.5",
                         "hailuo-3",
                         "wan3.0",
-                        "wan3.0-prime"
+                        "wan3.0-prime",
+                        "kling-4.0"
                       ]
                     },
                     "propertyNames": {
@@ -14255,7 +14259,8 @@
                           "seedance-2.5",
                           "hailuo-3",
                           "wan3.0",
-                          "wan3.0-prime"
+                          "wan3.0-prime",
+                          "kling-4.0"
                         ]
                       },
                       {
@@ -14846,7 +14851,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"
         ],
@@ -14882,7 +14887,8 @@
                       "seedance-2.5",
                       "hailuo-3",
                       "wan3.0",
-                      "wan3.0-prime"
+                      "wan3.0-prime",
+                      "kling-4.0"
                     ]
                   },
                   "reference_image_urls": {
@@ -14890,21 +14896,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"
@@ -15981,6 +15987,165 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/keyframes/generate": {
+      "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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
+        "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": {
+                  "quote_id": {
+                    "type": "string",
+                    "description": "来自 quote_shot_keyframes"
+                  },
+                  "keyframe_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0
+                    },
+                    "maxItems": 3
+                  },
+                  "image_model": {
+                    "type": "string"
+                  },
+                  "review_token": {
+                    "type": "string"
+                  },
+                  "asset_review_token": {
+                    "type": "string"
+                  },
+                  "acknowledge_review": {
+                    "type": "boolean"
+                  },
+                  "auto_acknowledge": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "quote_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}/keyframes/quote": {
+      "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「本剧未开启」= 不在内测名单,别重试。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyframe_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0
+                    },
+                    "maxItems": 3
+                  },
+                  "image_model": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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}/lipsync": {
       "post": {
         "operationId": "lipsync_shot",
@@ -16498,7 +16663,7 @@
       "post": {
         "operationId": "quote_regenerate_shot_video",
         "summary": "报价:重生某镜视频要多少点",
-        "description": "报价:重生某镜视频要多少点。返回 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+ 常被厂商拒)。",
+        "description": "报价:重生某镜视频要多少点。返回 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+ 常被厂商拒)。",
         "tags": [
           "storyboards"
         ],
@@ -16526,7 +16691,8 @@
                       "seedance-2.5",
                       "hailuo-3",
                       "wan3.0",
-                      "wan3.0-prime"
+                      "wan3.0-prime",
+                      "kling-4.0"
                     ]
                   }
                 }

package/package.json

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