@starreel/mcp 0.1.213 → 0.1.215

package/SKILL.md

@@ -543,6 +543,20 @@ content that will be rejected.
    `review_frames` flags the two actionable states as `seam_unchained` / `seam_broken`
    (warnings — they do not block `generate_videos`, but this is the cheapest point to fix
    them: the video is generated from the first frame).
+   `review_frames` / `generate_videos` may also return `unchained_seam_advisory`
+   (`quote_videos`: an `advisories` entry with `code: "unchained_seams"`) — the seams the
+   `chain_frames` plan would join but that are not joined yet, each with a `status`:
+   `no_stamp` (never joined), `pending` (a join was dispatched but has not landed / no verdict
+   yet), `stale_anchor` (the previous join's anchor is gone — the upstream last frame was
+   regenerated after joining, so the seam must be re-joined), `join_failed` (the last joining
+   regeneration was rejected / failed / superseded and never landed), `audit_failed` (it landed
+   but the continuity audit judged it discontinuous — see `seam_failed_dims`),
+   `first_frame_regenerated` (the next shot's first frame was regenerated after the join was
+   reviewed, bypassing the joining path), `not_linked` (unchained per the planner, cause not
+   evidenced). Re-join all of them per the plan. `video_locked` lists seams whose
+   next shot already has a video: `chain_frames` leaves those alone, so fix them per shot
+   (`chain_shot_from_prev` / `chain_shot_from`, then `regenerate_shot_video`, quote first).
+   Advisory only — it never changes `review_token`, quotes or status codes.
    Joined seams can still jump when the same subject sits on opposite sides of the frame,
    moves in opposite directions, or the shot size leaps several steps. Optional, before videos:
    `audit_seam_directions` (`dry_run` first — quote, billed by text tokens; advisory,
@@ -1482,6 +1496,17 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   `voice_gain_db` for the TTS dialogue + narration track); one music section's level, fades,
   where in the track it starts (`track_offset_ms`) and how late after its first shot it comes in
   (`start_shift_ms`) via `list_bgm_cues` → `update_bgm_cue`. Don't download the cut to re-mix it locally.
+- **Theme song with vocals** (free; settings only — `compose_episode` again): `get_theme_songs` →
+  `set_theme_songs` attaches an opening / ending / insert song to an episode (the customer's own
+  upload via `upload-url` kind=audio, or a `track_id`). Give the song's backing track as
+  `instrumental_url` and dialogue lines automatically swap the vocal for the backing track;
+  without it the whole song ducks by `duck_db` (default −18 dB) while someone speaks. Background
+  music yields inside the song's range. `enabled=false` = the drama isn't switched on yet.
+- **Poem / lyric text cards** (free; `compose_episode` again): `get_shot_verse_cards` →
+  `set_shot_verse_cards` — up to 6 vertical or horizontal cards per shot (left / right / center,
+  own fade-in/out and start time), a full-screen black closing card (`backdrop: "black"`) and
+  scrolling end credits (`motion: "scroll_up"`). Cards stay out of the dialogue-subtitle band.
+  Use only the text the customer supplied. Don't overlay text on a downloaded cut.
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
 - **What did this drama cost?** `get_drama_bill` — per kind `charged` / `refunded`

package/dist/i18n/tools.en.json

@@ -42,7 +42,7 @@
   "get_health_report": "(★Recommended · free diagnosis) Read storyboards and output a health report: overlong duration / insufficient motif coverage / problematic shots. Read-only, free. Check before image generation; identify issues, fix first, and avoid discovering them only after the film is produced.",
   "review_script": "【Hard Gate ① · Free】Review the AI rewritten script: dialogue line length, completeness of emotional turns, opening hook, final-scene cliffhanger. ★Before extract_assets and generate_storyboards, this tool must run first—character profiles and storyboards are derived from the rewritten script; issues in the script will be amplified layer by layer into character sheets / image generation / video generation, and discovering them at final cut means redoing the whole episode. Tell the client each item in findings one by one, fix by action (use edit_rewritten_script for script edits), then re-review and proceed with the review_token.\n★【Agent manual QC · Free】The returned agent_qc contains this-layer checklist and the episode materials to inspect (materials, each with a ref; images/videos include links). The platform only judges “exists / present / rejected”; “looks alike / correct / good” must be checked by you: download and open images, sample at least beginning/middle/end frames for videos, read text through with tools. Answer each checklist item (ok / issue / na; for issue, specify which item and what problem), list every inspected ref in inspected, and call submit_qc_report to submit; relay the QC conclusion to the client verbatim. If agent_qc.required=true and no report is submitted, this review_token cannot enter the next step (400 agent_qc_required); a problematic report blocks by default just like a platform error.\n★【Script evaluation and suggestions】materials contains the client original script (script:original) and the rewritten script (script): first evaluate the client’s script itself (mainline, motivation, conflict, pacing, plot holes, filmability), then check the rewritten script; for each issue, provide concrete fixes in submit_qc_report suggestions (if wording can be directly changed, provide before/after). After submission, tell the client the evaluation and suggestions item by item and let the client choose: adopt some / execute all directly / continue without changes (which path to take follows the execution mode: professional mode / unconfirmed plan / this stage controlled by client → tell the client and proceed only after client approval; do not decide for the client; if this stage is autopiloted → do not ask the client, execute according to get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log); autopiloted stages by default execute only priority=must items that do not change the client’s original dialogue; all others go into the delivery report. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "review_storyboards": "【Hard gate ② · free】Review storyboards: forbidden terms (will be rejected by vendors and waste credits), shot duration distribution, repeated adjacent composition, character blocking drift in the same scene, emotional curve peaks/valleys, key-shot markers. ★Must run this tool before generate_frames—storyboard issues become a whole episode of wasted images once generated and cannot be fixed shot by shot. Fix per findings.action using update_shot/split_shot, then review again. ★A finding with code=forbidden_term includes `terms` (specific matched terms, e.g. \"background music\", \"strong light\") and `shots` (shot numbers); use those two to update_shot and remove them, no need to guess word by word. ★Forbidden terms are judged with **negative semantics**: writing \"no background music\" or \"do not add music\" is not a violation (it is obeying the constraint), so no edit is needed. ★\"Action overload\" in warnings (action_overload, advisory only, non-blocking): one shot contains more independent actions than its duration can support; before video generation, use split_shot to split it or delete actions—slow motion/dissolves cannot rescue it after final cut. Ignore if multiple people each do one thing or it is a naturally continuous action chain.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
-  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion. ★When there are adjacent shots, the response also carries seam_direction_advisory (advisory, does not affect review_token): existing results of the adjacent-shot direction check (subject side jump/reversed motion/shot-size jump); seams not yet observed need audit_seam_directions dry_run for a quote first, and run only after the client agrees.",
+  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion. ★When there are adjacent shots, the response also carries seam_direction_advisory (advisory, does not affect review_token): existing results of the adjacent-shot direction check (subject side jump/reversed motion/shot-size jump); seams not yet observed need audit_seam_directions dry_run for a quote first, and run only after the client agrees. ★The response may carry an **unchained-seam hint** (does not affect review_token / quote / status codes): review_frames and generate_videos return unchained_seam_advisory; quote_videos returns an advisories entry with code=unchained_seams. seams lists adjacent seams (from_shot→to_shot) that chain_frames would chain but that are not chained yet: status=no_stamp (never chained) / pending (a chaining was dispatched but has not landed, or its audit has no verdict yet) / stale_anchor (the previous chaining anchor is no longer valid: the upstream shot's last frame was regenerated after chaining, so the seam must be re-chained) / join_failed (the last chaining regeneration was rejected / failed / superseded and never landed) / audit_failed (the chaining landed but the continuity audit judged it discontinuous — see seam_failed_dims in get_storyboards) / first_frame_regenerated (the downstream first frame was regenerated after the seam was reviewed, bypassing the chaining path, so the old chaining no longer counts) / not_linked (the planner judges the seam unchained but the cause is not evidenced); re-chain all of them per the plan; video_locked lists the same kind of seam where the downstream shot already has a video — chain_frames will not touch those, so fix them per shot with chain_shot_from_prev / chain_shot_from and then regenerate_shot_video (quote first). If seams is non-empty before generating videos, run chain_frames(dry_run:true) first, tell the customer the plan and price, execute after they agree, then re-run review_frames.",
   "review_assets": "【Asset-layer hard gate · free】Review character appearance images, scene images, and prop images used **on screen** in this episode—coverage and quality: on-screen character missing character sheet / missing reference image / still generating / generation failed / reference image rejected by consistency gate (hint includes rejection reason); scene missing empty-scene base plate; prop referenced by storyboard missing prop image / rejected; prop image conflicts with this shot's era/form; missing color script (warning). ★Call once after producing character sheets, reference images, scene images, and prop images; must review before generate_frames / generate_shot_frame—pass the returned review_token as **asset_review_token**, together with the storyboard-layer review_token (both are required). Only checks the assets themselves: generating shot images later will not invalidate it; changing character sheets / scene images / prop images will invalidate it, just review again (free, seconds). Explain findings to the customer one by one (code=issue type, names=which character/scene/prop, shots=affected shot numbers, action=which tool to call to fix).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★★【Pre-compose checks · after review_videos passes, before compose_episode】Don't hunt for problems by repeatedly exporting the whole cut and trying transitions by hand — per-shot and seam problems have dedicated tools; run them in order before stitching: ① portraits / turnarounds / scene images / shot frames were changed in this episode → first get_stale_portrait_frames(episode_id, free) to see which shots' in-use frames are still based on old assets; for shots where it is unclear which version to use, get_asset_versions(storyboard_id, free) shows each shot's versions and dependencies (unknown means insufficient evidence, not stale; regenerating is paid, so give the list to the customer and let them decide); ② scan_intra_shot_cuts(episode_id, free) finds shots where the vendor hard-cut inside a single shot; ③ per shot, recommend_trim_window(storyboard_id, free) shows a frozen tail and the effective action window (shots inside a scene group return applicable=false — skip them); apply a recommendation with trim_shot (free); ④ audit_seams(episode_id) checks editing continuity at seams between adjacent shots: by default dry_run only lists what would be audited (free); actually running it is billed by real text-token usage — tell the customer, and only after they explicitly accept pass dry_run:false + confirm_usage_billing:true; read the result from seam_review in get_storyboards; ⑤ then compose_episode. If the final cut shows jump cuts / dragging tails / seams that don't match, go back to these tools to locate the shots and fix only those — don't keep re-exporting the whole cut by trial and error. These checks are advisory, not gates; trimming and seam audits don't invalidate the review_videos token. The response's pre_compose_checks carries the same list in structured form (tool/scope/when/cost per item).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★If the response includes post_production_advisory = narrative-required effects that the script marks as post-production are still unhandled (the platform will not composite them): tell the client verbatim and use get_post_production_checklist to see the list. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "submit_qc_report": "Submit the QC report made by you (agent) after personally inspecting materials. Free. First call the corresponding review_* layer (script / storyboards / assets / frames / videos), open each returned agent_qc material in materials, answer every checklist item, then call this tool. ★The platform only verifies the report is **complete**, not whether your conclusions are correct: every checklist id must be answered (ok / issue / na; issue must include note explaining which item has what problem); every ref in materials must be listed in inspected (omit one and it is rejected with the missing refs named); if there are issues, set verdict=issues and list them in issues; reporting pass when issues exist will be rejected. ★Do not go through the motions: listing something in inspected without opening it means you signed off for the customer—wasted output will still be charged. ★When verdict=issues, this token cannot proceed to the next step by default: explain the problems to the customer, fix, then review + QC again; only if the customer is clearly informed and insists on proceeding as-is should the next step include acknowledge_review:true. ★suggestions (change suggestions): required at script layer when agent_qc.suggestions_required=true and issues were reported; optional for other layers. Each item includes problem + proposal; if text can be directly changed, also provide before/after; the response assigns each suggestion an id (s1…). Explain suggestions to the customer; the customer chooses accept some / execute all directly / proceed without changes (which route; autopilot = only execute priority=must suggestions that do not change the customer's original lines per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, recorded by the platform in get_autopilot_log). If content changes after the review, the report will be rejected; review again and QC against the new agent_qc.",
@@ -55,8 +55,8 @@
   "generate_frames": "Batch-generate frames after confirmation: backend async. Poll with get_storyboards; done when first_frame_image/last_frame_image is filled shot by shot. ★Image generation is slow—tens of seconds to minutes per image (especially HD models); a full episode may take 10+ minutes. When polling, check frame_status: **pending=still generating (keep waiting patiently; do not treat as failure; do not call generate_frames again; duplicate triggers=wasted credits)**, ready=done, failed=only this is real failure. Do not decide generation failed or retry just because “it still has not appeared after waiting a while”. Frames must be generated before video, otherwise video degrades into images with no consistency anchors. ★**Before generating frames, prepare both anchors**: character sheets (generate_portraits_and_sheets, anchors people) and empty scene baseplates (generate_scene_images, anchors scenes). Missing baseplates will not block you, but the first shot of each scene will have no background anchor (the platform fallback fill only benefits later shots in the same scene), so the background starts drifting from the first shot. Use the generate_scene_images step in get_pipeline_status to verify completed/total. frame_type must match what quote_frames used (default first_frame). ★This is **batch fill-missing-frames**: it only generates images for shots “missing that frame”; shots that already have first frames are skipped—this is normal design, not “the system refusing to regenerate”. To **regenerate/redraw an existing frame for one shot** (e.g. after changing a character sheet and wanting the new image to take effect), use generate_shot_frame (single-shot regeneration with platform identity anchor), not this tool, and definitely not a self-made image via upload_shot_frame. ★**This tool generates only first frames by default; framing is a two-pass process**: after first frames finish, you must call the free tail_frame_plan once—it tells you, using the platform’s own criteria, which shots need independent tail frames (end state ≠ start state: large camera move/object released/state change, about 30%; you cannot guess this yourself), then batch-fill with frame_type=last_frame. Production data: in 32 episodes, 30 generated only first frames for the whole episode, and 23 proceeded all the way to video: those shots had only one first-frame anchor when generating video, so the model freely invented the end state. shots_needing_last_frame in this tool’s response is this count; if it is not 0, do not go straight to review_frames. ★frames_planned in the response is **planned count, not successful count**—this endpoint returns before the backend dispatch loop starts. Real progress is only in get_storyboards first_frame_image / get_jobs per-item generation records; insufficient balance (402) aborts the whole batch, and polling forever will not produce results—check balance instead of continuing to wait. ★★**If a few shots repeatedly fail while all others are ready**: that is not “not enough waiting”; those shots are being repeatedly rejected by content gates. Check fail_reason in get_storyboards (repeat_rejected / diagnosis_required / needs_content_fix / contract_rejected). If diagnosis_required, first diagnose existing candidates per fail_hint; if audit is wrong, re-audit first; if evidence is insufficient, re-check first; do not redraw unchanged or rewrite the script on your own. Then **run run_precheck** (can be run after the fact; it will tell you what contradiction it is), follow its hints to use update_shot to change shot size/description/bound characters, then regenerate. Do not keep spinning generate_frames, and do not send the customer to external tools to make images—external images bypass identity anchors and frame audit, so faces/costumes/style will drift.\n★【Storyboard review hard gate · free】Before this step you must call review_storyboards first: relay every returned finding to the customer verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. Without review it is rejected with 400. If content changes after review → token auto-invalidates; just review again (still free). error findings block by default; only if the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing ahead with issues is likely to produce a junk video and still charges normally (acknowledge_review only means the customer personally agreed; any execution mode requires explicit customer consent, including autopilot). In autopilot steps, only whitelisted heuristic errors can pass with auto_acknowledge:true (platform decides; if not whitelisted returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer; false = self-fix per action and re-review). ★Gray-release dramas also require you (agent) to personally QC: inspect materials item by item per agent_qc returned by review_storyboards, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default just like error).\n★【Asset-layer hard gate · free】You must also run review_assets first (character appearance images/scene images/prop images) and pass its review_token as asset_review_token here (coexists with storyboard-layer review_token; both are required; gray-release dramas missing it will 400 and name review_assets). Generating frames does not invalidate the asset token. ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation depends on execution mode: professional mode / unconfirmed plan / this step controlled by customer → explain to customer and proceed only after customer agrees; do not decide for them; this step in autopilot → do not ask customer, follow get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-step quotes must be within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask the customer. ★**Image-generation quotes (character sheets/scene images/frame generation) provide two numbers**: estimated_points is the **upper bound** (estimated using the maximum reference-image count for that model, ensuring you do not start with an underbudget and hit 402 midway); typical_points in the same response is the **typical cost**. Tell the customer both—only saying the upper bound makes it seem much more expensive (the full-reference upper bound can exceed typical by 2x+), while only saying the typical value may leave insufficient balance. For fixed-price models they are equal; then one number is enough. Video-generation quote and charge use the same function; this range does not exist.",
   "quote_shot_frame": "Quote: how many credits to redraw/fill **one frame of one shot** (one frame = one image). Returns estimated_points, quote_id. Zero cost. Use this when the customer says \"shot N is wrong/needs changes\", instead of using another image platform and then upload_shot_frame. ★Response includes billing_kind/unit_points(actual billing tier and unit price); if you will switch models in generate_shot_frame, pass the same image_model when quoting. ★Both sides must pass the same image_model — mismatch is rejected directly (400 IMAGE_MODEL_MISMATCH), because the model determines the billing tier; different sources mean \"estimate ≠ charge\". Passing neither on both sides also counts as consistent (uses the drama setting). Deprecated models (all FLUX series) are always rejected; do not pass them. ★Returns two numbers: estimated_points is the **upper bound** (estimated by maximum reference-image count; prepare this balance to avoid mid-run 402), typical_points is the **usual cost**. Tell the customer both; quoting only the upper bound makes it look much more expensive. For fixed-price models (e.g. Nano Banana series), they are equal.",
   "generate_shot_frame": "After confirmation, generate or regenerate the frame for **one shot** (async). This is the proper path to fix a shot image: the platform will carry this shot’s character identity anchors, scene/prop reference images, style anchor, and frame audit; regenerated images stay consistent with the whole film. Using external tools to generate then upload bypasses this entire chain, so character/clothing/style will inevitably drift. Regeneration overwrites the shot’s existing frame image (including prior uploads) and marks this shot’s video as needing regeneration. A last frame requires this shot’s first frame to be ready (otherwise use first_frame or both first). Completion criterion: poll get_storyboards and watch this shot’s first_frame_image/last_frame_image change.\n★Inherited reopen (reopen_pair_id): if get_storyboards returns this field on a shot, pass it through unchanged to reroll only the actually problematic side among first/last frames—the other previously generated candidate is preserved as-is, not regenerated and not charged again. When passing it, you no longer need frame_type (it will be ignored; the platform decides which side to regenerate); quote_id still must come from quote_shot_frame (frame_type may be first_frame or last_frame; single-frame price is the same). If the shot has no reopen_pair_id field (inheritance conditions not met), do not pass this parameter; use normal frame_type retry.\n★★If generating a last frame is blocked with “this shot is marked as state changed, but nowhere says what it looks like at the end”: the correct fix is to use update_shot to write the ending state into last_frame_prompt, then generate—**do not simply add allow_missing_terminal and force it**. For this type of shot, generating a last frame as-is historically succeeds only 9.4% of the time (40.2% when an end-state description exists), so forcing it will mostly waste one charge. Only pass that parameter when you confirm this shot is intended to look “almost unchanged”.\n★One-click final cut hosted flow: the same shot may regenerate frames at most 3 rounds (one call counts as one round; both also counts as one round). At the limit, returns **409 AUTOPILOT_SHOT_REGEN_LIMIT** (not dispatched, not charged, quote not consumed)—do not bypass with another tool. Stop and ask the customer: if the customer agrees to more regeneration, quote and generate normally with customer_approved_more_regens:true (grants another limit); if the customer accepts the current state, proceed downward, and the next paid call must include acknowledge_review:true to record confirmation. Professional mode and customer-controlled stages are not subject to this limit.\n★【Storyboard review hard gate · free】Before this step you must call review_storyboards: tell the customer every returned finding verbatim (each with code=issue type, shots=hit shot numbers, action=which tool to use for fixing), then pass review_token into this tool. If not reviewed, it will be rejected with 400. If content changes after review → token auto-invalidates; just re-review once (still free). error findings block by default; only when the customer is informed and insists on continuing as-is may you pass acknowledge_review:true—pushing ahead with known issues is likely to produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, hosted included). In hosted stages, only allowlisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not allowlisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask the customer, false = self-fix according to action and re-review). ★Grayscale dramas also require you (agent) to personally QC: inspect assets item by item per agent_qc returned by review_storyboards, answer the checklist line by line, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; problematic report → blocks by default just like error).\n★【Asset-layer hard gate · free】You must also run review_assets first (character sheet images / scene images / prop images), and pass its review_token as asset_review_token (coexists with the storyboard-layer review_token; both are required; grayscale dramas missing it get 400 naming review_assets). Generating frames does not invalidate the asset token. ⚠️ Batch quote confirmation flow: first call the corresponding quote_* tool to get estimated_points and quote_id, then call this tool with quote_id (quote confirmation depends on execution mode: professional mode / unconfirmed plan / customer-controlled stage → explain to the customer and proceed only after customer approval; hosted stage → do not ask the customer, follow get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log). Hosted-stage quotes must stay within the hard budget cap; if blocked by 402 BUDGET_WOULD_EXCEED, stop and ask the customer. ★**Image-generation quotes (character sheet / scene image / frame generation) return two numbers**: estimated_points is the **upper bound** (estimated using that model’s maximum reference-image count, ensuring you do not start with an underbudgeted run that hits 402 midway); 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 (the max-reference upper bound can exceed 2× the typical value), while only saying the typical value may leave insufficient balance. For fixed-price models they are equal, so one number is enough. Video-generation quote and charge use the same function; no such range exists.",
-  "quote_videos": "Quote: how many credits to batch-generate videos for an episode (same function as actual charge, relatively accurate). Returns estimated_points, quote_id. Zero cost. ⚠️ Video is a large expense; clearly tell the user the credits and wait for confirmation.\n★**Only counts shots actually dispatched this time**: shots that already have video are skipped during whole-episode resume, not regenerated and not priced—shots_total = shots priced this time (not total shots in episode), shots_already_done = shots with video skipped this time. Exception: if any shot in a scene group lacks video, the **entire group is regenerated**, and already-generated shots inside the group are also priced. All shots already have video ⇒ 400(no dispatchable shots; use regenerate_shot_video to regenerate a shot). If any shot's video is cleared after quoting (becomes pending video), generate_videos returns 409 requiring a new quote; it will not charge for shots outside the quote.\n★**Specify video engine per shot**: pass shot_engines={storyboard id: engine} to switch engines only for those shots and only for this whole-episode generation (does not change drama-level video_engine; other shots unchanged). Quote prices per shot accordingly; quote_id pins the engines, and generate_videos dispatches exactly them—changing engine requires a new quote. Receipt shot_engines = actual applied mapping; shot_engines_ungrouped = scene groups **split into per-shot generation** because they include specified shots (scene-group duration and multi-keyframes are planned for the drama engine; generating the whole group with a changed engine would lose shots/keyframes; after splitting, other shots in the group still generate per-shot with the drama engine, losing group-level one-pass continuity, so do not split a good group for one shot—check get_scene_group_plan first). Selected engine must support this drama's resolution (seedance-2.5 only 480p/720p; hailuo-3 only 720p/1080p; wan3.0/wan3.0-prime 480p~1080p), and shot duration must not exceed that engine's single-shot limit (seedance-2.5/wan3.0 30s, hailuo-3 15s), otherwise 400 (vendors truncate overlong shots; either switch engine or split_shot). Shots with specified engines must be generated this time: whole-episode generation will not regenerate shots already having video, so specifying an engine for one ⇒ 400; a split per-shot scene group only counts group members without video. If you only want to regenerate a few shots that already have video, using quote_regenerate_shot_video with model is cheaper.",
-  "generate_videos": "After confirmation, batch-generate videos: one backend chain runs the full episode; if balance is insufficient it auto-aborts the whole chain (prevents duplicate charging). Requires first frames already generated for this episode (otherwise rejected). Poll get_storyboards; completion = video_url filled shot by shot.\n★【Hard gate: shot image review · free】Before this step you must call review_frames first: report the returned findings to the customer verbatim, item by item (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. No review → 400 rejection. If content changes after review → token auto-invalidates; review once again (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is, pass acknowledge_review:true—pushing ahead with issues will very likely produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, including autopilot). In autopilot steps, only whitelisted heuristic errors may be released with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer, false = self-fix per action then re-review). ★ Gray-release dramas also require you (agent) to personally QC: per review_frames returned agent_qc, inspect assets item by item, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has problems → blocked by default same as error). ⚠️ Batch quote confirmation flow: first call the 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 / this step controlled by customer → explain to customer and proceed only after customer agrees; do not decide for customer; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-step quotes must stay 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) give two numbers**: estimated_points is the **upper bound** (estimated using 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 **usual cost**. Tell the customer both—only stating the upper bound makes it look much more expensive (with max reference images, the upper bound can exceed 2x the typical value); only stating the typical value may leave balance insufficient. For fixed-price models the two are equal; then one number is enough. Video-generation quote and charge use the same function; no range exists.\n★【Post-completion QC · free】After generation, wait for it to persist (check video_status in get_storyboards / get_pipeline_status), then call review_videos to review video and dubbing layers (missing video / video made from old frames / hard cut at ending / unexpected human voice / missing dubbing / voice timbre unassigned / original voice line expired); fix and re-review; then personally inspect each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit via submit_qc_report; compose_episode must carry its review_token.",
+  "quote_videos": "Quote: how many credits to batch-generate videos for an episode (same function as actual charge, relatively accurate). Returns estimated_points, quote_id. Zero cost. ⚠️ Video is a large expense; clearly tell the user the credits and wait for confirmation.\n★**Only counts shots actually dispatched this time**: shots that already have video are skipped during whole-episode resume, not regenerated and not priced—shots_total = shots priced this time (not total shots in episode), shots_already_done = shots with video skipped this time. Exception: if any shot in a scene group lacks video, the **entire group is regenerated**, and already-generated shots inside the group are also priced. All shots already have video ⇒ 400(no dispatchable shots; use regenerate_shot_video to regenerate a shot). If any shot's video is cleared after quoting (becomes pending video), generate_videos returns 409 requiring a new quote; it will not charge for shots outside the quote.\n★**Specify video engine per shot**: pass shot_engines={storyboard id: engine} to switch engines only for those shots and only for this whole-episode generation (does not change drama-level video_engine; other shots unchanged). Quote prices per shot accordingly; quote_id pins the engines, and generate_videos dispatches exactly them—changing engine requires a new quote. Receipt shot_engines = actual applied mapping; shot_engines_ungrouped = scene groups **split into per-shot generation** because they include specified shots (scene-group duration and multi-keyframes are planned for the drama engine; generating the whole group with a changed engine would lose shots/keyframes; after splitting, other shots in the group still generate per-shot with the drama engine, losing group-level one-pass continuity, so do not split a good group for one shot—check get_scene_group_plan first). Selected engine must support this drama's resolution (seedance-2.5 only 480p/720p; hailuo-3 only 720p/1080p; wan3.0/wan3.0-prime 480p~1080p), and shot duration must not exceed that engine's single-shot limit (seedance-2.5/wan3.0 30s, hailuo-3 15s), otherwise 400 (vendors truncate overlong shots; either switch engine or split_shot). Shots with specified engines must be generated this time: whole-episode generation will not regenerate shots already having video, so specifying an engine for one ⇒ 400; a split per-shot scene group only counts group members without video. If you only want to regenerate a few shots that already have video, using quote_regenerate_shot_video with model is cheaper. ★The response may carry an **unchained-seam hint** (does not affect review_token / quote / status codes): review_frames and generate_videos return unchained_seam_advisory; quote_videos returns an advisories entry with code=unchained_seams. seams lists adjacent seams (from_shot→to_shot) that chain_frames would chain but that are not chained yet: status=no_stamp (never chained) / pending (a chaining was dispatched but has not landed, or its audit has no verdict yet) / stale_anchor (the previous chaining anchor is no longer valid: the upstream shot's last frame was regenerated after chaining, so the seam must be re-chained) / join_failed (the last chaining regeneration was rejected / failed / superseded and never landed) / audit_failed (the chaining landed but the continuity audit judged it discontinuous — see seam_failed_dims in get_storyboards) / first_frame_regenerated (the downstream first frame was regenerated after the seam was reviewed, bypassing the chaining path, so the old chaining no longer counts) / not_linked (the planner judges the seam unchained but the cause is not evidenced); re-chain all of them per the plan; video_locked lists the same kind of seam where the downstream shot already has a video — chain_frames will not touch those, so fix them per shot with chain_shot_from_prev / chain_shot_from and then regenerate_shot_video (quote first). If seams is non-empty before generating videos, run chain_frames(dry_run:true) first, tell the customer the plan and price, execute after they agree, then re-run review_frames.",
+  "generate_videos": "After confirmation, batch-generate videos: one backend chain runs the full episode; if balance is insufficient it auto-aborts the whole chain (prevents duplicate charging). Requires first frames already generated for this episode (otherwise rejected). Poll get_storyboards; completion = video_url filled shot by shot.\n★【Hard gate: shot image review · free】Before this step you must call review_frames first: report the returned findings to the customer verbatim, item by item (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass review_token into this tool. No review → 400 rejection. If content changes after review → token auto-invalidates; review once again (still free). If there is error, block by default; only if the customer is informed and insists on continuing as-is, pass acknowledge_review:true—pushing ahead with issues will very likely produce unusable footage and still charges normally (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, including autopilot). In autopilot steps, only whitelisted heuristic errors may be released with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause and ask customer, false = self-fix per action then re-review). ★ Gray-release dramas also require you (agent) to personally QC: per review_frames returned agent_qc, inspect assets item by item, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has problems → blocked by default same as error). ⚠️ Batch quote confirmation flow: first call the 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 / this step controlled by customer → explain to customer and proceed only after customer agrees; do not decide for customer; this step autopilot → do not ask customer, execute per get_production_plan autopilot.default_decisions, platform records it in get_autopilot_log). Autopilot-step quotes must stay 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) give two numbers**: estimated_points is the **upper bound** (estimated using 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 **usual cost**. Tell the customer both—only stating the upper bound makes it look much more expensive (with max reference images, the upper bound can exceed 2x the typical value); only stating the typical value may leave balance insufficient. For fixed-price models the two are equal; then one number is enough. Video-generation quote and charge use the same function; no range exists.\n★【Post-completion QC · free】After generation, wait for it to persist (check video_status in get_storyboards / get_pipeline_status), then call review_videos to review video and dubbing layers (missing video / video made from old frames / hard cut at ending / unexpected human voice / missing dubbing / voice timbre unassigned / original voice line expired); fix and re-review; then personally inspect each shot and listen to dubbing per agent_qc (action correct, face stable, lines complete, voice right), submit via submit_qc_report; compose_episode must carry its review_token. ★The response may carry an **unchained-seam hint** (does not affect review_token / quote / status codes): review_frames and generate_videos return unchained_seam_advisory; quote_videos returns an advisories entry with code=unchained_seams. seams lists adjacent seams (from_shot→to_shot) that chain_frames would chain but that are not chained yet: status=no_stamp (never chained) / pending (a chaining was dispatched but has not landed, or its audit has no verdict yet) / stale_anchor (the previous chaining anchor is no longer valid: the upstream shot's last frame was regenerated after chaining, so the seam must be re-chained) / join_failed (the last chaining regeneration was rejected / failed / superseded and never landed) / audit_failed (the chaining landed but the continuity audit judged it discontinuous — see seam_failed_dims in get_storyboards) / first_frame_regenerated (the downstream first frame was regenerated after the seam was reviewed, bypassing the chaining path, so the old chaining no longer counts) / not_linked (the planner judges the seam unchained but the cause is not evidenced); re-chain all of them per the plan; video_locked lists the same kind of seam where the downstream shot already has a video — chain_frames will not touch those, so fix them per shot with chain_shot_from_prev / chain_shot_from and then regenerate_shot_video (quote first). If seams is non-empty before generating videos, run chain_frames(dry_run:true) first, tell the customer the plan and price, execute after they agree, then re-run review_frames.",
   "compose_episode": "Stitch all shot videos of one episode into one final cut (final stitching). **Free** (pure stitching, no quote confirmation required), async in backend. Before starting, a final-stitch precheck runs: shots missing video or video tasks still generating will hard-block with 400 and list the problem shots (blockers); fix them and retry. If you really want a partial final cut, pass force=true (shots missing video are skipped, final cut lacks shots, logged). advisories in the response (duration drift/orphan tasks/missing TTS/post_production_pending unfinished post-production effects) are warnings only, not blockers; handle them one by one before stitching. After starting, poll with get_final_cut.\n★【Video and dubbing review hard gate · Free】Before this step you must call review_videos: relay the returned findings to the customer verbatim one by one (each with code=issue type, shots=hit shot numbers, action=which tool to use to fix), then pass the review_token into this tool. If not reviewed, 400 rejection. If content changed after review → token auto-invalidates; just review again (still free). error blocks by default; only if the customer is informed and insists on proceeding as-is may you pass acknowledge_review:true — proceeding with known issues will likely produce unusable video and still charge credits as usual (acknowledge_review only means the customer personally agreed; every execution mode requires explicit customer consent, autopilot included). In autopilot, only whitelisted heuristic errors may pass with auto_acknowledge:true (platform decides; if not whitelisted, returns 400 AUTOPILOT_MUST_ASK: must_ask_customer=true means pause to ask customer, false = self-fix per action and re-review). ★ For gray rollout dramas, you (agent) must personally QC: inspect materials item by item per agent_qc from review_videos, answer every checklist item, and submit via submit_qc_report before this token can be used (not submitted → 400 agent_qc_required; report has issues → blocked by default like error).\n★★【Pre-compose checks · after review_videos passes, before compose_episode】Don't hunt for problems by repeatedly exporting the whole cut and trying transitions by hand — per-shot and seam problems have dedicated tools; run them in order before stitching: ① portraits / turnarounds / scene images / shot frames were changed in this episode → first get_stale_portrait_frames(episode_id, free) to see which shots' in-use frames are still based on old assets; for shots where it is unclear which version to use, get_asset_versions(storyboard_id, free) shows each shot's versions and dependencies (unknown means insufficient evidence, not stale; regenerating is paid, so give the list to the customer and let them decide); ② scan_intra_shot_cuts(episode_id, free) finds shots where the vendor hard-cut inside a single shot; ③ per shot, recommend_trim_window(storyboard_id, free) shows a frozen tail and the effective action window (shots inside a scene group return applicable=false — skip them); apply a recommendation with trim_shot (free); ④ audit_seams(episode_id) checks editing continuity at seams between adjacent shots: by default dry_run only lists what would be audited (free); actually running it is billed by real text-token usage — tell the customer, and only after they explicitly accept pass dry_run:false + confirm_usage_billing:true; read the result from seam_review in get_storyboards; ⑤ then compose_episode. If the final cut shows jump cuts / dragging tails / seams that don't match, go back to these tools to locate the shots and fix only those — don't keep re-exporting the whole cut by trial and error. These checks are advisory, not gates; trimming and seam audits don't invalidate the review_videos token.\n★【Post-completion QC · Free】After the final cut is ready, run review_final_cut (missing shots/subtitles not fitting/identity anchors/axis jumps/typos; proofread=false means no credits charged), tell the customer the conclusion; call confirm_delivery_acceptance only after customer confirmation (delivery acceptance requires explicit customer consent in every execution mode, autopilot included). force only bypasses the final-stitch precheck, not the review gate.",
   "get_final_cut": "Check an episode final cut status and download link. When status=completed, returns download_url(our COS direct link, downloadable directly). Free. ★bgm_stale=true means BGM was generated/modified after the final cut and is not yet in the final cut: just compose_episode again (free), do not re-render. ★If a current delivery version has been set (external version registered by register_external_delivery, or platform version specified by set_current_delivery), also returns delivery—that is the version the customer actually received; download_url remains the platform's latest stitched final cut. To see what every final-cut version used and its hash, use list_deliveries.",
   "get_export": "Check an episode export/master status (downloadable master after final assembly). Free.",
@@ -258,5 +258,9 @@
   "get_local_frame_edit": "Check progress and results of a local frame edit (free). status=running → keep waiting; when completed, look at each candidate: composited_url (the result pasted back onto the original — show this to the customer), verdict (pass = usable; warn = usable but needs a human look — REGION_SEAM_WARN possible seam / EDIT_NOT_APPLIED barely changed / IDENTITY_NEEDS_REVIEW face-comparison score in the grey zone, not auto-approved / IDENTITY_NOT_JUDGEABLE side view, looking down or face too small to judge / IDENTITY_COMPARE_LOW legacy identity score low / IDENTITY_AUDIT_UNAVAILABLE identity not audited; reject = not recommended — REGION_MISALIGNED misaligned paste / IDENTITY_MISMATCH face comparison says it became a different person / IDENTITY_AUDIT_REJECTED frame audit failed, possibly a composition issue already present in the original frame), reason_text (a plain-language explanation of each reason — relay it to the customer as is), metrics, identity_audit, identity_compare (face edits: with method=face_embedding the decision uses face embeddings — similarity to the same face before the edit ≥0.75 passes, <0.60 is a mismatch, in between goes to a human; vlm_reference is recorded only. Without a method field it is the legacy advisory score). ★Still check face edits with your own eyes — the platform cannot judge side views, downward-looking or small faces. Download and look at composited_url yourself, tell the customer, then adopt_local_frame_edit the one they pick. Rejected candidates are not refunded (including those failing the frame audit because of an issue already in the original frame).",
   "adopt_local_frame_edit": "Adopt a local-edit candidate as this shot's current frame (free). Same follow-up as an uploaded frame: the shot video is marked for regeneration and adjacent seams are repaired. ★Only after the customer has looked and chosen. If the frame changed after the edit → 409 BASE_FRAME_CHANGED (start a new edit on the current frame); verdict=reject candidates are refused by default (409 CANDIDATE_REJECTED) — pass accept_rejected:true only when the customer insists after seeing it.",
   "audit_seam_directions": "Pre-video seam direction check (advisory, never blocks any step): for every pair of adjacent shots, compares \"previous shot's last frame (or first frame if none) ↔ this shot's first frame\" for the same subject jumping left/right sides of the frame (a reversed eyeline is noted with it), reversed motion direction, and shot-size jumps (same subject, extreme long ↔ close-up). Eyeline alone and key-light direction are observed but not reported: production replay showed too many false positives on those (better to miss than to nag). Shots that look fine alone but jump when cut together usually fail on these. Complements audit_seams, which checks identity/wardrobe/props/object state but not direction or position. ★When: after first frames (and needed last frames) are done and chain_frames has run, before review_frames / generate_videos. Scene changes, declared jump cuts, insert shots and title/black cards are skipped automatically. ★dry_run first (default, free): returns the seams to observe plus estimated_points (upper bound) and typical_points (usual cost); tell the client both — billed by actual text tokens. After the client agrees, pass dry_run=false + confirm_usage_billing=true. Execution is asynchronous and returns immediately; read results with get_seam_directions a minute or two later. Seams already observed with unchanged frames are not billed again.",
-  "get_seam_directions": "(Free) Read audit_seam_directions results: each issue gives the seam shot numbers, the problem (subject jumps sides, reversed motion, shot-size jump) and fixes (chain_shot_from mode=reframe to regenerate this shot's first frame anchored on the previous last frame / update_shot to state facing then generate_shot_frame / align_prev_shot when the previous shot already has video / split_shot to insert an intermediate shot size). Results are advisory: explain them to the client and let the client pick which to fix; intentional reverse shots, turns or impact cuts can be ignored. not_audited>0 = seams not observed yet or frames changed since; running=true = still running. review_frames' seam_direction_advisory is a summary of the same results. This tool only looks at pre-video still frames; after videos are generated, check seams with preview_seams (free short-clip previews)."
+  "get_seam_directions": "(Free) Read audit_seam_directions results: each issue gives the seam shot numbers, the problem (subject jumps sides, reversed motion, shot-size jump) and fixes (chain_shot_from mode=reframe to regenerate this shot's first frame anchored on the previous last frame / update_shot to state facing then generate_shot_frame / align_prev_shot when the previous shot already has video / split_shot to insert an intermediate shot size). Results are advisory: explain them to the client and let the client pick which to fix; intentional reverse shots, turns or impact cuts can be ignored. not_audited>0 = seams not observed yet or frames changed since; running=true = still running. review_frames' seam_direction_advisory is a summary of the same results. This tool only looks at pre-video still frames; after videos are generated, check seams with preview_seams (free short-clip previews).",
+  "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."
 }

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

@@ -42,7 +42,7 @@
   "get_health_report": "(★推荐·免费诊断)读分镜出体检报告:时长超标/母题覆盖不足/问题镜。纯读、免费。出图前查,识别问题先改再出、别出了片才发现。",
   "review_script": "【第①道硬闸·免费】审查 AI 改写稿:对白行长度、情绪转折完整性、开场钩子、末场悬念。★extract_assets 与 generate_storyboards 之前必须先跑本工具——人物档案和分镜都从改写稿派生,稿子里的问题会被逐层放大到定妆图/出图/出视频,等成片才发现就是整集重来。把 findings 逐条告诉客户、按 action 修完(改稿走 edit_rewritten_script)后复审,再拿 review_token 往下走。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。\n★【剧本评估与建议】materials 里有客户原稿(script:original)和改写稿(script):先评估客户给的稿子本身(主线、动机、冲突、节奏、漏洞、能不能拍),再核对改写稿;每个问题在 submit_qc_report 的 suggestions 里给出具体改法(能直接改字的给 before/after)。提交后把评估和建议逐条讲给客户,让客户选:采纳其中几条 / 全部直接执行 / 不改直接往下做(选哪条路按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log);托管环节默认只执行 priority=must 且不改客户原台词的,其余写进交付报告。",
   "review_storyboards": "【第②道硬闸·免费】审查分镜:禁区词(会被厂商审核拒、白扣费)、镜头时长分布、相邻构图重复、同场景角色站位漂移、情绪曲线峰谷、关键镜标记。★generate_frames 之前必须先跑本工具——分镜里的问题一旦整集出图就变成整集废图,单镜修不回来。按 findings.action 用 update_shot/split_shot 修完再复审。★code=forbidden_term 的 finding 带 `terms` 字段(命中的具体词,如「背景音乐」「强光」)与 `shots`(镜号),照着这两个去 update_shot 改掉即可,不用逐字猜。★禁区词判**否定语义**:写「无背景音乐」「不要配乐」不算违规(那是在遵守约束),不必为此改稿。★warnings 里的「动作过载」(action_overload,advisory 不拦):一镜塞了超过时长承载量的独立动作,出视频前用 split_shot 拆开或删动作——成片后靠慢放/叠化补救不了。多人各做一件事或本身连贯的一串可忽略。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
-  "review_frames": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / generate_shot_frame 单镜重生)再复审。★还会报**镜间接缝**(warning,不拦):code=seam_unchained(标了连续却从没做过首尾帧衔接,或发起的衔接重生没落地 / 衔接后首帧又被重生)/seam_broken(接过但没接上,或上一镜尾帧在衔接之后又重生过),shots 是「与上一镜的缝有问题」的那一镜。出视频前修最便宜——视频按首帧生成,首帧与上镜尾帧对不上,成片就是一次跳切。修法看 action(整集 chain_frames 先 dry_run;单道 chain_shot_from_prev / chain_shot_from)。★有相邻镜时响应还带 seam_direction_advisory(提示性,不影响 review_token):相邻镜方向对照(主体跳边/运动反向/景别跳级)的已有结论;还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
+  "review_frames": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / generate_shot_frame 单镜重生)再复审。★还会报**镜间接缝**(warning,不拦):code=seam_unchained(标了连续却从没做过首尾帧衔接,或发起的衔接重生没落地 / 衔接后首帧又被重生)/seam_broken(接过但没接上,或上一镜尾帧在衔接之后又重生过),shots 是「与上一镜的缝有问题」的那一镜。出视频前修最便宜——视频按首帧生成,首帧与上镜尾帧对不上,成片就是一次跳切。修法看 action(整集 chain_frames 先 dry_run;单道 chain_shot_from_prev / chain_shot_from)。★有相邻镜时响应还带 seam_direction_advisory(提示性,不影响 review_token):相邻镜方向对照(主体跳边/运动反向/景别跳级)的已有结论;还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
   "review_assets": "【资产层硬闸·免费】审查本集**出镜**用到的角色形象图、场景图、道具图——覆盖与质量:出镜角色缺定妆图 / 缺设定图 / 还在生成 / 生成失败 / 设定图被一致性闸拒收(hint 带拒收理由);场景缺空景基板;分镜引用的道具缺道具图 / 被拒;道具图与本镜时代形制冲突;缺色彩脚本(warning)。★出完定妆图、设定图、场景图、道具图后都调一次;generate_frames / generate_shot_frame 之前必须审过——把返回的 review_token 作为 **asset_review_token**,连同分镜层的 review_token 一起传(两张都要)。只看资产本身:出完镜头图不会让它失效;换了定妆图/场景图/道具图会失效,复审即可(免费、秒级)。findings 逐条讲给客户(code=问题类型、names=哪个角色/场景/道具、shots=影响的镜号、action=该调哪个工具修)。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
   "review_videos": "【视频与配音层硬闸·免费】审查本集视频与配音——覆盖与质量:缺视频 / 还在生成 / 生成失败 / 被厂商拒;首帧换过而视频还是旧帧出的(video_stale);疑似片尾硬切、无台词镜意外人声(warning);配音剧:台词镜缺配音、会开口的角色没音色、缺旁白角色;原声剧:出片时没挂上当前声线的镜、没锁声线的角色;缺配乐(warning)。★出完视频、配音(generate_tts)、配乐后都调一次;compose_episode 之前必须审过,带返回的 review_token。\n★★【成片前自检·review_videos 通过后、compose_episode 之前】别靠反复导出整片、手工试转场来找问题——逐镜与接缝的问题有专门工具,拼之前按序过一遍:①这一集换过定妆图 / 设定图 / 场景图 / 镜头帧 → 先 get_stale_portrait_frames(episode_id,免费)看哪些镜的在用帧还基于旧资产,拿不准该用哪一版的镜再 get_asset_versions(storyboard_id,免费)逐镜看版本与依赖(unknown 是证据不足、不是已过期;重出要付费,清单讲给客户由客户定);②scan_intra_shot_cuts(episode_id,免费)查厂商在单镜内自行硬切的镜;③逐镜 recommend_trim_window(storyboard_id,免费)看冻结尾段与有效动作区间(组内镜返回 applicable=false,跳过),有推荐就 trim_shot 应用(免费);④audit_seams(episode_id)查相邻镜接缝的剪辑连续性:默认 dry_run 只列待审范围(免费),真执行按实际文本 token 计费,讲给客户、客户明确接受后才带 dry_run:false + confirm_usage_billing:true,结果看 get_storyboards 的 seam_review;⑤再 compose_episode。拼完成片发现跳切 / 拖尾 / 接不上,回到这几个工具按镜定位后只修那几镜,别整片反复导出试错。这些都是提示性检查,不过闸;裁剪与接缝审核不让 review_videos 的 token 失效。返回体的 pre_compose_checks 是同一份清单(结构化,逐项 tool/scope/when/cost)。\n更细的检查(要解码画面/音轨)另有 scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio;拼完成片再跑 review_final_cut。★返回带 post_production_advisory = 剧本标注「后期」的叙事必需特效还没处理(平台不会合成):原样告诉客户,用 get_post_production_checklist 看清单。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
   "submit_qc_report": "提交你(agent)亲自看素材做的质检报告。免费。先调对应层的 review_*(script / storyboards / assets / frames / videos),按返回的 agent_qc 逐件打开 materials 看、逐条回答 checklist,再调本工具。★平台只校验报告**是否完整**,不评判你的结论:checklist 每个 id 都要答(ok / issue / na,issue 必须写 note 说清哪件什么问题);materials 里的每个 ref 都要列进 inspected(漏一件就拒收并点名漏了哪些);有问题就 verdict=issues 并在 issues 里逐条写,有问题却报 pass 会被拒。★别走过场:没打开看就列进 inspected,等于替客户签了字——出了废片照常扣费。★verdict=issues 时这张 token 默认进不了下一步:把问题讲给客户,修完重新 review + 质检;客户明确知情并坚持照现状继续,下一步才带 acknowledge_review:true。★suggestions(修改建议):剧本层(agent_qc.suggestions_required=true)报了问题就必须给,其它层可选。每条写 problem + proposal,能直接改字的再给 before/after;返回会给每条编号(s1…)。把建议讲给客户,客户选采纳几条 / 全部直接执行 / 不改直接往下做(选哪条路;托管=只执行 priority=must 且不改客户原台词的按执行模式:专业模式 / 未确认方案 / 本环节由客户把控 → 讲给客户、客户同意才做,别替客户决定;本环节托管 → 不问客户,照 get_production_plan 的 autopilot.default_decisions 执行,平台记进 get_autopilot_log)。审查之后内容又变了,报告会被拒,重新 review 后按新的 agent_qc 再质检。",
@@ -59,8 +59,8 @@
   "local_frame_edit": "确认后**局部修改某一镜的某一帧**(异步,扣费)。参数必须与 quote_local_frame_edit 那次完全相同(区域 / 指令 / 类型 / 角色 / 候选数 / 底图任一项变了 → 409 QUOTE_PARAMS_CHANGED,重新报价即可,免费)。返回 edit_id,之后用 get_local_frame_edit 轮询。★**不会自动替换当前帧**:候选出完先给客户看(composited_url),客户选定后调 adopt_local_frame_edit 才写进这一镜、并把本镜视频标为待重生;不采用,当前帧就不变。★被判据拒掉的候选照常计费、不退点。\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 倍以上),只说通常值又会让余额准备不足。固定价模型下两者相等,这时说一个数就行。出视频的报价与扣费同函数,不存在这个区间。",
   "get_local_frame_edit": "查一次局部返修的进度与结果(免费)。status=running 继续等;completed 后逐个候选看:composited_url(贴回原图后的成品,给客户看的就是它)、verdict(pass=可直接用;warn=能用但要人看——REGION_SEAM_WARN 边界可能有接缝 / EDIT_NOT_APPLIED 基本没改到 / IDENTITY_NEEDS_REVIEW 修脸后人脸比对分在灰区、平台不自动放行 / IDENTITY_NOT_JUDGEABLE 侧脸·低头·脸太小等判不了 / IDENTITY_COMPARE_LOW 旧版身份比对分偏低 / IDENTITY_AUDIT_UNAVAILABLE 身份没审成;reject=不建议用——REGION_MISALIGNED 贴回错位 / IDENTITY_MISMATCH 修脸后人脸比对判定换了人 / IDENTITY_AUDIT_REJECTED 帧审计不过,可能是原帧本身的构图问题)、reason_text(每条原因的中文说明,原样讲给客户)、metrics、identity_audit、identity_compare(修脸类身份比对:method=face_embedding 时按人脸特征向量判——与修改前同一张脸相似度 ≥0.75 放行、<0.60 判不像、中间交人看,vlm_reference 只记录;没有 method 字段的是旧版,只作参考)。★修脸结果仍要亲眼看是不是同一个人——侧脸、低头、小脸时平台判不了。下载 composited_url 亲眼看过、讲给客户,客户选定后用 adopt_local_frame_edit。被拒候选不退点(包括原帧本身问题导致帧审计不过的)。",
   "adopt_local_frame_edit": "采用某个局部返修候选:把它写成这一镜的当前帧(免费)。与上传帧同一套后续处理:本镜视频标为待重生、相邻接缝跟着修。★只在客户看过并选定后调用。返修之后这一帧若已换过 → 409 BASE_FRAME_CHANGED(对当前帧重新发起);verdict=reject 的候选默认拒绝采用(409 CANDIDATE_REJECTED),客户看过坚持要用才带 accept_rejected:true。",
-  "quote_videos": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。\n★**只计这次真会派发的镜**:已出视频的镜整集续跑时跳过,不重出不计价——shots_total = 这次计价的镜数(不是集内总镜数),shots_already_done = 已出视频、这次跳过的镜数。例外:场景组只要有一镜没出视频就**整组重出**,组内已出的镜同样计价。全部已出视频 ⇒ 400(没有可派发的镜,要重出某镜用 regenerate_shot_video)。报价之后若有镜的视频被清空(变成待出视频),generate_videos 会 409 要求重新报价,不按报价外的镜扣费。\n★**按镜指定视频引擎**:传 shot_engines={分镜id: 引擎} 即只为这些镜、这一次整集生成换引擎(不改剧级 video_engine,其余镜照旧)。报价按它逐镜计价,quote_id 把引擎钉死,generate_videos 派发的就是它——要改引擎必须重新报价。回执 shot_engines = 实际生效的映射;shot_engines_ungrouped = 因含指定镜而**拆成逐镜出**的场景组(场景组的时长与多关键帧是按剧引擎规划的,换引擎整组出会丢镜/丢关键帧;拆组后组内其余镜仍按剧引擎逐镜出,失去组内一次成片的连贯性,所以别为一镜去拆一个好好的组——先看 get_scene_group_plan)。所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;拆成逐镜的场景组只计没出视频的组员。只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。",
-  "generate_videos": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\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。",
+  "quote_videos": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。\n★**只计这次真会派发的镜**:已出视频的镜整集续跑时跳过,不重出不计价——shots_total = 这次计价的镜数(不是集内总镜数),shots_already_done = 已出视频、这次跳过的镜数。例外:场景组只要有一镜没出视频就**整组重出**,组内已出的镜同样计价。全部已出视频 ⇒ 400(没有可派发的镜,要重出某镜用 regenerate_shot_video)。报价之后若有镜的视频被清空(变成待出视频),generate_videos 会 409 要求重新报价,不按报价外的镜扣费。\n★**按镜指定视频引擎**:传 shot_engines={分镜id: 引擎} 即只为这些镜、这一次整集生成换引擎(不改剧级 video_engine,其余镜照旧)。报价按它逐镜计价,quote_id 把引擎钉死,generate_videos 派发的就是它——要改引擎必须重新报价。回执 shot_engines = 实际生效的映射;shot_engines_ungrouped = 因含指定镜而**拆成逐镜出**的场景组(场景组的时长与多关键帧是按剧引擎规划的,换引擎整组出会丢镜/丢关键帧;拆组后组内其余镜仍按剧引擎逐镜出,失去组内一次成片的连贯性,所以别为一镜去拆一个好好的组——先看 get_scene_group_plan)。所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;拆成逐镜的场景组只计没出视频的组员。只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
+  "generate_videos": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\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。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
   "compose_episode": "把某一集所有镜头视频拼成一条成片(终拼)。**免费**(纯拼接,无需报价确认),后台异步。发起前有终拼预检:缺视频的镜或仍在生成中的视频任务会 400 硬阻断并列出问题镜(blockers),补齐后重试;确要拼部分成片传 force=true(缺视频镜被跳过,成片缺镜,留痕)。响应里的 advisories(时长偏差/孤儿任务/缺TTS/post_production_pending 后期特效未完成)只提醒不阻断,建议逐条处理后再拼。发起后用 get_final_cut 轮询。\n★【视频与配音审查硬闸·免费】本步前必须先调 review_videos:把返回的 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_videos 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。\n★★【成片前自检·review_videos 通过后、compose_episode 之前】别靠反复导出整片、手工试转场来找问题——逐镜与接缝的问题有专门工具,拼之前按序过一遍:①这一集换过定妆图 / 设定图 / 场景图 / 镜头帧 → 先 get_stale_portrait_frames(episode_id,免费)看哪些镜的在用帧还基于旧资产,拿不准该用哪一版的镜再 get_asset_versions(storyboard_id,免费)逐镜看版本与依赖(unknown 是证据不足、不是已过期;重出要付费,清单讲给客户由客户定);②scan_intra_shot_cuts(episode_id,免费)查厂商在单镜内自行硬切的镜;③逐镜 recommend_trim_window(storyboard_id,免费)看冻结尾段与有效动作区间(组内镜返回 applicable=false,跳过),有推荐就 trim_shot 应用(免费);④audit_seams(episode_id)查相邻镜接缝的剪辑连续性:默认 dry_run 只列待审范围(免费),真执行按实际文本 token 计费,讲给客户、客户明确接受后才带 dry_run:false + confirm_usage_billing:true,结果看 get_storyboards 的 seam_review;⑤再 compose_episode。拼完成片发现跳切 / 拖尾 / 接不上,回到这几个工具按镜定位后只修那几镜,别整片反复导出试错。这些都是提示性检查,不过闸;裁剪与接缝审核不让 review_videos 的 token 失效。\n★【完成后质检·免费】成片出来后跑 review_final_cut(缺镜/字幕放不下/身份锚/跳轴/错别字,proofread=false 则不扣费),结论讲给客户;客户确认后才 confirm_delivery_acceptance(交付验收任何执行模式都须客户明确同意,托管也不例外)。force 只越过终拼预检,不越过审查闸。",
   "get_final_cut": "查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。★bgm_stale=true 表示配乐在成片之后生成/改动、尚未进成片:重新 compose_episode(免费)即可,别用 re-render。★若设过当前交付版(register_external_delivery 登记的外部版,或 set_current_delivery 指定的平台版),另返回 delivery——那才是客户实际收到的一版;download_url 仍是平台最新一次拼的成片。要看每一版成片用了什么、哈希是多少,用 list_deliveries。",
   "get_export": "查某一集导出/母版状态(成片终拼后的可下载母版)。免费。",
@@ -162,6 +162,10 @@
   "update_bgm_cue": "调某一段配乐的音量、淡入淡出与起点(免费)。换曲目或改覆盖镜号范围用 generate_bgm 重新生成。★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db;想从曲子的高潮部分开始→设 track_offset_ms;想等这段第一镜开口之后再进→设 start_shift_ms。改完 compose_episode 重新合成才生效。",
   "get_bgm_prompt_guide": "取「AI 配乐提示词」的书写规范:两个档位怎么选、该写哪些维度(附可照抄的示例)、哪些是写了也不会生效的硬限制(纯器乐/时长/不做音效/不复刻具体曲目)、常见写坏的方式。免费,纯静态,与具体剧目无关——写 generate_bgm 的 prompt 之前先读它,别自己猜。也适合直接把要点转述给客户看。",
   "set_shot_name_card": "给某一镜加/改/清「版式字卡」(终拼时烧进成片,含预览一致的书法字体与朱红印章)。name 传空字符串=清除本镜字卡。免费(纯数据,填了就显示)。两种用法:①不填 orient/placement/font_size = 角色名卡(画面侧边单列竖排人物名,适合群像出场镜);②填了其中任意一个 = 通用版式字卡,name 可以是**整句台词或旁白**(按标点自动切列、按最高列拟合字号)。placement=\"auto\" 会按背景亮度与粗糙度自动挑位置(躲开人脸/亮部);orient=\"auto\" 在背景太花时自动回退横排。③position=\"subtitle\" = 叙事字卡,与对白字幕同位同样式,可配 start_ms 从镜中段出现(无对白的镜最合适,避免与对白字幕重叠)。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。★别自己下载视频叠字再上传——那会绕开渲染机字体与印章素材,预览/成片不一致。",
+  "get_shot_verse_cards": "读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+  "set_shot_verse_cards": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。",
+  "get_theme_songs": "读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+  "set_theme_songs": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。",
   "extract_segment_to_library": "把某一镜（或某集成片）的某个时间区间抽出来，存成可复用的素材，进我的素材库。免费（纯剪切，不走厂商）。典型用法:闪回/回忆蒙太奇——画面全用已有镜头，边际成本为 0。区间是相对**该来源视频**的秒数;末端超出片长会自动夹回来并在 span 里回显实际区间。同源同区间重复调用会命中内容哈希、复用已有素材（reused=true），不会在库里堆重复行。★别自己下载视频再用本地 ffmpeg 切——厂商产物的 GOP 长达 10s，按关键帧切必然偏，这里走的是平台已经趟平的精确切点。",
   "get_bgm_status": "查某集 AI 配乐生成状态:running(是否在生成)+已入库的配乐轨列表(track/覆盖镜段/淡入淡出)+cue 数。免费。配乐 done 后需重新 compose_episode 才进成片。",
   "translate_subtitles": "把某集字幕翻译成第二语言并开启双语。后台异步,按用量后付不欠费。",

package/dist/tools/guide-data.js

@@ -278,9 +278,9 @@ export const PIPELINE = [
     },
     {
         step: '9 音频',
-        tools: ['assign_voices', 'generate_tts(仅 use_clip_audio=false)', 'clone_voice', 'generate_bgm', 'get_bgm_plan', 'quote_bgm_candidates', 'select_bgm_candidate', 'get_bgm_status', 'generate_sfx', 'lipsync_shot', 'lipsync_episode', 'get_lipsync_status', 'set_shot_name_card'],
+        tools: ['assign_voices', 'generate_tts(仅 use_clip_audio=false)', 'clone_voice', 'generate_bgm', 'get_bgm_plan', 'quote_bgm_candidates', 'select_bgm_candidate', 'get_bgm_status', 'generate_sfx', 'lipsync_shot', 'lipsync_episode', 'get_lipsync_status', 'set_shot_name_card', 'set_shot_verse_cards(诗句/歌词字卡·黑底结语卡·滚动片尾名单)', 'set_theme_songs(带人声的片头/片尾/插曲,台词时压低或切伴奏)'],
         billing: '混合',
-        note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。',
+        note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。国风电影感短片的诗句字卡与主题曲在平台内完成(compose_episode 时烧录/混音),别下载成片外挂后期。',
     },
     {
         step: '10 成片与交付',

package/dist/tools/produce.js

@@ -79,6 +79,14 @@ const REVIEW_GATE_HINT = (tool, layer) => `\n★【${layer}审查硬闸·免费
     `★灰度剧还要你(agent)亲自质检:按 ${tool} 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用` +
     `(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。`;
 /** 五个审查工具共用:平台审查之外,外部 agent 亲自看素材的质检(2026-10-14 用户拍板)。 */
+/** review_frames / quote_videos / generate_videos 共用：未接缝提示（与 chain_frames dry_run 同一份计划，只提示不拦）。 */
+const UNCHAINED_SEAM_HINT = '★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,' +
+    'quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),' +
+    'status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)' +
+    '/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)' +
+    '/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;' +
+    'video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。' +
+    '出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。';
 const AGENT_QC_HINT = '\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):' +
     '只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;' +
     '共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。' +
@@ -846,7 +854,7 @@ export function registerProduceTools(server, client) {
         'seam_broken(接过但没接上,或上一镜尾帧在衔接之后又重生过),shots 是「与上一镜的缝有问题」的那一镜。出视频前修最便宜——视频按首帧生成,' +
         '首帧与上镜尾帧对不上,成片就是一次跳切。修法看 action(整集 chain_frames 先 dry_run;单道 chain_shot_from_prev / chain_shot_from)。' +
         '★有相邻镜时响应还带 seam_direction_advisory(提示性,不影响 review_token):相邻镜方向对照(主体跳边/运动反向/景别跳级)的已有结论;' +
-        '还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。' + AGENT_QC_HINT, { episode_id: z.number().int().positive(), base_review_token: BASE_REVIEW_ARG }, async ({ episode_id, base_review_token }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/frames`, base_review_token ? { base_review_token } : undefined)));
+        '还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。' + UNCHAINED_SEAM_HINT + AGENT_QC_HINT, { episode_id: z.number().int().positive(), base_review_token: BASE_REVIEW_ARG }, async ({ episode_id, base_review_token }) => jsonResult(await client.producePost(`/episodes/${episode_id}/review/frames`, base_review_token ? { base_review_token } : undefined)));
     server.tool('review_assets', '【资产层硬闸·免费】审查本集**出镜**用到的角色形象图、场景图、道具图——覆盖与质量:' +
         '出镜角色缺定妆图 / 缺设定图 / 还在生成 / 生成失败 / 设定图被一致性闸拒收(hint 带拒收理由);' +
         '场景缺空景基板;分镜引用的道具缺道具图 / 被拒;道具图与本镜时代形制冲突;缺色彩脚本(warning)。' +
@@ -1047,13 +1055,13 @@ export function registerProduceTools(server, client) {
         '且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。' +
         '指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;' +
         '拆成逐镜的场景组只计没出视频的组员。' +
-        '只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。', {
+        '只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。' + UNCHAINED_SEAM_HINT, {
         episode_id: z.number().int().positive(),
         shot_engines: z.record(z.string().regex(/^\d+$/), z.enum(VIDEO_ENGINES)).optional().describe('可选:按镜指定引擎 {分镜id: 引擎}(分镜 id 见 get_storyboards)。缺省=全部跟随剧 video_engine'),
     }, async ({ episode_id, shot_engines }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/quote`, shot_engines ? { shot_engines } : {})));
     server.tool('generate_videos', '确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。' +
         '要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。' +
-        REVIEW_GATE_HINT('review_frames', '镜头图片') + CONFIRM_HINT + VIDEO_QC_HINT, {
+        REVIEW_GATE_HINT('review_frames', '镜头图片') + CONFIRM_HINT + VIDEO_QC_HINT + UNCHAINED_SEAM_HINT, {
         episode_id: z.number().int().positive(),
         quote_id: z.string().describe('来自 quote_videos'),
         ...REVIEW_ARGS,
@@ -2009,6 +2017,42 @@ export function registerProduceTools(server, client) {
         ...(start_ms !== undefined ? { start_ms } : {}),
         ...(position !== undefined ? { position } : {}),
     })));
+    server.tool('get_shot_verse_cards', '读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/verse-cards`)));
+    server.tool('set_shot_verse_cards', '给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。', {
+        storyboard_id: z.number().int().positive(),
+        cards: z.array(z.object({
+            text: z.string().min(1).describe('字卡文字;换行=另起一列(竖排)/一行(横排);≤300 字'),
+            orient: z.enum(['vertical', 'horizontal']).optional().describe('默认 vertical 竖排(从右往左);滚动名单自动横排'),
+            position: z.enum(['left', 'right', 'center']).optional().describe('默认 right;滚动名单默认 center'),
+            start_ms: z.number().int().min(0).max(60000).optional().describe('镜内起点毫秒(相对本镜开头),默认 0'),
+            duration_ms: z.number().int().min(500).max(60000).optional().describe('显示时长,默认 4000;超出本镜部分截掉'),
+            fade_in_ms: z.number().int().min(0).max(5000).optional().describe('淡入毫秒,默认 600'),
+            fade_out_ms: z.number().int().min(0).max(5000).optional().describe('淡出毫秒,默认 600'),
+            font_size: z.number().int().min(20).max(200).optional().describe('字号上限(输出像素),默认 64;放不下自动缩小'),
+            font: z.string().optional().describe('字体名,默认行书 Zhi Mang Xing;规整宋体填 Noto Serif CJK SC(渲染机已装的才生效)'),
+            backdrop: z.enum(['none', 'black']).optional().describe('black = 整屏黑底结语卡'),
+            motion: z.enum(['static', 'scroll_up']).optional().describe('scroll_up = 自下而上滚动的片尾名单'),
+        })).max(6).describe('整组字卡(顺序即渲染顺序);[] = 清空本镜字卡'),
+    }, async ({ storyboard_id, cards }) => jsonResult(await client.producePut(`/storyboards/${storyboard_id}/verse-cards`, { cards })));
+    server.tool('get_theme_songs', '读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/theme-songs`)));
+    server.tool('set_theme_songs', '给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。', {
+        episode_id: z.number().int().positive(),
+        songs: z.array(z.object({
+            audio_url: z.string().optional().describe('原曲(带人声)https 地址或 static/ 路径;与 track_id 二选一'),
+            track_id: z.number().int().positive().optional().describe('曲库/平台作曲的曲目 id(本人上传或公开的)'),
+            instrumental_url: z.string().optional().describe('同一首歌的伴奏轨(与原曲逐采样对齐);给了才能「台词段只留伴奏」'),
+            placement: z.enum(['opening', 'ending', 'range']),
+            sb_from: z.number().int().positive().optional().describe('起镜号(storyboard_number)'),
+            sb_to: z.number().int().positive().optional().describe('止镜号(含)'),
+            track_offset_ms: z.number().int().min(0).optional().describe('从曲内第几毫秒开始放(跳过前奏)'),
+            gain_db: z.number().min(-30).max(6).optional().describe('主题曲音量 dB,默认 -8'),
+            fade_in_ms: z.number().int().min(0).max(10000).optional().describe('默认 1000'),
+            fade_out_ms: z.number().int().min(0).max(10000).optional().describe('默认 2000'),
+            dialogue_mode: z.enum(['duck', 'instrumental']).optional().describe('有台词时:duck=整首压低;instrumental=切伴奏(需 instrumental_url)'),
+            duck_db: z.number().min(-40).max(0).optional().describe('duck 模式压低量 dB,默认 -18'),
+            bgm_yield: z.boolean().optional().describe('播放区间里配乐让开,默认 true'),
+        })).max(3).describe('整组主题曲;[] = 清空'),
+    }, async ({ episode_id, songs }) => jsonResult(await client.producePut(`/episodes/${episode_id}/theme-songs`, { songs })));
     server.tool('extract_segment_to_library', '把某一镜（或某集成片）的某个时间区间抽出来，存成可复用的素材，进我的素材库。免费（纯剪切，不走厂商）。' +
         '典型用法:闪回/回忆蒙太奇——画面全用已有镜头，边际成本为 0。' +
         '区间是相对**该来源视频**的秒数;末端超出片长会自动夹回来并在 span 里回显实际区间。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.213",
-    "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.213 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.215",
+    "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.215 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -8413,7 +8413,7 @@
       "post": {
         "operationId": "review_frames",
         "summary": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染",
-        "description": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / generate_shot_frame 单镜重生)再复审。★还会报**镜间接缝**(warning,不拦):code=seam_unchained(标了连续却从没做过首尾帧衔接,或发起的衔接重生没落地 / 衔接后首帧又被重生)/seam_broken(接过但没接上,或上一镜尾帧在衔接之后又重生过),shots 是「与上一镜的缝有问题」的那一镜。出视频前修最便宜——视频按首帧生成,首帧与上镜尾帧对不上,成片就是一次跳切。修法看 action(整集 chain_frames 先 dry_run;单道 chain_shot_from_prev / chain_shot_from)。★有相邻镜时响应还带 seam_direction_advisory(提示性,不影响 review_token):相邻镜方向对照(主体跳边/运动反向/景别跳级)的已有结论;还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
+        "description": "【第③道硬闸·免费】审查镜头图片层:角色身份锚覆盖(缺定妆图的角色在镜头里必漂)、出图失败率、孤儿角色变体、场景图被人物污染。★generate_videos 之前必须先跑本工具——出视频是全链最贵的一步,拿着漂移的首帧整集出视频是最典型的废片形态。按 findings.action 修完(多为 generate_character_portraits / generate_shot_frame 单镜重生)再复审。★还会报**镜间接缝**(warning,不拦):code=seam_unchained(标了连续却从没做过首尾帧衔接,或发起的衔接重生没落地 / 衔接后首帧又被重生)/seam_broken(接过但没接上,或上一镜尾帧在衔接之后又重生过),shots 是「与上一镜的缝有问题」的那一镜。出视频前修最便宜——视频按首帧生成,首帧与上镜尾帧对不上,成片就是一次跳切。修法看 action(整集 chain_frames 先 dry_run;单道 chain_shot_from_prev / chain_shot_from)。★有相邻镜时响应还带 seam_direction_advisory(提示性,不影响 review_token):相邻镜方向对照(主体跳边/运动反向/景别跳级)的已有结论;还没观察过的接缝要先 audit_seam_directions dry_run 报价,客户同意后再执行。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。\n★【增量复审·省时省量】review_storyboards / review_frames / review_assets 可带 base_review_token(上一张已交质检且 verdict=pass 的本层 token):只把变更镜及其相邻镜列进 agent_qc.materials、findings 只回这些镜(incremental.applied=true,另有 findings_hidden 计数),质检报告只需覆盖它们;共享资产变了、base 没质检通过时自动退回整集(incremental.reason 说明原因)。改一两镜后别整集重审。\n★【agent 亲自质检·免费】返回的 agent_qc 里有本层清单(checklist)和本集要看的素材(materials,每件一个 ref,图/视频给链接)。平台只判「有没有、在不在、被没被拒」,「像不像、对不对、好不好」要你自己看:图片下载打开看、视频至少抽开头/中间/结尾帧、文本用 tool 通读。逐条回答清单(ok / issue / na,issue 写明哪件什么问题),看过的每个 ref 都列进 inspected,调 submit_qc_report 提交;质检结论原样讲给客户。agent_qc.required=true 时没提交报告这张 review_token 进不了下一步(400 agent_qc_required),报告有问题与平台 error 同样默认拦。\n★【客户验收项】review_frames / review_videos 会把客户登记的具体要求(add_acceptance_criteria)追加进 checklist(id 以 req: 开头),附 acceptance_criteria:平台通用审查不知道这些要求,通过了不代表满足——逐条亲眼核对后在 submit_qc_report 里答,结论讲给客户,由客户 confirm_acceptance_criterion 确认。",
         "tags": [
           "episodes"
         ],
@@ -10277,6 +10277,199 @@
         }
       }
     },
+    "/episodes/{episode_id}/theme-songs": {
+      "get": {
+        "operationId": "get_theme_songs",
+        "summary": "读某一集的主题曲设置(免费)",
+        "description": "读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_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"
+          }
+        }
+      },
+      "put": {
+        "operationId": "set_theme_songs",
+        "summary": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)",
+        "description": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "songs": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "audio_url": {
+                          "type": "string",
+                          "description": "原曲(带人声)https 地址或 static/ 路径;与 track_id 二选一"
+                        },
+                        "track_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "曲库/平台作曲的曲目 id(本人上传或公开的)"
+                        },
+                        "instrumental_url": {
+                          "type": "string",
+                          "description": "同一首歌的伴奏轨(与原曲逐采样对齐);给了才能「台词段只留伴奏」"
+                        },
+                        "placement": {
+                          "type": "string",
+                          "enum": [
+                            "opening",
+                            "ending",
+                            "range"
+                          ]
+                        },
+                        "sb_from": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "起镜号(storyboard_number)"
+                        },
+                        "sb_to": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "止镜号(含)"
+                        },
+                        "track_offset_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "description": "从曲内第几毫秒开始放(跳过前奏)"
+                        },
+                        "gain_db": {
+                          "type": "number",
+                          "minimum": -30,
+                          "maximum": 6,
+                          "description": "主题曲音量 dB,默认 -8"
+                        },
+                        "fade_in_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 10000,
+                          "description": "默认 1000"
+                        },
+                        "fade_out_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 10000,
+                          "description": "默认 2000"
+                        },
+                        "dialogue_mode": {
+                          "type": "string",
+                          "enum": [
+                            "duck",
+                            "instrumental"
+                          ],
+                          "description": "有台词时:duck=整首压低;instrumental=切伴奏(需 instrumental_url)"
+                        },
+                        "duck_db": {
+                          "type": "number",
+                          "minimum": -40,
+                          "maximum": 0,
+                          "description": "duck 模式压低量 dB,默认 -18"
+                        },
+                        "bgm_yield": {
+                          "type": "boolean",
+                          "description": "播放区间里配乐让开,默认 true"
+                        }
+                      },
+                      "required": [
+                        "placement"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "maxItems": 3,
+                    "description": "整组主题曲;[] = 清空"
+                  }
+                },
+                "required": [
+                  "songs"
+                ]
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/transitions": {
       "post": {
         "operationId": "generate_transitions",
@@ -10437,7 +10630,7 @@
       "post": {
         "operationId": "generate_videos",
         "summary": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)",
-        "description": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\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。",
+        "description": "确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。\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。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
         "tags": [
           "episodes"
         ],
@@ -10512,7 +10705,7 @@
       "post": {
         "operationId": "quote_videos",
         "summary": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)",
-        "description": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。\n★**只计这次真会派发的镜**:已出视频的镜整集续跑时跳过,不重出不计价——shots_total = 这次计价的镜数(不是集内总镜数),shots_already_done = 已出视频、这次跳过的镜数。例外:场景组只要有一镜没出视频就**整组重出**,组内已出的镜同样计价。全部已出视频 ⇒ 400(没有可派发的镜,要重出某镜用 regenerate_shot_video)。报价之后若有镜的视频被清空(变成待出视频),generate_videos 会 409 要求重新报价,不按报价外的镜扣费。\n★**按镜指定视频引擎**:传 shot_engines={分镜id: 引擎} 即只为这些镜、这一次整集生成换引擎(不改剧级 video_engine,其余镜照旧)。报价按它逐镜计价,quote_id 把引擎钉死,generate_videos 派发的就是它——要改引擎必须重新报价。回执 shot_engines = 实际生效的映射;shot_engines_ungrouped = 因含指定镜而**拆成逐镜出**的场景组(场景组的时长与多关键帧是按剧引擎规划的,换引擎整组出会丢镜/丢关键帧;拆组后组内其余镜仍按剧引擎逐镜出,失去组内一次成片的连贯性,所以别为一镜去拆一个好好的组——先看 get_scene_group_plan)。所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;拆成逐镜的场景组只计没出视频的组员。只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。",
+        "description": "报价:给某一集批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。\n★**只计这次真会派发的镜**:已出视频的镜整集续跑时跳过,不重出不计价——shots_total = 这次计价的镜数(不是集内总镜数),shots_already_done = 已出视频、这次跳过的镜数。例外:场景组只要有一镜没出视频就**整组重出**,组内已出的镜同样计价。全部已出视频 ⇒ 400(没有可派发的镜,要重出某镜用 regenerate_shot_video)。报价之后若有镜的视频被清空(变成待出视频),generate_videos 会 409 要求重新报价,不按报价外的镜扣费。\n★**按镜指定视频引擎**:传 shot_engines={分镜id: 引擎} 即只为这些镜、这一次整集生成换引擎(不改剧级 video_engine,其余镜照旧)。报价按它逐镜计价,quote_id 把引擎钉死,generate_videos 派发的就是它——要改引擎必须重新报价。回执 shot_engines = 实际生效的映射;shot_engines_ungrouped = 因含指定镜而**拆成逐镜出**的场景组(场景组的时长与多关键帧是按剧引擎规划的,换引擎整组出会丢镜/丢关键帧;拆组后组内其余镜仍按剧引擎逐镜出,失去组内一次成片的连贯性,所以别为一镜去拆一个好好的组——先看 get_scene_group_plan)。所选引擎必须支持本剧分辨率(seedance-2.5 只有 480p/720p;hailuo-3 只有 720p/1080p;wan3.0/wan3.0-prime 480p~1080p),且镜头时长不超过该引擎单镜上限(seedance-2.5/wan3.0 30s,hailuo-3 15s),否则 400(超长会被厂商截断,要么换引擎要么 split_shot)。指定引擎的镜必须这次会出视频:已出视频的镜整集生成不会重出,给它指定引擎 ⇒ 400;拆成逐镜的场景组只计没出视频的组员。只想重出个别已出过视频的镜,用 quote_regenerate_shot_video 的 model 更省。★响应可能带**未接缝提示**(不影响 review_token / 报价 / 状态码):review_frames 与 generate_videos 是 unchained_seam_advisory,quote_videos 是 advisories 里 code=unchained_seams。seams 列的是 chain_frames 会接、却还没接上的相邻缝(from_shot→to_shot),status=no_stamp(从没接过)/ pending(发起过衔接、还没落地或审计未出结论)/ stale_anchor(上次承接的锚已失效:上一镜尾帧在衔接之后又被重生过,需要重接)/ join_failed(上次发起的衔接重生被拒 / 失败 / 落选,没落地)/ audit_failed(衔接落地但审计判不连续,看 get_storyboards 的 seam_failed_dims)/ first_frame_regenerated(接缝审过之后下镜首帧又被重出、没走承接路径,原衔接已不算数)/ not_linked(规划器判没接上、原因证据不足);都按计划重接即可;video_locked 是下镜已出视频的同类缝,chain_frames 不再改它们,只能逐镜 chain_shot_from_prev / chain_shot_from 换首帧后 regenerate_shot_video(都先报价)。出视频前看到 seams 就先 chain_frames(dry_run:true) 把计划与报价告诉客户,客户同意再执行,执行后重调 review_frames。",
         "tags": [
           "episodes"
         ],
@@ -15621,6 +15814,199 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/verse-cards": {
+      "get": {
+        "operationId": "get_shot_verse_cards",
+        "summary": "读这一镜的诗句/歌词字卡现值(免费)",
+        "description": "读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=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"
+          }
+        }
+      },
+      "put": {
+        "operationId": "set_shot_verse_cards",
+        "summary": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)",
+        "description": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。",
+        "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": {
+                  "cards": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "text": {
+                          "type": "string",
+                          "minLength": 1,
+                          "description": "字卡文字;换行=另起一列(竖排)/一行(横排);≤300 字"
+                        },
+                        "orient": {
+                          "type": "string",
+                          "enum": [
+                            "vertical",
+                            "horizontal"
+                          ],
+                          "description": "默认 vertical 竖排(从右往左);滚动名单自动横排"
+                        },
+                        "position": {
+                          "type": "string",
+                          "enum": [
+                            "left",
+                            "right",
+                            "center"
+                          ],
+                          "description": "默认 right;滚动名单默认 center"
+                        },
+                        "start_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 60000,
+                          "description": "镜内起点毫秒(相对本镜开头),默认 0"
+                        },
+                        "duration_ms": {
+                          "type": "integer",
+                          "minimum": 500,
+                          "maximum": 60000,
+                          "description": "显示时长,默认 4000;超出本镜部分截掉"
+                        },
+                        "fade_in_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 5000,
+                          "description": "淡入毫秒,默认 600"
+                        },
+                        "fade_out_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 5000,
+                          "description": "淡出毫秒,默认 600"
+                        },
+                        "font_size": {
+                          "type": "integer",
+                          "minimum": 20,
+                          "maximum": 200,
+                          "description": "字号上限(输出像素),默认 64;放不下自动缩小"
+                        },
+                        "font": {
+                          "type": "string",
+                          "description": "字体名,默认行书 Zhi Mang Xing;规整宋体填 Noto Serif CJK SC(渲染机已装的才生效)"
+                        },
+                        "backdrop": {
+                          "type": "string",
+                          "enum": [
+                            "none",
+                            "black"
+                          ],
+                          "description": "black = 整屏黑底结语卡"
+                        },
+                        "motion": {
+                          "type": "string",
+                          "enum": [
+                            "static",
+                            "scroll_up"
+                          ],
+                          "description": "scroll_up = 自下而上滚动的片尾名单"
+                        }
+                      },
+                      "required": [
+                        "text"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "maxItems": 6,
+                    "description": "整组字卡(顺序即渲染顺序);[] = 清空本镜字卡"
+                  }
+                },
+                "required": [
+                  "cards"
+                ]
+              }
+            }
+          }
+        },
+        "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}/video-lock": {
       "post": {
         "operationId": "lock_shot_video",

package/package.json

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