@starreel/mcp 0.1.150 → 0.1.153

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.150",
-    "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.150 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.153",
+    "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.153 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -5905,7 +5905,7 @@
       "post": {
         "operationId": "extract_assets",
         "summary": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)",
-        "description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★灰度剧还要你(agent)亲自质检:按 review_script 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。\n★【完成后质检】提取完用 get_characters / get_scenes / get_props 核对档案(名字、外貌、时代)与客户剧本一致;定妆图/设定图/场景图/道具图出完后由 review_assets 统一审覆盖与质量。",
+        "description": "从可拍稿提取角色/场景/道具(一次写三表,是下游一致性的地基)。后台异步,文本步后付不欠费。前置:已 rewrite_script 产出改写稿(新项目强制;人物档案从改写稿提取才与剧本、分镜自洽)。★分钟级后台任务;用 get_run_status 判断是否还在跑,别拿 60 秒当失败判据。\n★【改写稿审查硬闸·免费】本步前必须先调 review_script:把返回的 findings 逐条原样告诉客户(每条带 code=问题类型、shots=命中镜号、action=该调哪个工具修),再把 review_token 传进本工具。未审查会被 400 拒。审查后又改了内容 → token 自动失效,复审一次即可(仍免费)。有 error 时默认拦截;客户知情并坚持照现状继续,才带 acknowledge_review:true——带病推进大概率产出废片且照常扣费,不要替客户做这个决定。★灰度剧还要你(agent)亲自质检:按 review_script 返回的 agent_qc 逐件看素材、逐条答清单,调 submit_qc_report 提交后这张 token 才能用(没交 → 400 agent_qc_required;报告有问题 → 与 error 同样默认拦)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。★换服装改的是结构化绑定:update_shot 的 active_wardrobe_id(整镜)/ appearance_wardrobes(多人逐角色),可覆盖、可清空——改文字描述不换衣服,也不用让客户去网页改。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。\n★【完成后质检】提取完用 get_characters / get_scenes / get_props 核对档案(名字、外貌、时代)与客户剧本一致;定妆图/设定图/场景图/道具图出完后由 review_assets 统一审覆盖与质量。",
         "tags": [
           "episodes"
         ],
@@ -7564,7 +7564,7 @@
       "post": {
         "operationId": "rewrite_script",
         "summary": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)",
-        "description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
+        "description": "AI 改写:把原始剧本改写成可拍稿(读 content → 写 script_content)。按项目类型自动选改写 agent★保真自动路由:原稿已是剧本形态时自动走两步保真(台词逐句机器锁定、AI 不加戏,剧作缺口进 dramaturgy_suggestions 由客户决定);原稿是小说/大纲则走创作型改写。(广告走 ad 改写;MV 不走标准改写会被拦)。后台异步(分钟级),文本步按 token 后付、不欠费,无需报价。完成后用 get_script 审阅、edit_rewritten_script 改稿。★典型耗时 2~4 分钟(生产实测 ≈169 秒)。**60 秒内查不到结果是正常的,不是失败**——用 get_run_status 判断还在不在跑,别急着重发。★★**本工具是\"从原稿整篇重来\",不是\"再改一版\"**:已有可拍稿时重跑会把当前稿连同已做的所有修正一起覆盖,而且新一版**不保证保留旧版已经改好的地方**(生产三版实测:上一版拆好的长旁白段下一版又合回去、上一版正确的年代服装下一版漂走)。响应里的 overwrites_existing_script=true 就是这个意思。所以**首次改写成功之后,后续所有修改一律用 edit_rewritten_script 点改**——免费、秒级、只动指定的那几场,其余逐字不变,结果确定不抽卡;只有\"要一个完全不同的版本\"才重跑本工具。误重跑后用 get_script(include_previous=1) 取回上一版。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。★换服装改的是结构化绑定:update_shot 的 active_wardrobe_id(整镜)/ appearance_wardrobes(多人逐角色),可覆盖、可清空——改文字描述不换衣服,也不用让客户去网页改。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
         "tags": [
           "episodes"
         ],
@@ -8008,7 +8008,7 @@
       "put": {
         "operationId": "set_script",
         "summary": "给某一集设置**原始剧本**(content)",
-        "description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
+        "description": "给某一集设置**原始剧本**(content)。这是 AI 改写的输入,不是最终可拍稿。免费。梗概/大纲/自己写好的成品稿都放这里,设完**必须调 rewrite_script 做 AI 改写**——不能跳过改写直接把稿子贴进 edit_rewritten_script(会被拒)。★三档执行策略(别把三档混着问客户):①【基础项目设定·免费·必做地基·建剧即设好,别建空壳】project_type/setting_brief(世界观·ERA LOCK)/ethnicity(族裔)/画幅分辨率,以及一致性锚 cinematography_prompt(摄影DNA)·art_bible(美术圣经)·visual_lock(视觉锁定)——全免费,是驱动全链一致性的地基;不设好,后续所有生成都跑偏、返工重花钱。用 create_drama/update_project_settings 直接设。★visual_lock/art_bible 只写画面级/世界级锁(镜头语言·环境·美术基调·禁入元素),**绝不为具体角色钉服装/发型/外观细节**——角色外观的唯一真相源是 extract_assets 产出的人物档案(要改走 update_character);两处都写必然互相矛盾,定妆图跟档案、设定图跟视觉锁,一致性闸按定妆图拒收 → 设定图/镜头帧**结构性连拒**,重掷多少次都过不了、纯白花钱。★★【时代契约·免费·非现代题材出图前必设】setting_brief 里的世界观是**自由文本**,只能提供背景、压不住画面;真正能压过视觉锁的是**结构化时代契约**:用 set_era_contract 设本集档位(modern/republican/historical/fantasy),get_era_contract 读现值。**不设就是空着**——平台只能靠提示词正文堆字对抗,现代物件混进古代画面、场景图画成别的时代,基本都由这里空着导致。★仙侠/奇幻/仙境类**必须填 fantasy,别填 historical**:后者要求考据写实,会把发光灵气、悬浮地貌、非人化形一并判成「不合时代」,把画面往写实古代拽。某一场要破例(如奇幻世界里一场现代回忆)用 update_scene 的 era_contract 单独覆写,场级压过集级。★★【逐环节审查协议·全部免费·这是防废片的主线,不是可选项】每个环节产出后先审查、把结论原样告诉客户,再进下一步。**五道硬闸(不过会被 400 拒;④⑤与 agent 质检见下文)**:①改写稿产出后 → review_script(在 extract_assets / generate_storyboards 之前);②分镜产出后 → review_storyboards(在 generate_frames 之前);③镜头图片产出后 → review_frames(在 generate_videos 之前)。每次审查返回 review_token,把它随下游收费工具一起传;findings 逐条讲给客户(code=问题类型·shots=命中镜号·action=该调哪个工具修),按 action 修完后**复审**再走。审查后又改了内容 → token 自动失效,复审一次即可(免费)。有 error 时默认拦截,只有客户明确知情并坚持才带 acknowledge_review:true——别替客户做这个决定。**软引导(不阻断但强烈建议,同样免费)**:出图/出视频前跑 run_precheck(揪出必被厂商拒的镜,防白花钱)——★**要跑全集就先 run_drama_precheck**(剧级汇总·免费·只读):一次拿到每集问题数与 attention(该先修哪几集),按它定优先级,再对那几集跑 run_precheck 拿逐条明细;别一集一集盲扫。注意它的 not_covered——剧级跳过唯一要看图的那道 lint,「全剧 0 条」≠「全查过了」。★揪出来之后别自己盲改:plan_precheck_fix 让平台算出提案 → 逐条讲给客户 → 客户点头后 apply_precheck_fix 落库;分镜后跑 get_health_report;定妆图出完用 get_characters 核对每个出场角色都有 image/sheet;出帧后用 get_storyboards 看 frame_status 与 fail_reason/fail_hint(failed 的镜先修再往下,别带着废帧出视频);出视频后同样看 video_status;成片前用 get_pipeline_status 确认没有缺镜。★**禁止一路 generate 到底**:不审查就连推的做法,问题会在每一层被放大,最后整集废掉重来——而重来的每一次出图/出视频都是真扣费。审查全部免费,拦下来一分钱不花。★换服装改的是结构化绑定:update_shot 的 active_wardrobe_id(整镜)/ appearance_wardrobes(多人逐角色),可覆盖、可清空——改文字描述不换衣服,也不用让客户去网页改。②【产线主干·按序不跳步·★先分镜再建资产】set_script→rewrite_script→★review_script→extract_assets→storyboards(先分镜·纯文本拆镜)→★review_storyboards→★剧本纪律(端点强制,绕不过):原始素材(梗概/大纲/成品稿都算)一律放 set_script,**必须经 rewrite_script 产出 AI 改写稿**——把自己写好的剧本直接贴进 edit_rewritten_script 绕过改写会被 400 拒(没有改写稿就没有可改的对象),extract_assets 同样要求基于改写稿。改写后的所有修改按 AI 产物的结构化格式做:改稿 edit_rewritten_script(润色/纠正)、人物档案 update_character、分镜 update_shot/replace_shot_dialogue——别回头整篇替换剧本或在设定字段里另写一套,两套真相源打架是一致性事故的头号根源。★★**改写成功一次后就别再重跑 rewrite_script**:它是从原稿整篇重来,当前稿的所有修正全丢,且新版不保证保留旧版已改好的地方(三版实测会来回摆)。要修就 edit_rewritten_script 点改(get_script 取全文 → 只改那几场、其余逐字照抄 → 提交整篇),免费秒级、结果确定;误重跑用 get_script(include_previous=1) 回捞上一版。generate_portraits_and_sheets(定妆图+设定图·分镜后建:先用 delete_character 删掉**全剧任何一集都不出场、后续集也不打算用**的出镜角色再出图——角色是剧级的,删了每一集的出帧装配都不再带它,只看本集分镜判不出来、拿不准就留着(一张定妆图的钱远小于后面某集丢身份锚);定妆图步对**所有未删的出镜角色**出图、不看分镜绑定,留着的都照常扣费;画外音角色(char_type=voiceover 的旁白/电话音)本就不出图、也没有分镜绑定,**别删**,配音还靠它)→★generate_color_script(色彩脚本·统一调色)→assign_voices(分配音色;旁白/角色库里没合适的→design_voice 按描述造一个,定样后 set_character_voice)→★quote_scene_images+generate_scene_images(空景基板·出帧前必做)→frames(默认只出首帧)→★tail_frame_plan(免费·哪几镜要独立尾帧)→frames(frame_type=last_frame)→★review_frames→videos→generate_tts→compose;★★【尾帧别跳·出帧是两趟】generate_frames 默认只出首帧。约三成的镜**末态≠首态**(大运镜/物体脱手/状态改变),这些镜需要一张独立尾帧,而判据在平台侧、你从分镜文本猜不出来——所以首帧出完必须调一次免费的 tail_frame_plan 拿逐镜清单,再 frame_type=last_frame 补上(generate_frames 的响应体里 shots_needing_last_frame 就是这个数,不为 0 别直接去 review_frames)。跳过不报错、不拦你——代价是那些镜出视频时只有首帧一个锚,末态由模型自由发挥:动作做不到位、大运镜结束又回到起点构图。生产实测 32 集里 30 集整集只出了首帧,其中 23 集一路出完了视频。★★【尾帧被 TERMINAL_DESC_GATE 拦下时:改文本,不是重试】报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」的镜,用 update_shot 把**结束时画面什么样**写进该镜 last_frame_prompt,再重出尾帧。★更好的是**别撞**:出尾帧前先 get_storyboards 看一眼,terminal_desc_missing=true 的镜整集一次就列出来了(免费),先把它们的 last_frame_prompt 补齐再出,一次都不用被拒。逐镜也能问(get_shot_prompts 同名字段),但一集几十镜别那么干。不补描述直接重试是无效的——送厂商的提示词里根本没有终态段,画出来仍是首帧那个姿态、必然再次被终态审核拒,而每次都照常扣费(生产实测:没写终态的镜尾帧成功率 9.4%,写了的 40.2%)。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★★【空景基板别跳·这一步长期被第三方漏掉】场景图是**背景锚**:同一场的每个镜头帧都锚在它上面。不出基板照样能出帧、不报错、不拦你——代价是**每个场景的第一镜完全没有背景锚**(平台的兜底补图是「发现缺图就后台补一张」,补的那张给同场景后续镜用,触发它的那一镜自己等不到),而首镜往往正是定调的那一镜;后续镜之间背景也会漂。它跟定妆图是一对:定妆图锚人、场景图锚景,缺哪个漂哪个。进度自检看 `get_pipeline_status` 的 generate_scene_images 步(completed/total),`review_storyboards` 也会在出帧前把缺口报成 scene_plate_missing。★★【设定图别跳·定妆图≠设定图】定妆图是单人单张的身份锚;设定图是平台据定妆图生成的多视角 turnaround,是镜头帧/视频的一致性根锚(换角度·换光·服装几乎全靠它)。只出定妆图照样能出帧、不报错——代价是人物一换角度就漂、服装每镜不一样。用 generate_portraits_and_sheets 一键两步(每调一次推进一步,定妆图齐了再调一次才出设定图),或定妆图后接 generate_character_sheets。进度自检看 get_pipeline_status 的 generate_character_sheets 步(completed/total,portrait_only=只有定妆图的角色数)。★客户自带图:定妆图须单人、单张单角度、无文字;场景图须空景无人、无叠加文字——set_character_portrait/upload_scene_image 会自动检查、不合规 422 拒收。★别先建角色形象/道具设定图/动作模板再分镜——分镜是纯文本步、不依赖任何图;分镜后阵容才定,先删不出场角色再出图才省(动作模板本就必须分镜后)。收费步照现有 quote 报价确认流程。广告另需 add_product+generate_product_sheet;MV 走 set_mv_lyrics→generate_mv_story→generate_mv_script(没有现成歌曲:set_mv_lyrics 后先 suggest_mv_song_styles→quote_mv_song→generate_mv_song→get_mv_song→select_mv_song)。★★【④⑤两道新硬闸 + agent 亲自质检】④资产层:定妆图/设定图/场景图/道具图出完 → review_assets(在 generate_frames / generate_shot_frame 之前,它的 token 作为 asset_review_token、与分镜层 review_token 一起传);⑤视频与配音层:视频/配音/配乐出完 → review_videos(在 compose_episode 之前);成片出来后跑 review_final_cut。★每一层审查之后你还要**亲自质检**:按返回的 agent_qc 逐件看素材(图下载看、视频抽帧看、文本通读),逐条答清单,submit_qc_report 提交;灰度剧没交报告那张 review_token 进不了下一步,报告有问题与 error 同样默认拦。平台判有没有,你判像不像、对不对。★★【单镜路径同样受审查闸】:generate_shot_frame 同样要带分镜层 review_token,regenerate_shot_video 同样要带镜头图片层 review_token——别指望用逐镜工具绕开审查(实测有整集 25 镜全靠单镜出帧、一道闸都没碰到的做法,成片返工全是真扣费)。出完帧**不会**让分镜层 token 失效(指纹只看分镜内容);只有改了分镜内容——update_shot / 导入 / 增删镜 / 改角色绑定——才要复审一次(免费、秒级)。出完一镜的帧会让**镜头图片层** token 失效,下一镜 regenerate_shot_video 前 review_frames 一次即可。★★【原声剧先锁声线,再批量出视频】use_clip_audio=true(默认)时每镜嗓音由视频厂商各自采样,不锁必漂,事后统一要逐镜重出。有客户授权音源→clone_voice+set_character_voice,在 generate_videos 之前;没有→每个说话角色先用单镜工具 quote_regenerate_shot_video→regenerate_shot_video 出一镜台词较长的(generate_videos 没有按镜参数、只批量补缺视频的镜;单镜重生对还没有视频的镜同样可用),用 set_voice_anchor_from_shot 从那一镜选定声线,再出其余镜。get_pipeline_status 的 native_voice_anchor 会列出还没锁的 unanchored_speakers 和锁之前出的、需要重出的 stale_shots。★世界观概念图=默认必做(提升整剧一致性、很多第三方平台漏做这步):分镜后默认调 generate_world_concept,仍走报价确认流程(告知客户预估点数、确认再扣)——不静默扣费、也别跳过。★★【色彩脚本】generate_color_script 统一全片调色,分镜后、出帧前做;文本步无 quote_*,按用量后付。进度自检看 get_pipeline_status 的 generate_color_script,review_storyboards 会报色彩脚本缺口。★动作模板为可选实验:generate_motion_templates(动作模板提取)仅客户明确要求时在分镜后调用,文本步按用量后付。首尾帧默认不注入动作模板;缺模板无需补做,不阻碍出图、出视频或成片。视频模板可能被裁剪,不承诺送达或增益。★场景 Bible(每场景详细设定)顺序在**场景图片出图之后**——据出好的场景图完善(MCP 暂无此工具、在官网做);别在出场景图前做场景 Bible。★音频默认用视频原声(use_clip_audio 默认开、跳过 TTS 直接用 AI 视频自带声):建剧/改设定时 AI 应主动告知客户「默认用视频原声,如需 TTS 配音把 use_clip_audio 设 false」,让客户选。★图片模型默认 ChatGPT Image 2.5 Flare(gpt-image-2.5-flare·整剧统一画风):create_drama/update_project_settings 的 image_model 设,不传即默认它;可选 gpt-image-2.5-sunburst(同价·中文字形与细节更准)/gemini-3.1-flash-image(香蕉2·71点)/gemini-3-pro-image(香蕉Pro·更精细·175点)/gemini-3.1-flash-lite-image(香蕉2 Lite·便宜·31点)/doubao-seedream-5-0-260128(Seedream5.0);generate_frames 可临时覆盖某次。★2.5 按输入量计费(基础11点+每张参考图18点),香蕉/Seedream 是一口价——参考图多的镜头要把这笔算进预算。★视频引擎四选一(drama级·AI 建剧时必须主动按剧选型引导并给价差让客户定):【选型决策树】①写实真人剧→seedance-2.5(默认·指令遵循/人脸细节最强·720p 212点/秒),预算敏感可 hailuo-3(约1/3成本70点/秒·强保真编辑·但单镜约6分钟);②风格化/动画/3D卡通剧·空镜·产品镜→wan3.0(约4折84点/秒·最长30秒·最短2秒计费·单镜约2分钟),赶交付用 wan3.0-prime(126点/秒·约1分钟);③★写实真人剧绝不选 wan3.0/prime——WAN 输出侧真人脸审核在 720p+ 一致拒、重试救不回;④★★叙事剧(有对白、讲连贯故事、镜头节奏要稳的)慎选 wan3.0/prime:WAN 会在**单个分镜片内自行换机位硬切**(实测 11/12 镜有镜内跳切,对照 seedance-2.5 仅 1/6、hailuo-3 为 0/5),成片观感是「一个镜头里画面跳来跳去、切太快」;这是厂商指令遵循弱、提示词层拦不住(我方负向约束早已在其中且实测无效),事后只能换引擎重生。WAN 适合镜头本就短平快的风格化/空镜/产品镜;要稳定单镜叙事请选 seedance-2.5 或 hailuo-3。生成后可用 scan_intra_shot_cuts 核查;④b★★对白密集剧慎选 hailuo-3(与上一条的「镜内自剪」是两回事,这条讲**说不说得全台词**):原生音频引擎会念到镜头结束就停、也会自说自话,实测「台词没念完整」占比 hailuo-3 **50%**(26 镜,均为 8-30 原生音频修复之后所生成,故是引擎本身)、seedance-2.5 **23%**(294 镜);wan3.0 该维度**样本不足未测**(26 个样本全在同一修复之前,修复后仅 2 镜)——不要据此认为 WAN 差。客户报「话没说完」时先跑 scan_dialogue_coverage 分族,别默认去加长镜头(实测镜长够的镜里仍有 32% 没念全);⑤★镜长控制(所有引擎通用,WAN 上尤其明显):单镜保持 3~5 秒。镜头越长模型自由发挥空间越大——实测一个 16 秒单镜(邻镜都是 3~5 秒)在片内换了 4 次场景、人物中途消失 4 秒后又从画面边缘长出来,客户看到的就是「凭空多出一个人」。要长表演请拆成多个短镜再靠帧链衔接,别写 15 秒以上的单镜;【分辨率决策】草稿/迭代期:WAN 剧 480p(42点/秒最省)、其余 720p;成片交付:seedance 剧 720p(高清档停售)、hailuo-3 剧 1080p(=2K·112点/秒)、WAN 剧 1080p(168点/秒);hailuo-3 无独立 480p 档(选了也按 768P 计费);create_drama/update_project_settings 的 video_engine/video_resolution 设,★都必须在出视频前定——切换不回溯已生成镜头,同剧混用会画风/身份漂移。★图片生成慢≠失败:每张几十秒~数分钟、整集可能十几分钟,轮询 get_storyboards 看 frame_status——pending=还在生成(耐心等、别重复调 generate_frames 白花钱)、ready=完成、failed=才是真失败。★改某一镜画面 / 换定妆图后要让新图生效,走**单镜重生 generate_shot_frame**(平台自动带该镜身份锚·场景道具参考·画风锚,保全片一致);generate_frames 只批量补「缺帧」的镜、已有首帧的镜跳过(正常、不是\"拒绝\")。★首帧出完调免费的 tail_frame_plan 看哪几镜要独立尾帧,再 frame_type=last_frame 批量补。换定妆图(set_character_portrait)后响应里的 stale_frames 就是被旧图污染、需逐镜重生的镜。★绝不用外部工具自制首尾帧再 upload_shot_frame 来\"改画面\"——外部图无身份锚/画风锚,人物·服装·画风必漂,那才是废片根源;upload_shot_frame 只用于客户自有真实素材。③【可选增强·AI 主动提示客户·报价确认才做】美术圣经生成/视觉锁抽取/场景组/口型/海报/音效/配乐/字幕翻译——这些提升一致性/质量、大多收费。★AI 应主动告知客户这些可做并给报价,客户确认才跑;既不默默跳过、也不擅自扣费。★两条锁定纪律:①**画幅比例**在 create_drama 即定、drama 级锁定,之后所有出图/出视频/成片都用它、**别中途改**(改了已生成内容画幅会不一致、漂移);不设默认 9:16。②**拆镜每镜 5-7 秒是对 AI 出视频优化的正常时长**,别因「镜偏长」误判就重拆——generate_storyboards 会**替换整集所有分镜**、已出图白费,已有分镜后端会拦、需 confirm_replace。★改写保真(默认 auto 智能路由):set_script 的原稿**本身已是剧本形态**(场景头/对白行结构)时,rewrite_script 自动走两步保真——客户台词逐句由机器闸锁定(丢一句即内部拒收重做)、AI 绝不加戏;剧作缺口(钩子/情感锚点)不自动补,写进 get_script 返回的 dramaturgy_suggestions 由客户决定采纳。原稿是小说/大纲则自动走创作型改写(AI 铺钩子造情感点),两种客户各得其所、无需手动切换。要覆盖默认用 update_project_settings 的 rewrite_pipeline(auto/two_pass/single_forced)与 fidelity_enforce(1=保真硬闸)。客户说「AI 把我的剧本改偏了」时的处置:①确认完整原稿已进 set_script;②rewrite_pipeline 设 two_pass 强制保真后重跑 rewrite_script;③客户确认角色外观后用 update_character 的 profile_locked=1 锁定档案,防后续提取覆盖外貌导致定妆图换脸。★客户想在**别的 AI 平台**改写剧本(常见诉求:第三方模型评估我方改写\"改动太大\",客户想自己掌控改动幅度):先调 get_script_format_spec 拿平台认可的格式契约(markdown 范本 + 可直接转发给外部模型的 external_prompt + 空白骨架),把 external_prompt+范本+客户原稿一起交给那个平台;拿回整理稿后**先调 check_script_format 自查**(免费·纯规则·不调模型),errors 清零后有两条出口:【A】adopt_external_script 直接落为可拍稿(我方 AI 不介入·秒级·不计费,前提是外部稿含制作层标注);【B】set_script 灌回原稿位 + rewrite_script 走保真两步(外部只做剧情层时选这条,标注由平台补;客户自写的标注在这条路上会被剥掉重写)。★别把外部整理稿塞进 edit_rewritten_script(未跑过改写会被 400 拒),也别跳过 check_script_format 直接灌——格式不合规的稿子进来照样被闸拦,白跑一轮。★★客户交来的**已经是成品分镜表**(逐镜写了秒数/景别/运镜)时,以上两条都不适用——直接用 import_storyboard_table 建分镜,跳过改写与拆镜。走改写那条路会把秒数/景别/运镜/STYLE/文字卡当非剧情内容剥掉(生产实测 8 镜 36 秒→20 镜 109 秒)。★两条导入通道都是确定性的——写错了也会原样建进去,所以**先取契约再自检再导**:分镜表走 get_storyboard_table_spec → check_storyboard_table → import_storyboard_table;客户自己的工具/表格能导出结构化数据、或让外部 AI 直接产 JSON 时走 get_bulk_import_spec → check_bulk_import → bulk_import_storyboards(只建分镜;角色/场景/道具由 extract_assets 从剧本提取,导入按名字绑定已有的——先 extract 再导)。两条导入默认带 auto_complete(后台 AI 补专业字段 + 出图/视频提示词,文本步后付,调用前告知客户):回执 started=true 就用 get_autofill_status 轮询到 done 再 review_storyboards——补全会改镜,先审的 token 会失效。用 get_pipeline_status 查进度(按项目类型返回专属步骤)。",
         "tags": [
           "episodes"
         ],
@@ -8340,7 +8340,7 @@
       "get": {
         "operationId": "get_storyboards",
         "summary": "读某一集的分镜列表(供审阅/查进度)",
-        "description": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
+        "description": "读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。asset_versions 按首帧/尾帧/视频分别给出 generated(已生成)、input_consistent(与当前输入一致)、review_valid(审核有效)、adopted(已采用)、current_effective(当前有效)。null=缺少证据；ready 只表示存在产物，不代表当前有效。旧素材仍可查看。★每镜带**台词与说话人**:dialogue(原文,无台词为 null)、dialogue_lines([{speaker,text}] 逐行,与字幕/配音同一个解析器拆的——这里的 speaker 就是成片里被配音的那个;舞台提示已剥),以及 is_key_moment(1=关键镜,走高端图模)与 emotion_intensity(1-10)。核对「台词有没有丢/谁说的/关键镜是哪几镜/情绪曲线」用这一次调用即可,不用逐镜拉;update_shot 改完台词也在这里核对。画面/视频/首尾帧提示词仍只在 get_shot_prompts 逐镜读。★每镜还带**结构化状态**:frame_status/video_status(ready/pending/authorizing/rejected/failed/none/not_required)、★video_status=ready 只表示视频已生成，不等于画面验收通过。video_quality_issues 若含 terminal_cut：status=suspected 表示片尾疑似短促切镜，cut_at_s/tail_duration_s 给出位置；status=unavailable 表示探测未完成，不能当检测通过。两者均暂停本次自动尾帧回写与续接，先复核视频；字段缺席不代表做过检测，也不要直接重试收费生成。★not_required=旁白/片尾卡镜:帧与视频由成片层渲染,本镜不需要生成——数补齐进度时把它当已完成,别重试。fail_reason(sensitive/text_sensitive/copyright/face_mismatch/account_overdue/quota_full/authorizing/insufficient_credits/transient/repeat_rejected/diagnosis_required/pair_collateral/model_unavailable)、retryable(true=可重试;false=先按fail_hint处理,勿原样重试)、fail_hint(人读文案)。★model_unavailable=所选图片/视频模型的厂商已暂停或暂不可用:fail_hint 里列了当前可用的替代模型(扣没扣费以错误文案为准,别替平台向用户承诺已退款),问用户后用 update_project_settings 改 video_engine/image_model(或只对本镜用 regenerate_shot_video 的 model / generate_shot_frame 的 image_model)再生成,原样重试只会再失败。★diagnosis_required=同输入同细因连败或已有候选等待判决:先查看已有候选及审计依据。审计故障先重审同一候选,原因未知先复核,不得直接改剧本或重复生成。照 retryable 判该重试还是该改内容,别解析中文。★pair_collateral=同镜另一帧未通过、本帧随批结束——**本帧自身没被判不合格,别去改它**:有 reopen_pair_id 就用它只重掷有过错的一侧,否则直接重生本镜。★若某镜带 degraded_frames:[{frame_type,reason,reason_label,since,hint}],表示该帧是系统在同因连拒熔断后**放行**的(判据照记未拒),URL 上与干净帧无区别但需人工复核;不满意按 hint 修正输入后 generate_shot_frame 重生该帧。★terminal_desc_missing=true:该镜标为「状态改变」却三处都没说结束时什么样——**出尾帧前**就能看出来,现在整集一次拿到(此前只有 get_shot_prompts 能逐镜问,一集几十次没人会去问)。先 update_shot 把结束状态写进 last_frame_prompt 再出尾帧:照现状硬出的历史成功率 9.4%,写了终态的 40.2%,而每次被拒都照常扣费。确实该「几乎不变」的镜才用 generate_shot_frame 的 allow_missing_terminal 放行。★first_frame_source/last_frame_source='upload' 表示该帧是**外部上传图**(绕开了身份锚/画风锚/best-of-N/帧审计整条质量链路)——人物·服装·画风漂移排查先看这些镜;外部图导致的漂移不是平台生成质量问题,修复正路是删掉外部图改走 generate_shot_frame 平台重生。★若某镜带 reopen_pair_id:该镜首尾帧同时生成时只有一侧真的有问题、另一侧是无辜陪拒,原样传给 generate_shot_frame 的 reopen_pair_id 参数可以只重掷有问题的那一侧(省一半算力/费用,不会拿去生成一张这次根本没打算重做的图)。没有这个字段就按 fail_reason/retryable 走常规重试。免费。★每镜还带**绑定**(只有 ID):character_ids(本镜绑定的角色)、character_bindings[{character_id,presence}](presence=on_screen 在画面 / voice_only 只有声音、不进画面)、scene_id、prop_ids、active_wardrobe_id(整镜服装)、appearance_wardrobes[{character_id,wardrobe_id}](逐角色服装锚,只列声明了服装的角色)。出图注入谁的定妆图/哪张场景图/哪些道具图由这几项决定;角色名对照 get_characters、道具名对照 get_props。改绑用 update_shot 的 character_ids(★全量覆盖,先从这里读现值再改,漏传即解绑)与 character_presence;改服装用 update_shot 的 active_wardrobe_id / appearance_wardrobes(可覆盖、可传 null 清空);改完再读一次本工具核对。character_bindings 缺席 = 这次没读到(不是没绑),空数组才是没绑。★启用双边版本审核时，seam_review.status 为 passed/failed/not_checked/stale；stale 是证据过期，不是画面失败，不据此付费重生。continuity_intent 可用 update_shot 明确。★每镜带 **seam_state**(本镜与上一镜的镜间接缝,与官网帧时间线同一判据):ok=已续接(首帧就是上镜尾帧,或平台做过首尾帧衔接、已落地且之后两侧都没再重生) / unchained=该连续却没接上(标了连续从没接过,或平台发起的衔接重生没落地:被拒/失败/还在生成——本镜 frame_status 会是 failed/processing;或衔接审过之后本镜首帧又被重生过) / broken=接过但没接上(seam_failed_dims 给出哪几维不连续:characters/wardrobe/props/lighting/scene;seam_audit_status=stale 且没有维度 = 上一镜尾帧在衔接之后又重生过,本镜首帧接的还是旧尾帧) / intended=有意切换(硬切/换场/时间跳跃/景别大跳/插入镜/外部上传帧),不用管 / missing=两侧帧没齐 / unknown=没标意图也没接过(系统没判,不是有问题) / na=首镜或旁白卡。seam_audit_status=pending 表示衔接已落地、平台的衔接审计还没出结论。出视频前只需处理 unchained 与 broken:整集用 chain_frames(先 dry_run),单道用 chain_shot_from_prev / chain_shot_from。",
         "tags": [
           "episodes"
         ],
@@ -9398,7 +9398,7 @@
       "post": {
         "operationId": "apply_wardrobe_timeline",
         "summary": "把客户勾选的换装建议落库(第②步,免费)",
-        "description": "把客户勾选的换装建议落库(第②步,免费)。改的是每镜的 **active_wardrobe_id 结构化绑定**,不是文字描述——这正是「改了 update_shot 的文字却不生效」那个坑的正解。\n★只传客户点头的那几条;一次最多 200 条。\n★多角色同框的镜头单列装不下,那些走 apply_wardrobe_appearances。",
+        "description": "把客户勾选的换装建议落库(第②步,免费)。改的是每镜的 **active_wardrobe_id 结构化绑定**,不是文字描述——这正是「改了 update_shot 的文字却不生效」那个坑的正解。\n★items 只要 {storyboard_id, wardrobe_id}:可以传 build 给的建议(只传客户点头的),也可以**不跑 build、手工指定**(客户点名「这几镜换成这件」时直接传,免得为一次指定花 LLM 的钱)。一次最多 200 条。\n★改单镜、或要**清空**绑定,用 update_shot 的 active_wardrobe_id(传 null 清空);本工具只能设、不能清。\n★多角色同框的镜头单列装不下,那些走 update_shot 的 appearance_wardrobes(或本工具的多角色版 apply_wardrobe_appearances)。",
         "tags": [
           "episodes"
         ],
@@ -9422,7 +9422,29 @@
                 "properties": {
                   "items": {
                     "type": "array",
-                    "description": "build_wardrobe_timeline 给的建议,只放客户勾选的那几条"
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "storyboard_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "本集里的镜头 id"
+                        },
+                        "wardrobe_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "服装资产 id(list_wardrobe 查;必须是本剧的)"
+                        }
+                      },
+                      "required": [
+                        "storyboard_id",
+                        "wardrobe_id"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "minItems": 1,
+                    "maxItems": 200,
+                    "description": "[{storyboard_id, wardrobe_id}]。build 的建议或手工指定都行"
                   }
                 },
                 "required": [
@@ -9464,7 +9486,7 @@
       "post": {
         "operationId": "apply_wardrobe_appearances",
         "summary": "逐角色回填 appearances 的服装绑定(第②步的多角色版,免费)",
-        "description": "逐角色回填 appearances 的服装绑定(第②步的多角色版,免费)。用于**多角色同框**的镜头:单个 active_wardrobe_id 装不下几个人各穿各的,这条按角色逐个绑。同样只传客户勾选的那几条,一次最多 200 条。",
+        "description": "逐角色回填 appearances 的服装绑定(第②步的多角色版,免费)。用于**多角色同框**的镜头:单个 active_wardrobe_id 装不下几个人各穿各的,这条按角色逐个绑。items 可以是 build 的建议,也可以手工指定;一次最多 200 条。\n★它是**补空位**:该角色在这一镜已有服装选择的会被跳过(绝不覆盖);角色在这一镜必须已有出场条目,同一角色在一镜出现两次(同源分身)也跳过。要**覆盖改错的、清空、或给还没有出场条目的已绑定角色设服装**,用 update_shot 的 appearance_wardrobes(逐镜,显式覆盖,wardrobe_id:null 清空)。回执的 skipped/errors 要看。",
         "tags": [
           "episodes"
         ],
@@ -9488,7 +9510,35 @@
                 "properties": {
                   "items": {
                     "type": "array",
-                    "description": "build_wardrobe_timeline 给的建议,只放客户勾选的那几条"
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "storyboard_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "本集里的镜头 id"
+                        },
+                        "character_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "该镜里的角色 id"
+                        },
+                        "wardrobe_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "该角色自己的服装资产 id(list_wardrobe 查)"
+                        }
+                      },
+                      "required": [
+                        "storyboard_id",
+                        "character_id",
+                        "wardrobe_id"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "minItems": 1,
+                    "maxItems": 200,
+                    "description": "[{storyboard_id, character_id, wardrobe_id}]。build 的建议或手工指定都行"
                   }
                 },
                 "required": [
@@ -11134,8 +11184,8 @@
     "/storyboards/{storyboard_id}": {
       "put": {
         "operationId": "update_shot",
-        "summary": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(chara",
-        "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)与画外音标记(character_presence)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids)。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
+        "summary": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)、画外音标记(chara",
+        "description": "逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)、面部表情(expression_hint)、时长(duration)、成片变速(speed_factor)、角色绑定(character_ids)、画外音标记(character_presence)与服装绑定(active_wardrobe_id / appearance_wardrobes)。只传要改的字段、其余不动。★改镜(成功或被拒)都会作废覆盖本镜的未消费报价,生成时回 409 QUOTE_INVALIDATED——先改成功、回读核对,再报价。**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果(每镜带 character_ids / character_bindings / scene_id / prop_ids / active_wardrobe_id / appearance_wardrobes)。★★【换衣服改这里,不是改文字】出图穿什么由**服装绑定**决定:单人镜用 active_wardrobe_id(整镜一件),多人同框各穿各的用 appearance_wardrobes(逐角色)。把「穿某某衣服」写进 description/action 不会换衣服。服装 id 用 list_wardrobe 查;改完不会自动重出图,要让画面跟上需重生本镜首帧再重生视频。★★原声镜(厂商原生音频)改 dialogue 后,本镜视频会被标记「待重生」——因为台词是**烤进视频人声**的,不重生就终拼,成片里念的仍是改动前的台词(典型现象:台词像是跑到了别的镜头上)。compose_episode 会以 advisory `stale_video_after_edit` 列出这些镜;正确处置是先 regenerate_shot_video 再终拼。★也可直接改本镜的四条提示词正文(image_prompt/video_prompt/first_frame_prompt/last_frame_prompt):改前先用 get_shot_prompts 读现值,别凭空覆盖——正文里的 @char:N / @scene:M 是出图时的补充参考标记,照原样保留即可。★注入谁的定妆图由 character_ids 决定、背景由 scene_id 决定:删标记不会让已绑定的人从画面消失,要让某人不出现就改 character_ids,他只有声音(画外音)就用 character_presence 标 voice_only;反过来别给未绑定的角色写 @char 标记——会把他的图注入进来。★★【出尾帧被拦下就是来改这里】出尾帧若报「此镜标为状态改变,但没有任何地方说明结束时是什么样子」(TERMINAL_DESC_GATE),修法是把**结束时画面是什么样**写进本镜 last_frame_prompt,然后重新出尾帧。别去重试出图——这类镜(action_motion_class=state_change 却没写终态)的尾帧历史成功率 9.4%,有终态描述的是 40.2%;不补描述就重生,送厂商的提示词里根本没有终态段,画出来仍和首帧一样、还是会被拒,而每次重生都照常扣费。get_shot_prompts 的 terminal_desc_missing=true 就是这个信号。",
         "tags": [
           "storyboards"
         ],
@@ -11289,6 +11339,46 @@
                       "additionalProperties": false
                     }
                   },
+                  "active_wardrobe_id": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "exclusiveMinimum": 0
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "appearance_wardrobes": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "character_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        "wardrobe_id": {
+                          "anyOf": [
+                            {
+                              "type": "integer",
+                              "exclusiveMinimum": 0
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        }
+                      },
+                      "required": [
+                        "character_id",
+                        "wardrobe_id"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "minItems": 1
+                  },
                   "title": {
                     "type": "string"
                   },
@@ -12670,6 +12760,64 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/rederive-contract": {
+      "post": {
+        "operationId": "rederive_shot_contract",
+        "summary": "按本镜**当前**的正文与角色绑定,让平台重新推导构图契约(画面里可见几人、主体是人物还是局部/道具、景别)",
+        "description": "按本镜**当前**的正文与角色绑定,让平台重新推导构图契约(画面里可见几人、主体是人物还是局部/道具、景别)。契约本身不对外,读不到也改不了;本工具只回结论 outcome:updated(已改并生效)/ unchanged(推出来和原来一样)/ rejected(推出来自相矛盾,未采用,原契约保留)/ no_candidate(没拿到可用结果,原契约保留)/ stale(推导期间本镜又被改过,结果未写入,改完再调一次),附 note 说下一步。点数不足回 402。★什么时候用:出图/预检/审核反复说人数不对、局部镜(手部/道具特写)被当成完整人物出图或审核,而你已经改过正文或绑定——补全器只填空、不覆盖已有契约,不调本工具改动不会进契约。★正确顺序:先 update_shot 把画面写对(谁在画面里、谁只出声音用 character_presence 标 voice_only、不该出现的人从 character_ids 解绑),再调本工具;不改正文直接调多半回 unchanged。★一次文本 AI 调用,按 token 后付(与 autofill_storyboards 同链路),调用前告知客户。★只改契约这一个字段,不碰台词/提示词/其它专业字段;已出的首尾帧不会自动重出,要让画面跟上需对本镜重新出帧(先报价)。★updated 会作废本镜及同集未消费的出帧/出视频报价,之后要重新报价。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "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}/regen/generate": {
       "post": {
         "operationId": "regenerate_shot_video",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.150",
+  "version": "0.1.153",
   "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",